Difference between revisions of "Radiation Monitor Python Script Documentation"

From New IAC Wiki
Jump to navigation Jump to search
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
The Radiation Monitor Python script is a DBus-enabled UDP forwarding and reporting script designed to interpret and rebroadcast the information provided by the Ludlum Measurement Inc. 375-9 series Radiation Monitors in use at the IAC and in the ISU Physics building. It utilizes the common ''iac.nagios.'' DBus service and ''/IAC/Nagios/'' service path for statistic reporting to the IAC [[Monitoring_Server|Nagios]] server.
 
=Configuration And Use=
 
=Configuration And Use=
 +
Before first execution, the following directories will need to be created, with proper permissions for the ''nagios'' user to write to them:
 +
* ''/var/log/iac''
 +
* ''/etc/iac''
 +
These directories will be common for the Radiation Monitoring script as well as the Cluster Room Temperature Monitor script.
 +
 +
Once ''/etc/iac'' exists, you will need to create the ''rad_monitors.cfg'' configuration file within that directory.
 +
The configuration file syntax is described below.
 +
 +
The Radiation Monitor script, if called without a configuration file, uses the following defaults:
 +
* '''Local Address:''' ''None''
 +
* '''Listen Address:''' ''255.255.255.255''
 +
* '''Listen Port:''' ''55555''
 +
* '''Verbose Mode (Non-Daemon):''' ''False''
 +
* '''Debug Mode:''' ''False''
 +
* '''Daemon Mode:''' ''True''
 +
* '''Log Mode:''' ''Append''
 +
* '''Send Clients:''' ''None''
 +
 +
The command to start the Radiation Monitoring script is simply ''rad_monitors.py''. This script will need to be ran by the ''nagios'' user.
 
==Configuration File==
 
==Configuration File==
 
'''Example Configuration File'''
 
'''Example Configuration File'''
Line 11: Line 31:
 
  #nodaemon
 
  #nodaemon
 
  #truncate
 
  #truncate
 +
 +
Lines beginning with # are ignored by the script and may be used for comments on lines seperate from directive lines, or to remove directives from active use. For comments on lines containing directives, please place them at the end and prepend a : before the comment.
 
===Configuration Directives===
 
===Configuration Directives===
 
====local====
 
====local====
 +
This directive will allow you to bind to a specific IP address/interface and port number for purposes of UDP packet source information. By default the program will choose whichever interface is needed to talk to the send clients, as well as a random high port. The proper syntax for this directive is as follows:
 +
'''local''':''local_ip'':''local_port''
 +
This directive cannot be changed during run-time.
 
====listen====
 
====listen====
 +
This directive will allow you to specify what interface/IP address and port to listen for packets on. By default this is set for UDP broadcasts on ''255.255.255.255''. The proper syntax for this directive is as follows:
 +
'''listen''':''listen_ip'':''listen_port''
 +
This directive cannot be changed during run-time.
 +
 
====sendto====
 
====sendto====
 +
This directive will allow you to specify any number of clients to forward the UDP packets on to, one per directive line. The proper syntax for this directive is as follows:
 +
'''sendto''':''target_ip'':''target_port''
 +
Additional send clients can be added while the script is running by sending SIGHUP or using the DBus ''reload_configuration'' method to reload the configuration file, or by using the DBus ''add_send_client'' method.
 +
 
====verbose====
 
====verbose====
 +
This directive sets the Radiation Monitor script into verbose interactive mode (non-daemonized), for the purposes of examining packet flow and diagnostics. This directive needs no arguments and can simply be specified in the configuration file.
 +
 +
This directive cannot be changed during run-time.
 
====debug====
 
====debug====
 +
This directive sets the Radiation Monitor script into a further debugging mode, for program flow and diagnostic purposes.
 +
 +
This directive can be changed during run-time by sending SIGHUP or using the DBus ''reload_configuration'' method to reload the configuration file.
 
====noforward====
 
====noforward====
 +
This directive disables packet forwarding for the Radiation Monitor. This can be useful if you wish to run the script just for listening purposes, or for troubleshooting.
 +
 +
This directive can be changed during run-time by sending SIGHUP or using the DBus ''reload_configuration'' method to reload the configuration file.
 
====nodaemon====
 
====nodaemon====
 +
This directive sets the Radiation Monitor script to run in interactive (non-daemonized) mode, but without verbose output. This can be useful for troubleshooting purposes or if you wish to run the process in a
 +
screen session.
 +
 +
This directive cannot be changed during run-time.
 
====truncate====
 
====truncate====
 +
This directive requires the Radiation Monitor script to clear its log file at each session start, rather than appending (the default log method).
 +
 +
This directive cannot be changed during run-time.
 +
 
=API=
 
=API=
 
==DBus Quick Reference==
 
==DBus Quick Reference==
'''Service Bus''': ''SessionBus()''
+
'''Service Bus''': ''SystemBus()''
  
 
'''Service Name''': ''iac.nagios.radmonitors''
 
'''Service Name''': ''iac.nagios.radmonitors''
Line 35: Line 85:
 
  '''add_send_client('''''string''''')'''
 
  '''add_send_client('''''string''''')'''
 
  '''reload_configuration()'''
 
  '''reload_configuration()'''
 +
 
==DBus Interaction==
 
==DBus Interaction==
 
Before you can interact with the Radiation Monitor's DBus service, you will need to load some prerequisite Python libraries:
 
Before you can interact with the Radiation Monitor's DBus service, you will need to load some prerequisite Python libraries:
Line 45: Line 96:
 
  glib.init_threads()
 
  glib.init_threads()
 
===Connecting to the Radiation Monitor DBus service===
 
===Connecting to the Radiation Monitor DBus service===
To interact with the Radiation Monitor DBus service in Python, you will first need to connect to the DBus Session bus:
+
To interact with the Radiation Monitor DBus service in Python, you will first need to connect to the DBus System bus:
  ''dbus_bus'' = '''dbus.SessionBus()'''
+
  ''dbus_bus'' = '''dbus.SystemBus()'''
Once you have successfully connected to the session bus, you will then want to get the DBus service object for the Radiation Monitor. This is done via the '''get_object''' bus method:
+
'''Note:''' The Radiation Monitor script must be run as ''root'' to connect to the System bus.
 +
 
 +
Once you have successfully connected to the System bus, you will then want to get the DBus service object for the Radiation Monitor. This is done via the '''get_object''' bus method:
 
  ''dbus_object'' = ''dbus_bus''.'''get_object('''''service_name'', ''service_path''''')'''
 
  ''dbus_object'' = ''dbus_bus''.'''get_object('''''service_name'', ''service_path''''')'''
 
For our Radiation Monitor interface, the proper invocation is as follows:
 
For our Radiation Monitor interface, the proper invocation is as follows:
Line 57: Line 110:
 
  >>> remote_method()
 
  >>> remote_method()
 
  dbus.Int32(7)
 
  dbus.Int32(7)
 +
 
===Introspection Schema===
 
===Introspection Schema===
 
The Radiation Monitor DBus service returns the following schema upon being called with its inherited Introspect() method:
 
The Radiation Monitor DBus service returns the following schema upon being called with its inherited Introspect() method:
Line 126: Line 180:
 
This exposed DBus method will cause a running instance of the script to reload its configuration file, as if having been sent signal SIGHUP. It is invoked in the following manner:
 
This exposed DBus method will cause a running instance of the script to reload its configuration file, as if having been sent signal SIGHUP. It is invoked in the following manner:
 
  ''dbus_object''.'''reload_configuration()'''
 
  ''dbus_object''.'''reload_configuration()'''
Then function always returns dbus.Boolean ''True'' at this time.
+
The function always returns dbus.Boolean ''True'' at this time.
  
 
Example output:
 
Example output:
 
  >>> remote_object.reload_configuration()
 
  >>> remote_object.reload_configuration()
 
  dbus.Boolean(True)
 
  dbus.Boolean(True)

Latest revision as of 20:02, 9 March 2011

The Radiation Monitor Python script is a DBus-enabled UDP forwarding and reporting script designed to interpret and rebroadcast the information provided by the Ludlum Measurement Inc. 375-9 series Radiation Monitors in use at the IAC and in the ISU Physics building. It utilizes the common iac.nagios. DBus service and /IAC/Nagios/ service path for statistic reporting to the IAC Nagios server.

Configuration And Use

Before first execution, the following directories will need to be created, with proper permissions for the nagios user to write to them:

  • /var/log/iac
  • /etc/iac

These directories will be common for the Radiation Monitoring script as well as the Cluster Room Temperature Monitor script.

Once /etc/iac exists, you will need to create the rad_monitors.cfg configuration file within that directory. The configuration file syntax is described below.

The Radiation Monitor script, if called without a configuration file, uses the following defaults:

  • Local Address: None
  • Listen Address: 255.255.255.255
  • Listen Port: 55555
  • Verbose Mode (Non-Daemon): False
  • Debug Mode: False
  • Daemon Mode: True
  • Log Mode: Append
  • Send Clients: None

The command to start the Radiation Monitoring script is simply rad_monitors.py. This script will need to be ran by the nagios user.

Configuration File

Example Configuration File

#local:134.50.87.179:55554
listen:255.255.255.255:55555
sendto:127.0.0.1:54321
#sendto:134.50.87.179:54321
#verbose
#debug
noforward
#nodaemon
#truncate

Lines beginning with # are ignored by the script and may be used for comments on lines seperate from directive lines, or to remove directives from active use. For comments on lines containing directives, please place them at the end and prepend a : before the comment.

Configuration Directives

local

This directive will allow you to bind to a specific IP address/interface and port number for purposes of UDP packet source information. By default the program will choose whichever interface is needed to talk to the send clients, as well as a random high port. The proper syntax for this directive is as follows:

local:local_ip:local_port

This directive cannot be changed during run-time.

listen

This directive will allow you to specify what interface/IP address and port to listen for packets on. By default this is set for UDP broadcasts on 255.255.255.255. The proper syntax for this directive is as follows:

listen:listen_ip:listen_port

This directive cannot be changed during run-time.

sendto

This directive will allow you to specify any number of clients to forward the UDP packets on to, one per directive line. The proper syntax for this directive is as follows:

sendto:target_ip:target_port

Additional send clients can be added while the script is running by sending SIGHUP or using the DBus reload_configuration method to reload the configuration file, or by using the DBus add_send_client method.

verbose

This directive sets the Radiation Monitor script into verbose interactive mode (non-daemonized), for the purposes of examining packet flow and diagnostics. This directive needs no arguments and can simply be specified in the configuration file.

This directive cannot be changed during run-time.

debug

This directive sets the Radiation Monitor script into a further debugging mode, for program flow and diagnostic purposes.

This directive can be changed during run-time by sending SIGHUP or using the DBus reload_configuration method to reload the configuration file.

noforward

This directive disables packet forwarding for the Radiation Monitor. This can be useful if you wish to run the script just for listening purposes, or for troubleshooting.

This directive can be changed during run-time by sending SIGHUP or using the DBus reload_configuration method to reload the configuration file.

nodaemon

This directive sets the Radiation Monitor script to run in interactive (non-daemonized) mode, but without verbose output. This can be useful for troubleshooting purposes or if you wish to run the process in a screen session.

This directive cannot be changed during run-time.

truncate

This directive requires the Radiation Monitor script to clear its log file at each session start, rather than appending (the default log method).

This directive cannot be changed during run-time.

API

DBus Quick Reference

Service Bus: SystemBus()

Service Name: iac.nagios.radmonitors

Service Path: /IAC/Nagios/RadMonitors

Exposed Methods

get_active_channels()
get_active_monitors()
get_active_monitor_count()
get_radiation_levels()
add_send_client(string)
reload_configuration()

DBus Interaction

Before you can interact with the Radiation Monitor's DBus service, you will need to load some prerequisite Python libraries:

import dbus

This is the minimum to connect to DBus. If you wish to do more than connect as a client, you will need to load the following libraries:

import dbus.service, gobject
from dbus import glib

It is also recommend that you initialize threading now if you are planning on performing threaded tasks:

gobject.threads_init()
glib.init_threads()

Connecting to the Radiation Monitor DBus service

To interact with the Radiation Monitor DBus service in Python, you will first need to connect to the DBus System bus:

dbus_bus = dbus.SystemBus()

Note: The Radiation Monitor script must be run as root to connect to the System bus.

Once you have successfully connected to the System bus, you will then want to get the DBus service object for the Radiation Monitor. This is done via the get_object bus method:

dbus_object = dbus_bus.get_object(service_name, service_path)

For our Radiation Monitor interface, the proper invocation is as follows:

dbus_object = dbus_bus.get_object("iac.nagios.radmonitors", "/IAC/Nagios/RadMonitors")

After this is done, you may choose to call the Radiation Monitor's DBus methods either through the service object itself, or you may create references to specific methods for use:

dbus_method_ref = dbus_object.get_dbus_method(method, service_name)

Example:

>>> remote_method = remote_object.get_dbus_method('get_active_monitor_count', 'iac.nagios.radmonitors')
>>> remote_method()
dbus.Int32(7)

Introspection Schema

The Radiation Monitor DBus service returns the following schema upon being called with its inherited Introspect() method:

<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN"
"http://www.freedesktop.org/standards/dbus/1.0/introspect.dtd">
<node name="/IAC/Nagios/RadMonitors">
  <interface name="iac.nagios.radmonitors">
    <method name="reload_configuration">
    </method>
    <method name="get_active_monitors">
    </method>
    <method name="get_active_monitor_count">
    </method>
    <method name="add_send_client">
      <arg direction="in"  type="v" name="new_client" />
    </method>
    <method name="get_radiation_levels">
    </method>
    <method name="get_active_channels">
    </method>
  </interface>
  <interface name="org.freedesktop.DBus.Introspectable">
    <method name="Introspect">
      <arg direction="out" type="s" />
    </method>
  </interface>
</node>

Methods

get_active_channels

This exposed DBus method will return a dbus.Array value representing the active channels the script sees. It is invoked in the following manner:

dbus_object.get_active_channels()

Example output:

>>> remote_object.get_active_channels()
dbus.Array([dbus.Int32(1), dbus.Int32(2), dbus.Int32(3), dbus.Int32(4), dbus.Int32(5), dbus.Int32(6), dbus.Int32(7)], signature=dbus.Signature('i'))

get_active_monitors

This exposed DBus method will return a dbus.Array value representing the IP address of all radiation monitors the script sees. It is invoked in the following manner:

dbus_object.get_active_monitors()

Example output:

>>> remote_object.get_active_monitors()
dbus.Array([dbus.String(u'192.168.40.155'), dbus.String(u'192.168.40.154'), dbus.String(u'192.168.40.121'), dbus.String(u'192.168.40.172'),
dbus.String(u'192.168.40.137'), dbus.String(u'192.168.40.159'), dbus.String(u'192.168.40.120')], signature=dbus.Signature('s'))

get_active_monitor_count

This exposed DBus method will return a dbus.Int32 value representing the total number of active monitors the script sees. It is invoked in the following manner:

dbus_object.get_active_monitor_count()

Example output:

>>> remote_object.get_active_monitor_count()
dbus.Int32(7)

get_radiation_levels

This exposed DBus method will return a dbus.Array value representing the current radiation level of all monitors the script sees. It is invoked in the following manner:

dbus_object.get_radiation_levels()

Example output:

>>> remote_object.get_radiation_levels()
dbus.Array([dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.0'), dbus.String(u'0.1'), dbus.String(u'0.1'),
dbus.String(u'0.1')], signature=dbus.Signature('s'))

add_send_client

This exposed DBus method will add a new send target client to a running instance of the script, allowing for on-the-fly addition of targets without restarting. It is invoked in the following manner:

dbus_object.add_send_client(string)

Where string is a string containing the IP address and destination port number of the send target, formatted as "ip:port". The function returns a dbus.Boolean value; True if the add is successful, False if not.

Note: This only adds the new send client to the in-memory send list. If you wish to retain this send client for future use, you will need to edit the configuration file and add the appropriate sendto directive for that client.

Example output:

>>> remote_object.add_send_client("134.50.87.179:55555")
dbus.Boolean(True)

reload_configuration

This exposed DBus method will cause a running instance of the script to reload its configuration file, as if having been sent signal SIGHUP. It is invoked in the following manner:

dbus_object.reload_configuration()

The function always returns dbus.Boolean True at this time.

Example output:

>>> remote_object.reload_configuration()
dbus.Boolean(True)