pandorafms/pandora_doc/en/man/pandora_agents

.TH Pandora Agents

.SH NAME

pandora_agents - Agents for PandoraFMS

.SH AVAILABILITY

Linux, AIX, Solaris, Windows...

.SH DESCRIPTION

This is the man page for Linux Pandora Agents.

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 man describes the installation of agents in machines running over Linux operating systems.

.SH SYPNOSIS

.B 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 fifiles 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.

.B Main Script

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 fifile. In machines running over UNIX the main script is run
through a special script called pandora_agent_daemon, and runs continuously in the machine as a
process.

.B Configuration File

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

.I General parameters

 Configure general options about server location, agent name, interval, and other general options.

.I Module definitions

Configure and defined the method of extraction for each piece of information that will be extracted from local host and sent to Pandora Server.

.B 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:
.I 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: /opt/pandora/data_in.
.I   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).

.I 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 flcoding 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 /opt/pandora/data_out

.I 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.

.I debug:

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

.I 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.

.I 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.

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

.I     server_ip Pandora_Server
.br
.I     server_path /opt/pandora/data_in
.br
.I     temporal /opt/pandora/data_out
.br
.I     interval 300
.br
.I     agent_name satellite_agent
.br 
.I     debug 1
.br
.I     checksum 1

.B 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.

.I  module_begin

Defines the beginning of the module.

.I 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 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.

.I module_type type

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

.TP

Numeric (generic_data). 

Simple numeric data, flfloat or integer. If the values are of the float type, they will be truncated to their integer value.

.TP
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.

.TP•
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.

.P
.I 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.

.I 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. It is created automatically when working on learning mode.

.I 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.

.I 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.

.I module_interval factor

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).

.I module_end

Ends module definition

.B 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.

.B UNIX agents

.I Introduction to Unix agents

The in-built UNIX applications and tools make the agents running on this system be very simple. There
are also agents developed for AIX, Linux, Solaris and BSD platforms, some of them very similar but not
identical. Requirements for the installation of Pandora Agents on UNIX
.I AIX

MD5 signatures are used to guarantee the integrity of the generated data packages. The MD5 package is
integrated in AIX 5.1 and above. There is a freeware package for AIX 4.3 but it has several issues and
might not work correctly. In the case of having problems with the AIX agents the checksum system used
to validate the integrity of the data can be disabled.

.I Solaris

The MD5 package is necessary to execute the Solaris agent correctly. This package is available from
http://sunfreeware.com . It can be also downloaded for Solaris 8 from the following URL:

ftp://ftp.sunfreeware.com/pub/freeware/sparc/8/md5-6142000-sol8-sparc-local.gz
MD5 Package installation on Solaris

.I        root@stest:/tmp:> gzip -d md5-6142000-sol8-sparc-local.gz
.br
.I         root@stest:/tmp:> pkgadd -d ./md5-6142000-sol8-sparc-local
.br
.I          The following packages are available:
.br
.I          1 SMCmd5           md5
.br
.I          (sparc) 6142000
.br
.I          Select package(s) you wish to process (or ’all’ to process
.br
.I          all packages). (default: all) [?,??,q]: 1
.br
.I Solaris SSH

The suggested SSH client is OpenSSH. If any other SSH client is to be used it must be considered that
each piece software may have different ways to generate or manage keys. For example, if F-Secure SSH
is used, the public key must be in OpenSSH format when the keys are generated. The format can be
changed from IETF to OpenSSH with F-Secure SSH, using the following command:

.I ssh-keygen -i -f file_ietf_pubkey

.B GNU/Linux

SSH and MD5 should be installed in Linux by default, but if they are not they can be installed using the
tools available in each distribution.

.B BSD (IPSO)

SSH and MD5 should be installed by default. If they are not, it is necessary to install them.

.B Pandora Unix Agent install

The software comes in a .tar.gz file. First of all the fifile needs to be extracted into a folder, usually
/opt/pandora_agent, although any other folder may be used. If a different folder is used, the daemon
launcher must be modified by changing route to $PANDORA_HOME.

There is hardly any difference between AIX, Solaris and Linux, and they all work around the hash MD5
generation binaries.

This is the structure of the installation in /opt/pandora_agent/ once the fifiles have been extracted:

.I /opt/pandora_agent/data_out

Folder where the data collected by the agents is stored.

.I /opt/pandora_agent/doc

Folder with information about the agent and its license.

.I /opt/pandora_agent/pandora_agent.conf

File where the data to be collected is defined, along side the command to be executed for the data collection. This is the system core, as it defines the main
data to be collected in any Firewall.

.I /opt/pandora_agent/pandora_user.conffi

File where several of the parameters to collect data from the monitored system are defined in more detail.

.I /opt/pandora_agent/pandora_agent.sh 

This is the actual Pandora agent. This file is a shellscript that collects the data configured in the pandora_agent.conf and pandora_user.conf files. It also transfers
the data packages to the Pandora server.

.I /opt/pandora_agent/pandora_agent_daemon

Start and stop script. It makes a call to pandora_agent.sh. It offers two options, start and stop.

.I /opt/pandora_agent/pandora.log

Textfifile where the activity of the Pandora agent is saved, when the agent is executed in debugging mode.

.B Key generation

The SSH keys generated must be:

  SSH version2 keys
•
  Open SSH format keys
•
  DiffieHellman (DH) format keys

•
To generate the keys the command ssh-keygen is executed followed by the specific parameters for our
operating system. Please, create key WITHOUT password.

The public key must be copied into the /home/.pandora/authorized_keys fifile in the Pandora
server. Before starting the Pandora agent the SSH authentication must be checked. To do this the
following command must be executed on the agent machine:

.I         $ ssh pandora@pandora_server

The system must connect successfully BEFORE launching the Pandora agent.

.B First running of the Unix agent

To start the agent it is only necessary to execute pandora_agent_daemon start from /opt/pandora_client.
Pandora Agent creates a file (/var/run/pandora.pid) with the PID number of the process when it is started.

For IPSO systems the agent will be started with a nice -10 priority, so it becomes the process with the
lowest priority over the system CPU. It will be executed when no other processes with a higher priority
are waiting in the system CPU queue.

In BSD systems the maximum priority is +20 and the lowest -20.

To stop agent, execute pandora_agent_daemon stop from /opt/pandora_agent.

.B Advanced configuration for Unix Agent

The real power of Pandora resides in the capability of the agents to run user defined scripts. This could
be used to collect specific data or to perform an operation to return any desired value. This is the purpose
of pandora_user.conf.

This file is executed every in agent loop. It is a shell-script in which any command can be executed, as
long as the output is in the XML format the agent uses to send data to the server. The XML structure
would be:

.I         <module>
.br 
.I        <name>NAME</name>
.br 
.I        <type>TYPE</type>
.br
.I         <data>DATA</data>
.br
.I        </module>

Where NAME, TYPE and DATA are the variables already defined in previous sections. The XML must
be built manually, usually using echo commands.

.SH EXAMPLES

An example of a Unix module would be:

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

This would be the script a customized agent would use for Checkpoint FW1 in IPSO agents:

.I #!/bin/sh
.br
.I # Pandora User-Defined acquisition script
.br
.I # This code is under GPL licence
.br 
.I # Please refer documentation for more example and a more
.br
.I # depth usage instructions
.br
.I # mbuf clusters usados (%)
.br
.I MBUF_TOTAL=‘netstat -m |grep "mbuf cluster" | tr -s "/" " " |awk ’{ print $2 }’‘
.br
.I MBUF_USED=‘netstat -m |grep "mbuf cluster" | tr -s "/" " " |awk ’{ print $1 }’‘
.br
.I MBUF_USED_PER=‘echo $MBUF_TOTAL $MBUF_USED | awk ’{ print $2 / ($1 / 100) }
.br
.I echo  "<module>"
.br
.I echo  "<name>MBUF_CLUSTER_USED_PER</name>"
.br
.I echo  "<data>$MBUF_USED_PER</data>"
.br
.I echo  "<type>generic_data</type>"
.br
.I echo  "</module>"

A more complex example could be:

.I #!/bin/sh
.br
.I # Pandora User-Defined acquisition script
.br
.I # This code is under GPL licence
.br
.I # Please refer documentation for more example and a more
.br
.I # depth usage instructions
.br
.I # Calculating the number of packages generated by ETH2,
.br
.I # if nothing is generated
.br
.I # within 20 seconds an alert is rosen
.br
.I # Perform the calculation between 8 to 23h. Return ok for times
.br
.I # outside this range
.br
.I echo "<module>"
.br
.I echo "<name>Packet_Generator_Check</name>"
.br
.I echo "<type>generic_proc</type>"
.br
.I UNO=‘ifconfig eth2 | grep "TX packets" | cut -f 2 -d ":" | grep -o -e "[0-9]*"‘
.br
.I sleep 20
.br
.I DOS=‘ifconfig eth2 | grep "TX packets" | cut -f 2 -d ":" | grep -o -e "[0-9]*"‘
.br
.I HORA=‘date "+%k"‘
.br
.I if [ "$HORA" -lt "8" ] && [ "$HORA" -gt "11" ]
.br
.I then
.br
.I # Time out of range, no checking, everything OK
.br
.I # Fuera de hora, no compruebo, esta OK
.br
.I   echo "<data>1</data>"
.br
.I else
.br
.I if [ "$UNO" == "$DOS" ]
.br
.I then
.br
.I        echo "<data>0</data>"
.br
.I  else
.br
.I      echo "<data>1</data>"
.br
.I  fi
.br
.I fi
.br
.I  echo "</module>"

.B Implementation examples for Unix Agents

Example #1: calculate the number of HITS of the main page of an Apache Web server:

.I      module_begin
.br
.I      module_name WEB_Hits
.br
.I      module_type generic_data_inc
.br
.I      module_exec cat /var/log/apache/access.log | grep "index" | wc -l
.br
.I      module_end

Example: check if the process of the DNS server (named) is active or fell over:

.I      module_begin
.br
.I      module_name DNS_Daemon
.br
.I      module_type generic_proc
.br
.I      module_exec ps -Af | grep named | grep -v "grep" | wc -l
.br
.I      module_end

Complete example of the configuration of an agent for Linux
      # General Parameters
      # ==================
.I      server_ip         192.168.100.45
.br
.I      server_path /opt/pandora/data_in
.br
.I      pandora_path /opt/pandora_ng/
.br
.I      temporal           /opt/pandora_ng/data_out
.br
.I      interval           300
.br
.I      hostname linuxbox01
.br
.I      debug       0
.br
.I      checksum 1

# Module Definition
# =================
.I module_begin
.br
.I module_name cpu_user
.br
.I module_type generic_data
.br
.I module_exec vmstat 1 2 | tail -1 | awk ’{ print $14 }’
.br
.I module_end

.I module_begin
.br
.I module_name cpu_sys
.br
.I module_type generic_data
.br
.I module_exec vmstat 1 2 | tail -1 | awk ’{ print $14 }’
.br
.I module_end

.I module_begin
.br
.I module_name disk_root_free
.br
.I module_type generic_data
.br
.I module_exec df -kh / | tail -1 | awk ’{ print 100 - $5 }’
.br
.I module_end

.I module_begin
.br
.I module_name disk_store_free
.br
.I module_type generic_data
.br
.I module_exec df -kh /store | tail -1 | awk ’{ print 100 - $5 }’
.br
.I module_end

.I module_begin
.br
.I module_name memfree
.br
.I module_type generic_data
.br
.I module_exec cat /proc/meminfo  | grep MemFree | cut -c 10-23
.br
.I module_end

.I module_begin
.br
.I module_name memused
.br
.I module_type generic_data
.br
.I module_exec cat /proc/meminfo | grep "Active"  | cut -c 8- | cut -f 1 -d "k"
.br
.I module_end

.I module_begin
.br
.I module_name proctotal
.br
.I module_type generic_data
.br
.I module_exec ps -A | wc -l
.br
.I module_end

.I module_begin
.br
.I module_name sshd
.br
.I module_type generic_proc
.br
.I module_exec ps -Af | grep sshd | grep -v "grep" | wc -l
.br
.I module_end

.I module_begin
.br
.I module_name WEB_Hits
.br
.I module_type generic_data_inc
.I module_exec cat /var/log/apache/access.log | grep "index.php" | wc -l
.br
.I module_end

.I module_begin
.br
.I module_name eMails_proc
.br
.I module_type generic_data_inc
.br
.I module_exec cat /var/log/mail/mail.log | grep "message-id" | wc -l
.br
.I module_end

.I module_begin
.br
.I module_name FTP_sessions
.br
.I module_type generic_data_inc
.br
.I module_exec cat /var/log/syslog | grep "FTP session opened" | wc -l
.br
.I module_end

.I module_begin
.br
.I module_name eMails_SPAM
.br
.I module_type generic_data_inc
.br
.I module_exec cat /var/log/mail/mail.log | grep "identified spam" | wc -l
.br
.I module_end

.SH AUTHOR

Pandora Free Monitoring System is made and copyrighted by Sancho Lerena <sancho.lerena@artica.es>
Pandora is a project initiated and mainly developed by Sancho Lerena, at present other people is working
on it: Raul Mateos, David Villanueva, Esteban Sanchez, Jose Navarro, Jonathan Barajas and Manuel Arostegui We want to
thank many other people who help us with translation, graphic design, bugs reporting and interesting
ideas.
.br


.SH SEE ALSO

.B pandora
.br
.B pandora_server
.br
.B pandora_agents
.br
.B pandora_console