pandorafms/pandora_agents/README.unix

Pandora FMS Agents
==================

Understanding what is a Pandora FMS Agent
-----------------------------------------

Pandora FMS agents collect all system's data. They are executed in each local
system, although they can also collect remote information by installing
monitoring systems for the agent in several different machines - called
satellite agents.

They are developed to work under a given platform, making use of the specific
tools of the language being used: VBSCript/Windows Scripting for Microsoft
platforms (Win2000, WinXP y Win2003), ShellScripting for UNIX - which includes
Linux, Solaris, AIX, HP-UX and BSD, as well as the Nokia's IPSO. Pandora agents
can be developed in virtually any language, given its simple API system and
being open source. There are branches of the Pandora project started for the
creation of agents in Posix C, Perl and Java for those systems requiring closed
agents.

Pandora Agents are Free Software, i.e., the way agents collect and sent
information is documented. An agent can be recreated in any programming
language, and can be upgraded easily, to improve aspects of the program not
covered so far.

This document describes the installation of agents in machines running over
Windows and Unix operating systems.

Generic role of the agents
--------------------------

Regardless the platform an agent is running on, this is formed of the following
elements:

A script (or binary application in Windows) that collects and sends the data to
the server. For UNIX machines the script is called pandora_agent.sh and is
executed directly from the Pandora agent folder.

One or several configuration files where the values to be collected are defined.
The file is called pandora_agent.conf both for Windows and Unix machines.

This simple structure makes it easy the customisation of an agent. There is no
need to code again the agent to modify the way it works, as the configuration
file holds most of the parameters needed to do so.

Pandora FMS Agent configuration
------------------------------

Main program
~~~~~~~~~~~~

The main script is the executable file that collects the data specified in the
configuration file. It sends the data to the server in XML. In Windows machines
application is installed as a service and is executed at the time intervals set
in the configuration file. In machines running over UNIX the main script is run
through a special script called pandora_agent, and runs continuously in the
machine as a process.

Configuration File
~~~~~~~~~~~~~~~~~~

The data collection in the host system is the gathering of independent data
units, which are defined in the /etc/pandora/pandora_agent.conf file. The
pandora_agent.conf file is divided in two parts:

    * General parameters: Configure general options about server location, agent
name, interval, and other general options.

    * Module definitions: Configure and define the method of extraction for each
piece of information that will be extracted from local host and sent to Pandora
Server.

General parameters
~~~~~~~~~~~~~~~~~~

The general parameters of the agent configuration are defined in this section.
Some of these parameters are common for all systems and others specific for
Windows or UNIX. The general parameters are:

    * server_path: The server path is the full path of the folder where the
server stores the data sent by the agent. It is usually
/var/spool/pandora/data_in.

    * server_ip: The server IP is the IP address or the host name of the Pandora
server, where the data will be stored. The host must be reachable and must be
listening to port 22 (SSH).

    * temporal: This is the full path of the folder where the agent stores the
data locally, before it is sent to the server. It must be said that the data
packages are deleted once the agent tries to contact Pandora server, no matter
if the communication was successful or not. This is done to avoid over flooding
hard drive of the host system where the agent runs. The location of the local
folder varies with the architecture of the host system. In Unix systems this is
usually /var/spool/pandora/data_out, and in Windows systems C:\program
files\pandora\data_out.

    * interval: This is the time interval in seconds in which the agent will
collect data from the host system and send the data packages to the server. The
recommended value ranges from 300 (5 minutes) to 600 (10 minutes). This number
could be larger, although it is important to consider the impact of a larger
number on the database.

    * debug: This parameter is used to test the generation of data files,
forcing the agent to do not copy data file to server, so you can check data file
contents and copy XML data file manually. It does not delete any data when the
process is finished, so data file will be in temp directory. The activity is
written in a log file. The file is named pandora_agent.log. This log file can be
used to test the system and to investigate potential issues.

    * agent_name: This is an alternative host name. This parameter is optional
as if it is not declared the name is obtained directly from the system.

    * checksum: This parameter can take two values. If the value is 1, the
checksums are performed through MD5. If the value is 0, the checksum is not
performed at all. This may be useful for systems where a MD5 tool cannot be
implemented. If the checksum is deactivated in the agent it must be also
disconnected in the server. Otherwise it could create problems.

    * Transfer Mode: This parametrer let you specify which transfer mode is
going to be set up to send the agent data to the server. Modes available are:
ssh (using scp), ftp or local. Local mode it is only for systems where the agent
run in the same machine as the server does, cause it is basically a copy between
directories.

	* ftp_password: Specify password for FTP transfer mode (Windows only).
	
    * encoding: Set the encoding type of your local system, like iso-8859-15, or
utf-8.

    * Pandora Nice: This parametrer let you specify the priority the Pandora
Agent process will have in your system.

An example of the general parameters from a Unix configuration would be:

     server_ip    192.168.12.12
     server_path  /var/spool/pandora/data_in
     temporal     /var/spool/pandora/data_out
     interval     300
     agent_name   dakotaSR01
     debug 	   0
     checksum     0

Module definition
-----------------

Each data item that is to be collected must be defined precisely in each module,
using the exact syntax. As many values as necessary can be set to be collected,
adding at the end of the general parameters as many modules as the number of
values to collect. Each module is made of several directives. Following is a
descriptive relation of all module marks available for Unix agents (almost all
of them are applicable to Windows Agent too).


module_begin

Defines the beginning of the module.

module_name <name>

Name of the module. This is the id for this module, choose a name without blank
spaces and not very long. There is no practical limitation (max of 250 chars)
but will be more easier to manage if you use short names. This name CANNOT be
duplicated with a similar name in the same agent. This name could be duplicated
with other modules in other agents.

module_type <type>

Data type the module will handle. There are four data types for agents:

    * Numeric (generic_data). Simple numeric data, float or integer. If the
values are of the float type, they will be truncated to their integer value.

    * Incremental (generic_date_inc). Integer numeric data equal to the
differential between the actual value and the previous one. When this
differential is negative the value is set to 0.

    * Alphanumeric (generic_string). Text strings up to 255 characters. 

    * Monitors (generic_proc). Stores numerically the status of the processes.
This data type is called monitor because it assigns 0 to an "Incorrect" status
and any value above 0 to any "Correct" status.

module_exec <command>

This is the generic "command to execute" directive. Both, for Unix and Windows
agents there is only one directive to obtain data in a generic way, executing a
single command (you could use pipes for redirecting execution to anoter
command). This directive executes a command and stores the returned value. This
method is also available on Windows agents. This is the "general purpose method"
for both kind of agents.

For a Windows agent there are more directives to obtain data, who are described
following this lines.


module_service <service>

(Win32 Only)

Checks if a given service name is running in this host. Remember to use " "
characters if service name contains blank spaces.


module_proc <process>

(Win32 Only)

Checks if a given processname is running in this host. If the process name
contains blank spaces do not use " ". Also notice that the process name must
have the .exe extension. The module will return the number of process running
with this name.

module_freedisk <drive_letter:>

(Win32 Only)

Checks free disk on drive letter (do not forget ":" after drive letter).

module_cpuusage <cpu id>

(Win32 Only)

Returns CPU usage on CPU number cpu. If you only have one cpu, use 0 as value.

module_freememory

(Win32 Only)

Return free memory in the whole system.

module_min <value>

This is the minimum valid value for the data generated in this module. If the
module has not yet been defined in the web console this value will be taken from
this directive. This directive is not compulsory. This value does not override
the value defined in the agent if the module does not exist in the management
console is created automatically when working on learning mode.

module_max <value>

It is the maximum valid value for the data generated in this module. If the
module has not been defined in the web console this value will be taken from
this directive. This directive is not compulsory and is not supported by the
Windows agent. This value does not override the value defined in the agent if
the module does not exist in the management console. This is created
automatically when working on learning mode.


module_description <text>

This directive is used to add a comment to the module. This directive is not
compulsory. This value does not override the value defined in the agent if the
module does not exist in the management console. This is created automatically
when working on learning mode.


module_interval <factor>

Since Pandora 1.2 introduces this new feature. You can, for each module, setup
its own interval. This interval its calculated as a multiply factor for agent
interval. For example, if your agent has interval 300 (5 minutes), and you want
a module only be calculated each 15 minutes, you could add this line:
module_interval 3. So this module will be calculated each 300sec x 3 = 900sec
(15 minutes).


module_end

Ends module definition


Examples

An example of a Windows module, checking if EventLog service is alive, would be:

       module_begin
       module_name ServicioReg
       module_type generic_proc
       module_service Eventlog
       module_description Eventlog service availability
       module_end

An example of a Unix module would be:

       module_begin
       module_name cpu_user
       module_type generic_data
       module_exec vmstat | tail -1 | awk '{ print $14 }'
       module_min 0
       module_max 100
       module_description User CPU
       module_end


Agent types
===========

It is possible to monitor virtually any system with Pandora. This can be done
either with a local agent collecting data directly from the system to be
monitored, using a a satellite agent collecting data from a system by SNMP or
using the new Pandora 1.2 agents, the remote agents, who can chack using remote
network polling (TCP, UCP, ICMP/PING and SNMP) remote services, from the Pandora
Network Server.

The local agents can be either Windows or Unix agents. The satellite agents can
be implemented using any of the agents above. The modules are configured to
collect data from the external system by, for example, an SNMPGET tool.


Quick Install Guide for Pandora FMS UNIX AGENTS 1.3
===================================================

Installing Pandora FMS Agent for unix
-------------------------------------

Untar agent tarball, for example at /tmp/pandora_agent

As root, execute command line installer:

    ./pandora_agent_installer --install

This should install your agent, setup permissions and place files in their
respective locations:

    root@blackbox01:/tmp/pandora/pandora_agents/linux# ./pandora_agent_installer
--install

    Pandora FMS Agent Installer 1.0 (c) 2007 Sancho Lerena
    This program is licensed under GPL2 Terms. http://pandora.sourceforge.net

    Checking default dir /usr/share/pandora_agent...
    Checking Pandora FMS Agent on /usr/bin/pandora_agent....
    Creating Pandora FMS Agent home directory at /usr/share/pandora_agent ...
    .
    .
    
    Creating logfile at /var/log/pandora_agent.log...
    Copying Pandora FMS Agent to /usr/bin/pandora_agent...
    You have your startup script ready at /etc/init.d/pandora_agent_daemon
    First you need to copy your public SSH keys (/home/slerena/.ssh/id_dsa)
    under /home/pandora/.ssh/authorized_keys on your Pandora FMS Server host
    You also need to setup your /etc/pandora/pandora_agent.conf config file

Setup SSH authentication
------------------------

Due that Pandora FMS agent connect by SSH you need to setup SSH keys now. You
also can use FTP method by using .netrc file, but it's much more secure and
better to use SFTP with SSH2).

Probably you want to run Pandora FMS agent under root privileges to grab system
data. It's possible that you don't need to run as root to collect data you need,
in that case, procedure are the same, but using another user.

Create ssh keys using DSA type for key:

	ssh-keygen -t dsa

And reply as follows to questions (enter to all questiosn):

	Generating public/private dsa key pair.
	Enter file in which to save the key (/root/.ssh/id_dsa):
	Created directory '/root/.ssh'.
	Enter passphrase (empty for no passphrase):
	Enter same passphrase again:
	Your identification has been saved in /root/.ssh/id_dsa.
	Your public key has been saved in /root/.ssh/id_dsa.pub.
	The key fingerprint is:
	xx:xx:xx:xx:xx:xx:xx:xx:xx:2d:68:30:f7:53:2d:7e

You need to add your PUBLIC key (/root/.ssh/id_dsa.pub) to
/home/pandora/.ssh/authorized_keys file in each Pandora FMS data server you want
to use with this agent.

Login to Pandora FMS data server, and add the key on
/home/pandora/.ssh/authorized_keys file. You could use cut and paste, for
example, or copying file with scp or ftp from one system to another. Take care
of carriage returns. Public key "appearance" is like as:

  ssh-dss AAAAB3NzaC1kc3MAAACBAMR4WOOvuT3UyZPKC/NcqBuduB/H8oKF2LRv52LX88YNO
  kgdIPNOat+NeweCuQdVOaDUNvFTgnyYV6iBtApstzUl6ndKALZlDoZnBYULYTUtBF+cdRHq7v
  n0bufIMRHFpg8ZvqR3dBulz6bVQqJu8nqZGQDyLgPEmkQ6O9 root@blackbox01

The entire block MUST BE in a SINGLE LINE, if not, don't work. Also,
/home/pandora/.ssh/ directory and /home/pandora/.ssh/authorized_keys in server,
should have "pandora" user ownership and permissions set to 700 for directory
and 600 for authorized_keys file.

For example, if you have copied id_dsa.pub to /tmp in server system:

	cat /tmp/id_dsa.pub >> /home/pandora/.ssh/authorized_keys
	chmod 600 /home/pandora/.ssh/authorized_keys
	chmod 700 /home/pandora/.ssh/
	chown -R pandora /home/pandora/

Image:Warning.png Warning! Setting up SSH authentication is a mess due ANY step
you missed, makes auth to fails, so please don't skip nothing


Always test this connection to check that SSH authentication is working. From
your agent system, where Pandora FMS agent is running, try to contact Pandora
FMS server:

	ssh pandora@server_ip

First time a hostkey authentication changenge should show you something like:

	The authenticity of host 'xxxxx (x.x.x.x)' can't be established.
	RSA key fingerprint is 42:d4:a5:f2:a7:b8:1f:c3:d5:42:ab:c7:b5:5b:af:57.
	Are you sure you want to continue connecting (yes/no)?     
	
Reply yes, and you should see the system prompt for user pandora, WITHOUT asking
for password, because SSH automatic authentication, based on DSA Keys, should
work and resolve authentication. If not, try to review previous steps. Note that
if you're using scponly protection, shell don't be available, but authentication
will be correct.

If you have serious problems and get stuck, try to setup maximun verbosity of
SSH Daemon on System running Pandora FMS server:

	vi /etc/ssh/sshd_config

Replace LogLevel INFO for LogLevel DEBUG2

Restart ssh

	/etc/init.d/ssh restart

Now you have MUCH MORE information about SSH problems. In debian this
information is at /var/log/auth.log. Dont forget to set again LogLevel INFO in
your sshd_config and restart again SSH, or too much loggin will be generated
(and performance penalty).
 Configure Pandora FMS agent

Your config file is at /etc/pandora/pandora_agent.conf, edit it and setup that
variables:

    * server_ip: put IP address of your Pandora FMS data server
    * debug: set it to zero to not use debug mode. 

Rest of parameters could be default values.

Check out some of the default modules to have an idea of your agent will do and
what kind of information will report to Pandora FMS data server. This could be
modified in any time (restarting agent).

Run your Pandora FMS unix agent
-------------------------------

First to need to create your agent in your Pandora FMS console as described in
"new agent" procedure (but you don't need to create network modules), only
create an agent with the SAME name that have your system. After creating agent
in console, you could launch agent:

    /etc/init.d/pandora_agent_daemon start

If you have problems, a good idea is restart Pandora FMS agent manually to check
errors in startup:

    pandora_agent /etc/pandora