Usage
=====

SANET Poller is a single daemon that reads SANET's database and checks 
periodically all the defined Targets and Measures.

Remember that in order to execute the Poller properly the enviroment 
variable SANET_HOME must contain the path to the SANET's installation 
directory.


Run as daemon
-------------

Poller is meant to run as a *daemon* process. In this mode, only log
informations are available to the user. See the :ref:`anchor-log-management` sections 
for details.


Start and Stop
^^^^^^^^^^^^^^

To start the poller launch the command::

	etc/rc.sanet pstart


By default, the poller runs as a daemon process.

To stop the poller process launch::

	etc/rc.sanet pstop

You can launch the poller by hand with the following commands::

	python poller/main.py start

	python poller/main.py stop

Poller PID file
^^^^^^^^^^^^^^^

When the poller starts as a daemon process it writes the Process ID inside the 
file::

	var/poller_pid

When Poller is stopped the file is deleted.

*NOTE*: You should not modify this file by hand!

No daemon mode
^^^^^^^^^^^^^^

The poller can be executed as a normal process with the option '-n' (not 
daemon)::

	python poller/main.py -n start

	python poller/main.py stop


.. _anchor-log-management:

Log management
--------------

Poller supports several logging options in order to provide a very 
customizable logging system.

Logging Level
^^^^^^^^^^^^^

The amount of log messages and their verbosity depends on a numeric
value called *severity level*. Only messages with a severity level
equal or greater than the current severity level will be reported.

Poller's logging level can be changed with the '-L' option::

	python poller/main.py -L <value> start

The *value* can be either a numeric constant or one of the
following mnemonic strings::

    CRITICAL 50
    ERROR    40
    WARNING  30
    INFO     20
    DEBUG    10
    NOT SET   0

Poller's default level is set to INFO.

You should not run the Poller with logging level <= INFO in 
production environments.


The var/poller_log log file
^^^^^^^^^^^^^^^^^^^^^^^^^^^

This is the default log file. The Poller never erases the content 
of this file. New log messages are always appended at the end of 
the file.

The growth rate of this file depends on the logging level used by 
the current running instance of the Poller. 


Logging on stdout
^^^^^^^^^^^^^^^^^

Specify the -v option in order to print log messages on standard 
output.

This is useful only when the Poller is executed with the -n (no 
daemon mode) option. ::

	python poller/main.py -v -n start

Logging on syslog
^^^^^^^^^^^^^^^^^

Specify the -p option in order to print log messages throw the
syslog system::

	python poller/main.py -p start

Logging on separated directories
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Poller runs perfrom several checks at the same time by using several 
thread of execution. 
You can save a different log for every thread in separeted files with 
the -l option::

	python poller/main.py -l  /tmp/temp_dir  start

Inside the specified directory Poller will create a different log 
file for every check perfomed.



Performing single tests
-----------------------

The purpose of the options reported below is for debug only.
You should not check and/or update single Targets and Measures manually.

Test a target
^^^^^^^^^^^^^

To check a single target use the -c option::

	python poller/main.py -c <target path>

	python poller/main.py -c <target id number>

In order to check and update a single target use the -C option::

	python poller/main.py -C <target path>

	python poller/main.py -C <target id number>


Test a measure
^^^^^^^^^^^^^^

To check a single measure use the -m option::

	python poller/main.py -m <measure path>

	python poller/main.py -m <measure id number>

In order to check and update a single measure use the -M option::

	python poller/main.py -M <target path>

	python poller/main.py -M <target id number>

Test an expression
^^^^^^^^^^^^^^^^^^

Use the -e option::

	python poller/main.py -e <host>  <expression string>

The program will read from standard input the addional parameters required for the
expression evaluation and then compute the expression.

Example::

	$ echo | python poller/main.py -e foo  ' (1 + 1) / 2'
	VALUE:  1.0 ( <type 'float'> )
	INFO :  (1 + 1) / 2 expands to ((1 + 1) / 2)

If *host* is registered as a SANET Node, additional symbols will be available:

	* $node	= the host name (string)
	* $snmpversion = SNMP version (number)
	* $community = SNMP community (string)
	* $snmpport = SNMP port (number)

The input data passed to the program throw standard input must have the following syntax::

	<symbol> [ '='  <type> ] '='  <value>

The <type> parameter is optional:

	* <symbol> : Must be a valid expression variable (es: $foo)
	* <type>   : Must be a valid type-string: "num", "string". Default is: "string".
	* <value>  : The symbols' value. It will be converted

Example::

 	foo@localhost$ cat | python poller/main.py -v -L DEBUG -e localhost '1.3.6.1.2.1.1.1.0@'
	$snmpversion = num = 1
	$community = public
	$snmpport = num = 161 
	*Cltr+D*

	VALUE:  Linux mason 2.4.34.5 #12 Tue Jun 26 14:09:29 CEST 2007 i686 ( <class 'poller.SnmpExprParser.Types.SnmpValueType'> )
	INFO :  1.3.6.1.2.1.1.1.0@ expands to Linux mason 2.4.34.5 #12 Tue Jun 26 14:09:29 CEST 2007 i686


See the  :mod:`functions`  section in the Development documentation for more informations about
available functions.

Verify adjacency
^^^^^^^^^^^^^^^^

TODO


Periodic clean up
-----------------

If SANET database is based on the Postgress backend, the following command must
be executed periodically::

	/etc/rc.d/rc.sanet nightly

This command will stop Poller, garbage-collect/analyze the database and then
restart Poller.


Performance tuning
------------------


Number of thread
^^^^^^^^^^^^^^^^

The number of threads running inside the Poller is variable and 
can be specified  with the option -T::

	python poller/main.py -T <number> start

There is system-dependent limit to the number of running threads. 
In general,  the  number of thread can not be greater then the 
number of DB connection  your DBMS can handle at the same time.

Because of Poller operations are IO bound, you should use a number
of thread as great as possibile.

Site parameter
^^^^^^^^^^^^^^

TO DO


Thread stack size
^^^^^^^^^^^^^^^^^

You can controll the size (in Kbs) of the stack python will allocate
for every thread created by the Poller.

	python poller/main.py -S 64 start

The minimun stack size value is system dependent. A stack size
of 64kb should work on every system.