Difference between revisions of "Pandora: Documentation en: Configuration"

From Pandora FMS Wiki
Jump to: navigation, search
(module_exec)
(No difference)

Revision as of 13:37, 27 November 2012

Go back Pandora FMS documentation index

Contents

1 Pandora FMS configuration

Pandora FMS has three basic components that should be configured for a correct operation. The two first ones are the server and the web console, that should interact between them and the data base to could introduce, process and show the stored data. There are also the software agents that send the data to the Pandora FMS server.

In this chapter we are going to explain the configuration files of the three elements and also other elements that are important for a correct performance of the application components.

1.1 Server

Pandora FMS server has a configuration file that allows to adjust several application parameters to obtain an excellent performace. The configuration file pandora_server.conf is located in a predetermined way at directorio /etc/pandora/.

1.1.1 Configuration File Elements

Pandora FMS configuration file is a UNIX standard plain text where the variables that aren't used or the comments are preceded by a "#" character

Next we are going to explain all the configuration parameters.


1.1.1.1 servername

Pandora FMS server name. If it is commented, then we should use the name of the equipment or "host". Please do not change the name of the server after executing it first time because all references goes linked to the name (remote agent modules, and other information). If you change it, you should re-assign the server to all your agents.

1.1.1.2 incomingdir

XML data packages Incoming Directory. By default is /var/spool/pandora/data_in/. You can improve performance by setting up a RAM disk or fast disk here.

1.1.1.3 log_file

Pandora FMS record file (log). By default is /var/log/pandora/pandora_server.log. This is the main logfile, very important for debuggin.

1.1.1.4 snmp_logfile

Logfile of SNMP console of Pandora FMS. By default is /var/log/pandora/pandora_snmptrap.log. This is a log file with SNMP traps received BEFORE Pandora FMS server process it, you should not touch or edit this file.

1.1.1.5 errorlog_file

Pandora FMS error registry file (log). By default is /var/log/pandora/pandora_server.error. This logfile stores all non-controlled errors or non captured output from tools executed by the server, also important to find problems and debugging.

1.1.1.6 dbname

Name of database the server will connect to. By default is pandora.

1.1.1.7 dbuser

Username used in the Pandora database connection. By default is "pandora".

1.1.1.8 dbengine

Engine running the database (oracle, postgres or mysql). Mysql by default.

1.1.1.9 dbpass

Password for the connection against Pandora FMS Database

1.1.1.10 dbhost

Ip address or equipment name that host the Pandora FMS database. In reduced installations it is usually the same equipment where the server is, that is localhost.

1.1.1.11 dbport

(Optional) Used to define a different port in your Database setup.

1.1.1.12 daemon

Shows if the Pandora server is executed as demon or not. If the server is launched with the option –D, then it is also executed as demon.

1.1.1.13 verbosity

Detail level for the server and error messages, the register or log files. 0 is the predetermined one, 1 is the detailed, 2 is debugging, 3-10 noisy. When you have any problem with Pandora FMS put this value to 10 to get the maximun detail. High values here (like 10) are not intended to use in production because they have a great performance impact.

1.1.1.14 master

1 Say that is a master server, 0 that is an slave server that is part of a multiple server configuration (for HA environment, go to "HA" documentation chapter for more information).

1.1.1.15 snmpconsole

1 Shows that the SNMP traps reception console is activated in the configuration.0 that it is not. The console depends on snmptrapd UNIX service. Before starting Pandora FMS server, please check snmptrapd process IS NOT running in your server.

1.1.1.16 networkserver

1 Shows that Pandora FMS network server is activated in the configuration. 0 that it is not.

1.1.1.17 dataserver

1 Shows that Pandora FMS data server is activated in the configuration. 0 that it is not. This server process the XML files coming from the agents, but do more tasks, so you should have this server always running in your system.

1.1.1.18 reconserver

1 Shows that Pandora FMS network recon server is activated in the configuration. 0 that it is not. If you don't want to use the reconserver, it's better to disable it.

1.1.1.19 pluginserver

1 Shows that Pandora FMS complement server is activated in the configuration.0 that it is not.

1.1.1.20 predictionserver

1 Shows that Pandora FMS prediction server is activated in the configuration.0 that it is not .

1.1.1.21 wmiserver

1 Shows that the Pandora FMS server of WMI is activated in the configuration.0 that it is not .

1.1.1.22 inventoryserver

(Pandora FMS Enterprise only)

1 Shows that Pandora FMS remote inventory server is activated in the configuration.0 that it is not. The inventory data sent by the agents are processed with the data server and there is no need to activate the remote inventory server.

1.1.1.23 exportserver

(Pandora FMS Enterprise only)

1 Shows that the Pandora FMS export server is activated in the configuration.0 that it is not.

1.1.1.24 webserver

(Pandora FMS Enterprise only)

1 To activate the checking WEB(webserver or also known as Goliat Server).0 that it is not.

1.1.1.25 eventserver

(Pandora FMS Enterprise only)

Enables (1) or disables (0) the event correlation server (1 by default).

1.1.1.26 icmpserver

(Pandora FMS Enterprise only)

Enables (1) or disables (0) the Enterprise ICMP server (0 by default). The Enterprise ICMP server uses Nmap to perform block ICMP requests. The XML output of older versions (5.0 or previous) of Nmap does not report round-trip time. If all your ICMP latency modules return 0, set this configuration variable to 0.

1.1.1.27 snmpserver

(Pandora FMS Enterprise only)

Enables (1) or disables (0) the Enterprise SNMP server (0 by default). The Enterprise SNMP server uses an external utility called braa to perform block SNMP queries. Modules that can't be processed by braa will be marked as not-initialized and will be handled by the Network server. If you experience additional problems with braa simply set this configuration variable to 0.

1.1.1.28 network_timeout

Is the timeout -in seconds- for the network server connections on network ICMP modules. Default value is 2 seconds. If you are doing remote checks on WAN networks, you probably should increase this value to avoid false results.

1.1.1.29 server_keepalive

Time before classify the server as down. In seconds. By default its value is 45.

1.1.1.30 server_threshold

The number of seconds of the main loop, in seconds. By default its value is 5. This is a very important configuration token because it defines how many times Pandora FMS search in database or disk for new data to process. From 5 to 10 is a good value for most cases, minimum value is 1, and if you set to 1, system CPU will be very high. You can set 1 on specific situations like, when your server has been down for a while and you need to process the pending XML files and Network modules as quick as system can. Set this to 1, wait to be finish processing all pending modules/XML, and set again to 5 - 15. This value, used in conjuntion with *server*_theads and max_queue_files are used to adjust the performance of your server.

1.1.1.31 network_threads

Number of threads for the network server. Shows how many checks can be done at the same time, but as it increases it needs much more processing capacity. Its predetermined value is 5. Do not use more than 20 - 25 threads or the system could get inestable or have poor performance.

1.1.1.32 icmp_checks

Defines the pings number to each icmp_proc kind of module. At least one of these ckecks must give back 1 to the module could be classified as correct. Its predetermined value is 1. If you set 5 here, and the first ping it's OK, the other 4 are skipped.

1.1.1.33 tcp_checks

Number of TCP reattempts if the first one fails. The predetermined value is 1.

1.1.1.34 tcp_timeout

Specific timeout for TCP connexions. The predetermined value is 30.

1.1.1.35 snmp_checks

Number of SNMP reattempts if the first one fails. The predetermined value is 1.

1.1.1.36 snmp_timeout

Specific expiration time for the SNMP connexions. The predetermined value is 3.

1.1.1.37 snmp_proc_deadresponse

Gives back DOWN if it is not possible to connect with a boolean SNMP module (proc) or if it gets NULL.If it is set to 0 then it should be ignored.

1.1.1.38 plugin_threads

Number of threads for the complement server. Shows how many checks could be done at the same time.Its predetermined value is 3.

1.1.1.39 plugin_timeout

Timeout for the checks with complements.After this time the module state will be shown as unknown. Its predetermined value is 5. Probably you need to raise this value. If a plugin has a higher value, the value used is this, instead the plugin value.

1.1.1.40 wmi_timeout

WMI checks timeout.After this time the module state will be shown as unknown. Its predetermined value is 10.

1.1.1.41 wmi_threads

Number of threads for the WMI server. It shows how many checks could be done at the same time. Its predetermined value is 2.

1.1.1.42 prediction_threads

Number of threads for the prediction server.

1.1.1.43 recon_threads

Number of threads for the network recon server. Shows how many checks could be done at the same time. Its predetermined value is 2.

1.1.1.44 dataserver_threads

Number of threads for the dataserver. Shows how many threads of the XML file processor are at the same time. Its predetermined value is 2.

1.1.1.45 inventory_threads

(Pandora FMS Enterprise only)

Number of threads assigned to the remote inventory server. It shows how many simultaneous threads are assigned to this component.

1.1.1.46 export_threads

(Pandora FMS Enterprise only)

Number of threads assigned to the export server. It shows how many simultaneous threads are assigned to this component.

1.1.1.47 web_threads

(Pandora FMS Enterprise only)

Number of threads assigned to the WEB test server. It shows how many simultaneous threads are assigned to his component.

1.1.1.48 mta_address

Mail Server IP address (Mail Transfer Agent)

1.1.1.49 mta_port

Mail server port (by default 25)

1.1.1.50 mta_user

Mail server user (if necessary for use with authentication)

1.1.1.51 mta_pass

Password for the mail server (if necessary with authentication)

1.1.1.52 mta_auth

Mail server authentication system( if necessary; the valid values are: LOGIN PLAIN CRAM-MD5 DIGEST-MD)

1.1.1.53 mta_from

Mail address from the mails will be send. In a predetermined way is [email protected].

1.1.1.54 xprobe2

If it is given, is used to discover the operating system of the remote systems assigned to the agents,when a recon network task is launched. The predetermined path is /usr/bin/xprobe2. If is not provided, NMAP will be used instead, but it's much more imprecise.

1.1.1.55 snmpget

Needed for SNMP checks. In a predetermined way it is at /usr/bin/snmpget. It refers to the location for the snmp standard client of the system. It is recommended not to touch it unless you know exactly what are you doing.

1.1.1.56 nmap

Needed for the recon server.In a predetermined way is at /usr/bin/nmap.It is recommended not to touch it unless you know exactly what are you doing.

1.1.1.57 plugin_exec

Shows the absolute path to the program that execute the plugins in a controlled way in time. By default /usr/bin/timeout, and it is recommend not to touch unless you know exactly what are you doing. If your base system doesn't have timeout, you should change to use /usr/bin/pandora_exec instead.

1.1.1.58 autocreate_group

Numeric id of the predetermined group for the new agents created with the data server through the datafile reception.The default value is 2.

1.1.1.59 autocreate

If you put 1 then agents will be self-created when XML files are received for which there would be no agents. Is it is set to 0 they will not be created and you will need to create an agent first (case sensitive!).

1.1.1.60 max_log_size

Maximum size of Pandora FMS register file, in bytes. When this size is got, then the file should be moved topandora_server.log.old and go on working on the original one. The predetermined size is 65536Bytes.

1.1.1.61 max_queue_files

Maximum number of XML datafiles from the directory that contains them will be not read. To avoid overload the system. Although the directory don't be read it doesn't means that the files are not read and that they continue being processed. The default value is 250.

1.1.1.62 use_xml_timestamp

Deactivated by default. If it is activated (value 1) use the XMLfile timestamp, generated with time and date of the server in the moment of the reception of it, instead of the timestamp that the XML file has internally and that was generated by the server. This is useful to deactivate globally the use of the dates generated by the agents and use the date/hour (timestamp)of the server as a reference for all data. In systems with problems with synchronization, systems with wrong date/hour, it's an option that could solve almost all problems.

1.1.1.63 auto_restart

Deactivated by default. If it is activated (value in seconds), it forces the server to do an internal restart each X seconds (1 day = 86400). This option is useful if you observe degradation or lost of control of any thread or specific server of Pandora FMS.

1.1.1.64 restart

By default 0. If set to 1 the server will restart on critical errors after a given number of seconds.

1.1.1.65 restart_delay

By default 60. Number of seconds the server will wait before restarting after a critical error if restart is enabled.

1.1.1.66 self_monitoring

The server has a self monitoring flag, that creates a virtual agent in the server that monitors most of the important parameters of a Pandora FMS serve. To activate it the parameter self_monitoring must be set to 1.

1.1.1.67 update_parent

Also the sever has now (v3.1) a parameter to define if the agent can update it's parent by sending the parent name on the XML, if this parameter is not defined or is 0 the agent information is ignored, if not, when the server receives an XML with parent_name attribute, searches for an agent with this name and if it's found updates the parent of the agent from the XML.

1.1.1.68 icmp_threads

(Pandora FMS Enterprise only)

Number of threads for the ICMP Enteprise server (3 by default).

1.1.1.69 snmp_threads

(Pandora FMS Enterprise only)

Number of threads for the Enteprise SNMP server (3 by default).

1.1.1.70 block_size

(Pandora FMS Enterprise only)

Block size for block producer/consumer servers, that is, the number of modules per block (15 by default).

1.1.1.71 braa

(Pandora FMS Enterprise only)

Location of the braa binary needed by the Enterprise SNMP server (/usr/bin/braa by default).

1.1.1.72 event_window

(Pandora FMS Enterprise only)

Event window: It's the time window (in seconds) inside which the event server will look for events. For example, if set to 3600 the event server will check events generated in the last hour.

1.1.1.73 wmi_client

Default wmi client used (wmic by default). You should not change this.

1.1.1.74 activate_gis

Flag to activate GIS (positional information for agents and maps) by default it is desactivated

1.1.1.75 location_error

Radius of error in meters to consider two gis locations as the same location.

1.1.1.76 recon_reverse_geolocation_mode

Recon reverse geolocation mode [disabled, sql, file]

  • disabled The recon task doesn't try to geolocate the ip discovered.
  • sql The recon task trys to query the SQL database to geolocate the ip discovered
  • file The recon task trys to find the geolocation information of the ip discovered in the file indicated in the recon_reverse_geolocation_file parameter

1.1.1.77 recon_reverse_geolocation_file

Recon reverse geolocation file. This is the database with the reverse geolocation information using MaxMind GPL GeoLiteCity.dat format).

1.1.1.78 recon_location_scatter_radius

Radius (in meters) of the circle in where the agents will be place randomly when finded by a recon task. Center of the circle is guessed by geolocating the IP.

1.1.1.79 google_maps_description

This enable realtime reverse geocoding using Google Maps public api. This requires internet access, and could have performance penalties processing GIS information due the connetion needed to resolve all GIS input. NOTE: If you dont pay the service to google, they will ban your IP in a few days.

1.1.1.80 openstreetmaps_description

This enable realtime reverse geocoding using Openstreet Maps public api. This requires internet access, and could have performance penalties processing GIS information due the connetion needed to resolve all GIS input. You can alter the code to use a local (your own) openstreet maps server.

1.1.2 Snmptrapd configuration

Pandora FMS SNMP Console uses snmptrapd to grab SNMP traps. Snmptrapd is a standard tool, present on almost all UNIX systems, to grab traps and write a logfile. Pandora FMS configures snmptrapd to write a custom logfile and reads it every x seconds, executing alerts if defined.

Previously, snmptrapd will accept all incoming notifications, and log them automatically (even if no explicit configuration is provided). Starting with 5.3 release, access control checks will be applied to incoming notifications.

If snmptrapd is run without a suitable configuration file (or equivalent access control settings), then such traps will not be processed.

Probably you will need to configure your snmptrapd using the file /etc/snmp/snmptrapd.conf. If doesn't exist, check /var/log/pandora/pandora_snmp.log file for warnings or errors.

A basic snmptrapd.conf could be like:

authCommunity log public

If doesn't work on your linux distribution, please check your version syntax to enable the reception of traps in your snmptrapd daemon with

man snmptrapd.conf

1.1.3 Tentacle Configuration

By default, Pandora FMS software agents send the data packages to the server through the Tentacle protocol (port 41121/tcp assigned by IANA [1]). The agent could also be reconfigured to it send data through alternative ways: local transfer (NFS,SMB),SSH or FTP, etc. IF you want that they send the data packages through Tentacle protocol, then we should have to configure a Tentacle server where this data will be received. By default, when a Pandora FMS server is installed, a Tentacle server is also installed in the same machine.

If it would be necessary to adjust some parameters of the Tentacle server configuration, then it could be done modifying directly the script that launches the Tentacle Server daemon that is in:

/etc/init.d/tentacle_serverd

Next, there is a list of the different options for Tentacle Server configuration:

PANDORA_SERVER_PATH

Path to the entry directory of data. In a predetermined way is /var/spool/pandora/data_in

TENTACLE_DAEMON

Tentacle daemon. In a predetermined way is tentacle_server.

TENTACLE_PATH

Path to the Tentacle binary. In a predetermined way is /usr/bin.

TENTACLE_USER

User the Tentacle demon will be launched with. In a predetermined way is pandora.

TENTACLE_ADDR

Direction to listen the data packages. If you fix 0.0.0.0. it will be listened in all of them. In a predetermined way it is listen in all directions, this is , its value is 0.0.0.0.

TENTACLE_PORT

Listening port for the packages reception. By default it's 41121 (official port assigned by IANA).

TENTACLE_EXT_OPTS

Additional options for executing the Tentacle server. Here you can setup Tentacle to use authentication with certs (x509) and/or simmetric password in both sides.

Simple file transfer with password authentication (not secure):

Extra parameters in the tentacle server setup

 -x password

Extra parameters in the client side (TENTACLE_EXT_OPTS)

 -x password

Secure file transfer without client certificate:

Extra parameters in the tentacle server setup

 -e cert.pem -k key.pem 

Secure file transfer with client certificate:

Extra parameters in the tentacle server setup

 -e cert.pem -k key.pem -f cacert.pem

Extra parameters in the client side (TENTACLE_EXT_OPTS)

 -e cert.pem -k key.pem 

Secure file transfer with client certificate and password authentication:

Extra parameters in the tentacle server setup

 -x password -e cert.pem -k key.pem -f cacert.pem

Extra parameters in the client side (TENTACLE_EXT_OPTS)

 -x password -e cert.pem -k key.pem

1.2 WEB Console

Pandora FMS web console has a configuration file that usually is created and configured when it's installed.If the installations is done through the DEB or RPM packages or from the Pandora FMS installation CD, then it is configured in an automatic way.If it is installed in a manual way,with the tarball package. It could be configured from the web assistant through http://ip_instalacion_consola/pandora_console/install.php

The configuration file config.php is at the directory/include/ in the console installation directory, that could be /var/www/pandora_console (Debian, Ubuntu) or /srv/www/htdocs/pandora_console/ (SUSE, RH, Fedora...), depending on the distribution.

1.2.1 Configuration file config.php

The configuration options in the file are in the header of it, and are these:

$config["dbname"]

Database name to connect to . In a predetermined way is pandora.

$config["dbuser"]

User name for the connexion against the Pandora database. In a predetermined way is pandora.

$config["dbpass"] Password for the conexion against Pandora FMS database.

$config["dbhost"]

Ip adress or equipment name that host Pandora FMS database. In reduced installation usually it is the same equipment where the server is, this is, localhost.

$config["homedir"]

Directory where the Pandora FMS web console is. It usually is /var/www/pandora_console o /srv/www/htdocs/pandora_console.

$config["homeurl"]

Base directory for Pandora FMS. It usually is /pandora_console.

$config["public_url"]

The full url is set with the string value, the value is the URL of inside PandoraFMS server when you use a inverse proxy for example mod_proxy of Apache.

1.2.1.1 Redirection to /pandora_console from /

If you only has one Pandora FMS in your Apache server, then, it's possible that you could benefit by readdressing automatically /pandora_console when users connect with the URL of their server. To do this, you could create the following file index.html and put it in the web server root directory (/var/www ó /srv/www/htdocs):

When users connect with the URL / of their server. For it you can create the following file index.html and put it in the web server root directory

 <html>
 <head>
 <meta HTTP-EQUIV="REFRESH" content="0; url=pandora_console/index.php">
 </head>
 </html>

1.3 Pandora FMS software agents

1.3.1 What is an Agent ?

Pandora FMS software agents collect all data from the systems. They are executed in each local system, but they also can collect remote information through the monitoring systems installation for the agent in several different machines.

They are developed to work with a fixed platform, using the specific tools of the language that is used:VBSCript/Windows scripting for Microsoft platforms (Windows 2000, Windows XP, Windows 2003 y Windows Vista), ShellScripting for UNIX-includes GNU/Linux, Solaris, AIX, HP-UX y BSD, and also the Nokia IPSO. The Pandora FMS agents could be developed in any language, as long as it would be a system with an easy API and that it would be open code. There are modalities of the Pandora FMS project that has been started for the agents creation in Posix C, Perl and Java for those systems that require closed agents.

Pandora FMS are 100% open code, for example in the way the agents collect and send information is documented and could analyze and/or modify the code for it could suit to your needs. An agent could be created again in any programing language and could be easily updated to improve aspects of the program that had been cover completely.

This document describes the agent installation in machines that work with the Windows and UNIX operative systems.

1.3.1.1 Software Agents Generic Role

The Software Agents generic role is based on obtaining information about the operative system in which them are installed, collect this information and then send it to the server.

Pandora FMS software agents use the specific commands of the operative system in order to obtain the information.Pandora FMS data server keeps and processes the data generated by these commands and sent to the server in an XML file.

The information returned by these commands is kept in what is called «Module». f the agent has been added in «learning» mode, the modules that have been sent and that are not defined previously in the logical agent will be created automatically by the server.

1.3.2 Introduction to the agent configuration

The agent is controlled by an unique configuration file that has a syntax that is almost the same in UNIX systems and in Windows Systems, this file is named pandora_agent.conf and is located in the agent installation directory(in Windows Systems) and in /etc/pandora/pandora_agent.conf in Unix systems.

This configuration file is a plain file text with different options that could be modify by the administrator, to modify the performance or it, configure where data will be send, which things will monitor and how it will do.

Template warning.png

Configuration file encoding it's very important and must be the same that value set in encoding configuration parameter. If encoding is set properly we will avoid to receive data with wrong encoding characters

 


Next we talk about the general parameters for the Software agent and the monitoring modules that are the ones that define how and what is monitored locally with the Software Agent.

1.3.3 Agent General Parameters

The Configuration of Agent General Parameters is defined in this section. Some of them are commons for all systems and others are specifics for Windows or Unix. The general parameters are:

1.3.3.1 server_ip

Is the IP address or the name of Pandora FMS server host, where all data will be kept. The server must be prepared to collect the data either by SSH (listening on port 22), Tentacle (port 41121), FTP (port 21), SMB or NFS.

1.3.3.2 server_path

The server path is the comprehensive file path where the server keeps all data sent by agent.Usually it is /var/spool/pandora/data_in.

1.3.3.3 temporal

This is the complete path of the folder where the agent keeps data locally before sending to the server.

Please consider that the data packages, by default,they are deleted once the agent tries to contact with the Pandora FMS server, not taking in account if the connection was successful or not ( though this performance could be changed, as we see later).

This is done to prevent an overload in the hard disc of the host system where the agent runs. The location of the local file changes depending on the architecture of the host system. In UNIX system is usually at n /var/spool/pandora/data_out, and in the Windows systems C:\program files\pandora_agent\temp.The Windows installer by default will create this directory depending on where decides to install Pandora FMS.

And in Windows systems the Windows installer will create this directory by default, depending on where it decides to install Pandora FMS.

1.3.3.4 description

Send the description of the agent in the XML and Pandora FMS imports this description when it creates the agent.

1.3.3.5 group

Send the name of the group we want the agent owns, and that is only used at creating the agent. Pandora FMS server will automatically use this group to put the agent in the selected group.

1.3.3.6 temporal_min_size

If the free space (at mega bytes) of the partition in which the temporary directory is located is smaller that this value, then it would continue generating data packages. In this way, it avoids that the disk would become full if under any circumstance the connexion with the server is lost during an extended interval.

1.3.3.7 logfile

The path to the Pandora FMS agent events record file. The file could be used to check the system and to investigate other things.

1.3.3.8 interval

This is the time interval "in seconds" in which the agent will collect data from the host system and will sent the data packages to the server. The ranks of recommended values are, from 300 (5 minutes) to 600 (10 minutes).This number could be greater, but it's important to consider the impact of a higher number in the database. The execution is not recommended if it's below 30-60 seconds.

1.3.3.9 debug

This parameter is used to check the creation of data in the files, forcing the agent to not copy data from files for the server, so the data content of the files could be checked and also copy the XML files data manually. No data is destroyed when the process has been done, so the data of the files will be at the temporary directory. The activity is registered in the registry file. The registry file is pandora_agent.log (see logfile above).

1.3.3.10 agent_name

This is an alternative name for the host. This parameter is optional so this has not been declared but obtained directly from the system. The parameter could be used to overwrite the host name for another one in case of a conflict.

1.3.3.11 address

This is the IP addres of the software agent. Could be an IP addres with the format X.X.X.X, a domain name as 'localhost', or 'auto'. If is an IP addres or a domain name, this will be added to the addresses of the agent and will be established as main address. If is 'auto', it will obtain the IP addres from the host and will be added to the agent as the previous case.

1.3.3.12 encoding

Install the kind of codification of the local system, such as iso-8859-15, or utf-8. This option is available for the UNIX and Windows agents from Pandora FMS 2.0.

1.3.3.13 server_port

This parameter allows to identify the remote port of the server that is waiting. By default it is 41121 for Tentacle. In case that Tentacle is not used or that the server would be installed in other port, is here where it should be changed.

1.3.3.14 transfer_mode

This parameter specifies the transfer mode we have to install in order send the agent data to the server. The available modes are SSH (using SCP), Tentacle, FTP o local. The local mode is only for systems where the agent is executed in the same machine that the server, because it is basically an copy between directories. The local mode is available only for GNU/Linux agents.

1.3.3.15 server_pwd

Specific for the password of Windows FTP and for the Tentacle transference mode, although the password at the last one is optional. Server password for authentication with password.

1.3.3.16 server_ssl

Specific for the Tentacle transfer mode. Allows to authorize (1) or deny(0) the connexions encrypt through SSL.

1.3.3.17 server_opts

Specific for the Tentacle transfer mode. Allows to give additional parameters to the Tentacle client for advanced configurations. They should be between "" (for example,"-v-r 5").

Coming with 3.2 agent version, tentacle supports optional use of a HTTP proxy (using CONNECT) mode to send information to server. This is implemented using an advanced option, like this:

server_opts -y user:pass[email protected]:8080

This will force tentacle client to use proxy.inet at port 8080 using "user" and "pass" for authentication, if you want to use a proxy in 192.168.1.2 with port 9000 without credentials, will be:

server_opts -y 192.168.1.2:9000

1.3.3.18 delayed_startup

This parameter allows to configure the Pandora FMS agent in order it start working after any specific time (in minutes) after having executed it manually. It could be useful for systems with a lot of load packages. By default it is deactivated, this is, the Pandora FMS agent will start to work from the moment it will be executed manually. This option is only valid for UNIX agents.

1.3.3.19 pandora_nice

This parameter allows to specify the priority that the Pandora FMS agent process will have in the system. It is only available for Unix/Linux agents.

1.3.3.20 autotime

If it is enabled (1) send a timestamp of special execution (AUTO) that makes that the server uses the server local date /hour to establish the data hour, not paying attention to the hour sent by the agent. This is necessary in those agents that by any reason have a wrong hour or a different hour from the server.

1.3.3.21 cron_mode

With this parameter is possible to do that the agent use the Linux crontab to execute itself in a specific interval instead of using the agent internal system to execute itself every certain time . It is deactivated by default and it is not recommended to use it unless it would be strictly necessary.

1.3.3.22 remote_config

This parameter controls if it is possible to configure the agent remotely from the console or not. 1: the remote configuration is activated, 0: the remote configuration is not allowed. By default is deactivated.

1.3.3.23 xml_buffer

By default 0. If set to 1 the agent will save any XML data files that could not be sent and try again later.

On Unix, if you are in a secured environment and want to enable the XML buffer you should consider changing the temporal directory, since /tmp is world writable.

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

server_ip       192.168.1.1 
server_path     /var/spool/pandora/data_in 
temporal        /var/spool/pandora/data_out 
logfile         /var/log/pandora/pandora_agent.log 
interval        300 
debug           0 
agent_name      box01 
server_port     41121 
transfer_mode   tentacle 
remote_config    1 

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

server_ip       192.168.1.1 
server_path     /var/spool/pandora/data_in 
temporal        c:\archivos de programa\pandora_agent\temp
logfile         c:\archivos de programa\pandora_agent\pandora_agent.log 
interval        300 
debug           0 
agent_name      box01 
server_port     41121 
transfer_mode   tentacle 
remote_config   1 

1.3.3.24 timezone_offset

The agent now can set it's timezone offset with the server. This is very useful to have agents with a different timezone synchronized with the same time with a server on another timezone. Agents will sent the shifted timezone to the server.

# Timezone offset: Difference with the server timezone
timezone_offset 3

1.3.3.25 agent_parent_name

Also now it's possible (if the server allows it) to update the parent of an agent by sending in the XML the name of the parent agent.

parent_agent_name parent_name

1.3.3.26 agent_threads <threads>

Number of threads the agent will launch to execute modules in parallel. by default there is a single thread, to execute one module, and later the other, and go on until finish all of them. This is only available in Unix agents.

1.3.3.27 include <filename>

Alternative configuration file path. This file can contain additional modules and collections besides the main configuration file ones. This token is optional. As regarding perl agent, it allows filename wildcards.

1.3.3.28 broker_agent <name>

It manages configurations and data collection from an agent like if they were multiple. A new configuration file is created for each broker agent added in the main configuration file with the name we have assigned to it. This token will be used only in the broker agent and not in the new agents created by this. These new agents will start reporting after the next execution. This token is optional.

1.3.3.29 pandora_user <user>

This parameter is optional and allow to execute the agent with the system user specified. This user will have permissions to execute the agent and the associated resources.

As we can see, most of the parameters from a Windows and a Unix agent are the same.

1.3.3.30 (>= 5.X) custom_id

Custom Id of the agent for extern applications.

1.3.3.31 (>= 5.X) url_address

Custom URL to open it from the agent in the console.

1.3.3.32 (>= 5.X) custom_fieldX_name

Name of an agent custom field that already exists on the system. If doesnt exist, will be ignored.

Example:

custom_field1_name Model

1.3.3.33 (>= 5.X) custom_fieldX_value

Value for the custom field X defined in the previous parameter.

Example:

custom_field1_value C1700

1.3.4 Secondary Server

An special kind of general configuration parameter is the definition of a secondary server. This allow to define a server to which send data, in a complementary way to the server defined in an standard way. The secondary server mode works in two different ways:

  • on_error: Send data to the secondary server only if it cold not send them to the primary.
  • always: Always send data to the secondary server, regardless if it can contact or not with the main server.

Configuration example:

secondary_server_ip     192.168.1.123
secondary_server_path   /var/spool/pandora/data_in
secondary_mode          on_error
secondary_transfer_mode tentacle
secondary_server_port   41121

1.3.5 UDP Server

Pandora FMS Windows agent allows to configure the agent for the listening of remote commands.This server listen in a UDP port that has been specified by the user, and allows to get orders from a remote system, ideally from the Pandora FMS, through the execution of alerts in the server.

There are several options to configure the UDP remote server. They are at pandora_agent.conf

  • udp_server:To activate the UDP server put it at 1. It is deactivated by default.
  • udp_server_port: Port where it listen.
  • udp_server_auth_address:Authorized IP address to send orders. For security reasons, restrict the access to this agent from a unique IP.
  • process_<name>_start <command>: Command that will start a process defined by the user.
  • process_<name>_stop <command>: Command that will stop the process.
  • service_<name> 1: Allows that the service <name> could be stop or started remotely from UDP server.

Configuration example:

udp_server 1
udp_server_port 4321
udp_server_auth_address 192.168.1.23
process_firefox_start firefox
process_firefox_stop killall firefox 
service_messenger 1 

The server accept the following commands:

* <START|STOP> SERVICE <name of the service>: Start or stop a service.
* <START|STOP> PROCESS <nombre del proceso>: Start or stop a process.
* REFRESH AGENT <nombre del agente>: Forces one execution of the agent, refreshing data.

For example:

STOP SERVICE messenger
START PROCESS firefox
REFRESH AGENT 007

There is an script in the server at /util/udp_client.plthat is the used by the Pandora FMS Server as a command of an alert, to start process or services. It has this syntax.

./udp_client.pl <address> <port> <command>

For example, to restart an agent:

./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT"

For more information, please go to the Alert configuration section. ¡

1.3.6 Modules definition

Each piece of information that is collected should be perfectly defined in each module, using the most precise syntax. You can implement as many values as it would be necessary in order they could be collected, adding, at the end of the general parameters as many modules as the number of values to compile. Each module is composed by several directives. The list that appears bellow is a descriptive list of all available modules signals for UNIX agents (almost all of them could be also apply to the Window agent).

The general syntax is the following:

module_begin
module_name NombreDelMódulo
module_type generic_data
.
.
.
module_description Ejecución del comando
module_interval Número
module_end 

There are different kinds of modules, with different suboptions, but all modules have an structure similar to this. The parameters module_interval and module_description are optionals and the rest completely compulsories. We are going to see first the common elements.

1.3.6.1 Common elements of all modules

1.3.6.1.1 module_begin

Defines the beginning of the module. Compulsory.

1.3.6.1.2 module_name <name>

Name of the module. This is the module ID. Choose a name without blanks and not too long. There is no specific limitation. (max.250 characters), but a short name would be easier to work with, this name CAN NOT be duplicated ' with a similar name in the same agent. This name could be duplicated with other modules in other agents. Same as with other things Pandora FMS is sensible to the difference between capital and small letters.

It is compulsory.

1.3.6.1.3 module_type

The data type that the module will use. There are several data types for agents:

  • Numerical (generic_data). Simple numerical data, in floating comma or wholes. If the values are floating type, these will be cut to its whole value.
  • Incremental (generic_data_inc). The whole numeric data equals to the differential being between the current value and the previous one. When this differential is negative, the value is fixed to 0.
  • Alphanumeric (generic_data_string). Collect alphanumeric text strings.
  • Monitors (generic_proc). Useful to evaluate the state of a process or service. This type of data is called monitor because it assigns 0 to a «Wrong» state and any value higher to 1 to a «Right» state.
  • Asynchronous Alphanumeric (async_string). Collect alphanumeric text string that could entry at any moment without a fixed periodicity. The rest of parameters (generic*) have a synchronous working, this is, they expect the data entry every XX time, and if they don't come then it's said that they are in an unknown state (unknown). The asynchronous modules can not be in this state.
  • Asynchronous Monitor (async_proc). Similar to the generic_proc but asynchronous.
  • Asynchronous Numerical (async_data). Similar to generic_data but asynchronous.

It is compulsory

1.3.6.1.4 module_min <value>

This is the minimum valid value to data generated in this module. If the module has not been defined yet in the web console, then this value would be taken from this directory. This order is not compulsory. This value does not eliminate the defined value in the agent. If the module does not exist in the dashboard, then it will created automatically when the learning mode is used.

1.3.6.1.5 module_max <value>

This is the maximum valid value for data generated in this module. If the module has not been defined in the web console, this value could be taken from this directory. This guideline is not compulsory and is not supported by the Windows agent. This value does not eliminate the defined value in the agent. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.6 module_min_warning <value>

This is the minimum value that will make the module state goes to warning. This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.7 module_max_warning <value>

This is the maximum value that will make the module state goes to warning. This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.8 module_min_critical <value>

This is the minimum value that will make the module state goes to critical. This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.9 module_max_critical <value>

This is the maximum value that will make the module state goes to critical. This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.10 module_disabled <value>

Indicates if the module is enabled (0) or disabled (1). This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.11 module_min_ff_event <value>

This is the interval between new changes of state will be filtered avoiding continuos changes of module state. This guideline is not compulsory. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is used.

1.3.6.1.12 module_description <text>

This guideline will be employed to add a comment to the module. This guideline in not compulsory. This value does not overwrite the value defined by the agent. If the module does not exist in the dashboard, then it will be created automatically when the learning mode is employed.

1.3.6.1.13 module_interval <factor>

Since Pandora 1.2 introduced this new type, it is possible for each module to fix its own interval. This interval is calculated as a multiplier factor for the agent interval.For example, if the agent has interval 300 (5 minutes), and you want a module that will be processed only every 15 minutes, then you should add this line: module_interval 3. The, this module will be preocessed every 300sec x 3 = 900sec (15 minutes).

1.3.6.1.14 module_timeout <secs>

(Windows only)

In 3.1 version, Pandora FMS supports specifying in each module independently, the total of seconds, Agent will wait for the execution of the module, so if it takes more than XX seconds, it will abort the execution of the module (for avoid becoming "dead" in the implementation of a module). In version 3.1 it's only supported on Windows, but future versions will also be implemented for Unix agents.

1.3.6.1.15 module_postprocess <factor>

Same as in the definition of post processing of a module that is done from the console, here could be defined a numeric value of floating comma that will send this value to Pandora FMS in order the server will use it to multiply the received (raw) by the agent. If you want to multiply by 1024 the value that the agent returns, put here "1024". If you want to divide it by 1024, then put here 1 /1024, that is 0,000976563.

1.3.6.1.16 module_save <variable name>

From version 3.2 it's possible to save the module returned value in an environment mode variable, so it could be used later in other modules. It's important to consider that the values are updated after the modules are executed, that is, in the same order that they are defined.

For example:


module_begin
module_name echo_1
module_type generic_data
module_exec echo 41121
module_save ECHO_1
module_end
module_begin
module_name echo_2
module_type generic_data
module_exec echo $ECHO_1
module_end


1.3.6.1.17 module_crontab <minute> <hour> <day> <month> <day of the week>

From version 3.2 it's possible to schedule modules in order they'll be executed in an specific date. To do this, you should have to define the module_crontab' using a similar format to that of the crontab file:(http://es.wikipedia.org/wiki/Cron_(Unix)#Sintaxis)


module_crontab <minute> <hour> <day> <month> <day of the week>

Being:

  • Minute 0-59
  • Hour 0-23
  • Day of the month 1-31
  • Month 1-12
  • Day of the week 0-6 (0 is Sunday)

It's also possible to specify intervals using the -character as divider.

For example, in order to one module will be executed every Monday between 12 and 15, we could use the following configuration:

module_begin
module_name crontab_test
module_type generic_data
module_exec script.sh
module_crontab * 12-15 * * 1
module_end

The module will be executed once during the interval. If we want that it'll be executed while the interval is on, we could use the module_cron_interval 0 option in the following way:

module_begin
module_name crontab_test2
module_type generic_data
module_exec script.sh
module_crontab * 12-15 * * 1
module_cron_interval 0
module_end

To execute a command every hour, in an hour and 10 minutes:

module_begin
module_name crontab_test3
module_type generic_data
module_exec script.sh
module_crontab 10 * * * *
module_cron_interval 0
module_end
1.3.6.1.18 module_condition <operation> <command>

From version 3.2 it's possible to define commands that will be executed when the module returns some specific values. It's necessary to specify one of the following options:

  • > [value]: Executes the command when the module value is higher that the given value.
  • < [valor]: Executes the command when the module value is lower than the given value.
  • = [valor]: Executes the command when the module value is the same as the given value.
  • != [valor]: Executes the command when the module value is different to the given value.
  • =~ [regular expression]: Executes the command when the module value coincides with the given regular expresion.
  • (valor, valor): Executes the command when the module value is ranged between the given values.

It's possible to specify multiple conditions for the same module. For example:

module_begin
module_name condition_test
module_type generic_data
module_exec echo 2.5
module_condition (1, 3) script_1.sh
module_condition > 5.5 script_2.sh
module_end

Examples:

module_begin
module_name MyProcess
module_type generic_data
module_exec tasklist | grep MyProcess | wc -l
module_condition > 2 taskkill /IM MyProcess* /F
module_end
module_begin
module_name PandoraLogSize
module_type generic_data
module_exec ls -la "c:\Archivos de programa\pandora_agent\pandora_agent.log" | gawk "{ print $5 }"
module_condition > 10000 del "c:\Archivos de programa\pandora_agent\pandora_agent.log"
module_end
module_begin
module_name Service_Spooler
module_type generic_proc
module_service Spooler
module_condition = 0 net start Spooler
module_end
  • NOTE: On Windows platforms is recommended to use cmd.exe /c to execute the command to ensure it is executed properly. For example:
module_begin
module_name condition_test
module_type generic_data
module_exec echo 5
module_condition (2, 8) cmd.exe /c script.bat
module_end
1.3.6.1.19 module_precondition <operation> <command>

if the precondition is true, the module will run. It's necessary to specify one of the following options:

  • > [value]: Executes the command when the module value is higher that the given value.
  • < [valor]: Executes the command when the module value is lower than the given value.
  • = [valor]: Executes the command when the module value is the same as the given value.
  • != [valor]: Executes the command when the module value is different to the given value.
  • =~ [regular expression]: Executes the command when the module value coincides with the given regular expresion.
  • (valor, valor): Executes the command when the module value is ranged between the given values.

An example of a module using precoditions is the following:

module_begin
module_name Precondition_test1
module_type generic_data
module_precondition (2, 8) echo 5
module_exec monitoring_variable.bat
module_end

Like postconditions is possible to use several precondition. The module will only be executed if all preconditions are successfull:

module_begin
module_name Precondition_test2
module_type generic_data
module_precondition (2, 8) echo 5
module_precondition < 3 echo 5
module_exec monitoring_variable.bat
module_end
  • NOTE: On Windows platforms is recommended to use cmd.exe /c to execute the command to ensure it is executed properly. For example:
module_begin
module_name Precondition_test3
module_type generic_data
module_precondition (2, 8) cmd.exe /c script.bat
module_exec monitoring_variable.bat
module_end
1.3.6.1.20 (>= 5.x) module_unit <value>

This is a the unit of the value retrieved by the module.

Example:

module_unit %

1.3.6.1.21 (>= 5.x) module_group <value>

This is the name of the module group. If the group doesnt exist the module will be created without module assigned.

Example:

module_group Networking

1.3.6.1.22 (>= 5.x) module_custom_id <value>

This is a custom identifier for the module.

Example:

module_custom_id host101

1.3.6.1.23 (>= 5.x) module_str_warning <value>

This is a regular expression to define the Warning status in the string types modules.

Example:

module_str_warning .*NOTICE.*

1.3.6.1.24 (>= 5.x) module_str_critical <value>

This is a regular expression to define the Critical status in the string types modules.

Example:

module_str_critical .*CRITICAL.*

1.3.6.1.25 (>= 5.x) module_warning_instructions <value>

This is instructions to the operator when the modules changes to Warning status.

Example:

module_warning_instructions Increase incident priority

1.3.6.1.26 (>= 5.x) module_critical_instructions <value>

This is instructions to the operator when the modules changes to Critical status.

Example:

module_critical_instructions Call to sys department

1.3.6.1.27 (>= 5.x) module_unknown_instructions <value>

This is instructions to the operator when the modules changes to Unknown status.

Example:

module_unknown_instructions Open incident

1.3.6.1.28 (>= 5.x) module_tags <value>

This is the tags that will be assigned to module separated by commas. Will be assigned only the tags that exist in system.

Example:

module_tags tag1,tag2,tag3

1.3.6.1.29 (>= 5.x) module_warning_inverse <value>

This is a flag (0/1) that when is activated the Warning threshold will be the inverse of the defined

Example:

module_critical_inverse 0

1.3.6.1.30 (>= 5.x) module_critical_inverse <value>

This is a flag (0/1) that when is activated the Critical threshold will be the inverse of the defined

Example:

module_critical_inverse 1

1.3.6.1.31 (>= 5.x) module_quiet <value>

This is a flag (0/1) that when is activated the module will be in quiet mode (it will not generate event or alerts)

Example:

module_quiet 1

1.3.6.1.32 (>= 5.x) module_ff_event <value>

This is the flip flip execution threshold of the module (in seconds)

Example:

module_ff_event 2

1.3.6.1.33 (>= 5.x) module_macro<macro> <value>

This is a macro generated by the console with the components macros system. Set this parameter from the configuration file is useless because it is only for modules created with local components.

Example:

module_macro_field1_ 8080

1.3.6.1.34 module_end

Defines the end of the module. It is compulsory.

1.3.6.2 Specific guidelines to obtain information

Next there are the specific guidelines that could be specified for each module in order to obtain information. In each module only could be use one kind of them.

1.3.6.2.1 module_exec <comand>

This is the general way to gather information by executing a command. Both for the Unix agent and for the Windows agent.There is only one guideline to obtain data from a generic way, executing only one command (it can be use pipes to re-address the execution to other command). This guideline executes a command and keeps the returned value. This method is also available in the agents for Windows. This is the general purpose method for both agents.


Template warning.png

If execution returns a return code different from 0 this will be taken as "execution error" and information will be discarted.

 


In some cases where you're sure your command is ok, even if returning codes != 0, you can pipe the execution to another "dump" command to clean the return code, for example:

top -n 1 

Will give you errorcode 1 (check which echo $?). To "clean" that error code, use this:

top -n 1 | grep ""


For the agents there are more guidelines to obtain data. They are the following ones:

1.3.6.2.2 module_service <service>

Checks if an specific service is being executed at the machine. Remember to use the «" "» characters if the name of the service contains blanks.

module_begin
module_name Service_Dhcp
module_type generic_proc
module_service Dhcp
module_description Service DHCP Client
module_end

The service is identified with the short name of the service (Service name),such as it appears in the Windows services manager. There is other identifier, called "display name", longer and usually more descriptive, but this is not the one used by Pandora FMS to identify the process. Neither it is the process related to the server. In this snapshot we could see the short name (Service name) of the service monitored in the previous example. It is important to stress that there is a difference in the use of the "capital and the small letters so, for example it is not the same DHCP that Dhcp

Service name id.png

Unix

In Unix works like Windows, but in Unix service and process is the same concept. For example, to see if process sshd is running, module definition will be:

module_begin
module_name Service_sshd
module_type generic_proc
module_service sshd
module_description Process SSHD running
module_end

Service watchdog and service asynchronous detection is not possible in Unix agents.

Asynchronous Way

Pandora FMS usually executes a test battery(each of them defined by a module) every X seconds (300 seg.= 5 min.by default) so if a service is down just after an execution of Pandora, then it will be take other 300 seconds to know it has get down. The asynchronous modules do that Pandora notify "inmmediatly" the fall of this service. This is called asynchronous operation mode. For it, it would be enough to add the guideline.

module_async yes

Watchdog of services

There is a watchdog mode for the services, so the agent could start them again if they stop. In this case, the service that is restarted does not requires any parameter, because Windows already knows how to do it.In this case the configuration is easier and this could be an example:

module_begin
module_name ServiceSched
module_type generic_proc
module_service Schedule
module_description Service Task scheduler
module_async yes
module_watchdog yes
module_end
1.3.6.2.3 module_proc <process>

Checks if an specific name of process is working in this machine. If the name of the process has blanks no use «" " ». Consider that the name of the process should have the .exe extension. The module will return the number of processes that are being executed with this name. It is important, same as with other cases, that the name of the process would be exactly the same that the one shown by the Windows task manager, including blanks, capital letters/small letters.For exemple it will not be the same cmd.exe that CMD.exe

This would be an example of the monitoring of process cmd.exe:

module_begin
module_name CMDProcess
module_type generic_proc
module_proc cmd.exe
module_description Process Command line
module_end

Unix

In Unix this module works like the module_service. It doesn't support asynchronous and/or watchdog mode.

Asynchronous mode

In a similar way to the services, monitoring processes can be critical in some cases. Now the Window agent supports asynchronous checking for the module_proc. module. In this case, the agent notify inmediatly when the process changes the state, without waiting for the agent executes again the verification as it is configured in the agent interval. In this way, you can know the fall or critical processes almost at the same time they take place. This would be an example of asynchronous monitoring of processes:

module_begin
module_name Notepad
module_type generic_data
module_proc notepad.exe
module_description Notepad
module_async yes
module_end

The difference is in the configuration token "module_async yes".

Processes Watchdog

A Watchdog is a system that allows to act immediately when an agent is down, usually picking up the process that is down . The Pandora FMS Windows agent could act as Watchdog when a process is down. This is called watchdog mode for the process:


Executing a process could need some parameters, so there are some additional configuration options for these kind of modules. It is important to say that the watchdog mode only works when the module type is asynchronous. Let's see an example of configuration of a module_proc with watchdog.


module_begin
module_name Notepad
module_type generic_data
module_proc notepad.exe
module_description Notepad
module_async yes
module_watchdog yes
module_start_command c:\windows\notepad.exe
module_startdelay 3000
module_retrydelay 2000
module_retries 5
module_end

This is the definition of the additional parameters for module_proc with watchdog:

  • module_retries:number of consecutive attempts for the module will try to start the process before deactivating the watchdog. If the limit is achieved , then the watchdog device for this module will be deactivated and will never try to start the process, even if the process is recovered by the user ( at last until the agent will be reboot). By default there is no limit for the nº of reattempts of the watchdog.
  • module_startdelay:number of milliseconds the module will wait before starting the process by first time. If the process takes lot of time at starting , then it will be a great idea to order the agent through this parameter that it "wait" until start checking again if the process has got up. In this example wait 3 seconds.


  • module_retrydelay: Similar to the previous one but for subsequent falls/reattempts, after having detect a fall. When Pandora detects a fall, relaunch the process, wait the nº of milliseconds pointed out in this parameter and check again if the process is already up.

It is important to say that Pandora FMS is executed as service and if you want to use the Watchdog functionality to execute processes that allow to interact with the desktop, then we should arrange, in the Pandora FMS service functionalities, the box "Interactive access with desktop", as it is shown in the following snapshot:

Service interactive.png

Same way, it is necessary to understand that Pandora FMS as service, is executed under the count "SYSTEM" and that the executed process will do it with this user and environment, so if it wants to execute an specific process that requires be used with an specific user,he should encapsulate in one script (.bat or similar) the previous processes for starting the environment, environment variables, etc) and execute this script as a watchdog action.


1.3.6.2.4 module_cpuproc <process>

(Unix only)

Return the CPU usage of a specific process.

module_begin
module_name myserver_cpu
module_type generic_data
module_cpuproc myserver
module_description Process Command line
module_end
1.3.6.2.5 module_memproc <process>

(Unix only)

Return the memory used by a specific process.

module_begin
module_name myserver_mem
module_type generic_data
module_memproc myserver
module_description Process Command line
module_end
1.3.6.2.6 module_freedisk <unit_letter:>|<volume>

This module works in Unix and Windows. It checks the free space in the disk unit (don't forget «":"» after the unit_letter) or the unix volume, p.e /var.

1.3.6.2.7 module_freepercentdisk <unit_letter:>|<volume>

This module returns the free disk percentage in a windows unit: (don't forget the ":") or on a Unix system, the volume, like /var.


 module_begin
 module_name freepercentdisk
 module_type generic_data
 module_freepercentdisk C:
 module_end
module_begin
module_name disk_var
module_type generic_data
module_freepercentdisk /var
module_end
1.3.6.2.8 module_occupiedpercentdisk <unit_letter:>|<volume>

(Unix only)

This module returns the occupied disk percentage in a Unix volume, like /var.

module_begin
module_name disk_var
module_type generic_data
module_occupiedpercentdisk /var
module_end
1.3.6.2.9 module_cpuusage <cpu id>

This works in Unix and Windows. It gives back the CPU usage in a CPU number. If there is only one CPU, let it blank or use the 'all'. It is also possible to obtain the use average of all CPU in a multiprocessor system:

module_begin
module_name SystemCPU
module_type generic_data
module_cpuusage all
module_description Average CPU use in systme
module_end

To check CPU usage in CPU #1

module_begin
module_name SystemCPU_1
module_type generic_data
module_cpuusage 1
module_description Average CPU use in system for CPU #1
module_end
1.3.6.2.10 module_freememory

Supported in Windows and Unix. Gives back the free memory in the whole system.

module_begin
module_name FreeMemory
module_type generic_data
module_freememory
module_description Non-used memory on system
module_end
1.3.6.2.11 module_freepercentmemory

Supported in Unix and Windows. This module gives back the free memory percentage in one system:

module_begin
module_name freepercentmemory
module_type generic_data
module_freepercentmemory
module_end
1.3.6.2.12 module_tcpcheck

(Windows only)

This module tries to connect with the IP and port specified.It returns 1 if it had success and 0 if it had other way.You should specify a time out.

module_begin
module_name tcpcheck
module_type generic_proc
module_tcpcheck www.artica.es
module_port 80
module_timeout 5
module_end
1.3.6.2.13 module_regexp

(Windows only)

This module monitors a record file (log) looking for coincidences using regular expressions, ruling out the already existing lines when starting the monitoring . The data returned by the module depends on the module type:

  • generic_data_string, async_string: Gives back all the lines that fit with the regular expression.
  • generic_data: Gives back the number of lines that fit with the regular expression.
  • generic_proc: Gives back 1 if there is any coincidence, 0 if other way.
  • module_noseekeof: With a 0 value by default, with this configuration token active, in each module execution, independently from any modification the target file suffers, the module will restart its check process without searching for the EOF flag of the file, so it will always extract to the XML output all those lines matching our search pattern.
module_begin
module_name regexp
module_type generic_data_string
module_regexp C:\WINDOWS\my.log
module_pattern ^\[error\].*
module_noseekeof 1
module_end

To obtain more information about the syntax of the regular expressions, please have a look at this:[2]

1.3.6.2.14 module_wmiquery

(Windows only)

The WMI modules allow to execute locally any WMI query without using an external tool. It is configured through two parameters:

  • module_wmiquery: WQL query used.Several lines could be obtained as a result, that will be placed as several data.
  • module_wmicolumn: Name of the column that that is going to be used as a data source.

For example, we could obtain a list of the installed services.

module_begin
module_name Services
module_type generic_data_string
module_wmiquery Select Name from Win32_Service
module_wmicolumn Name
module_end

Or of the current CPU load:

module_begin
module_name CPU_speed
module_type generic_data
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
module_wmicolumn LoadPercentage
module_end
1.3.6.2.15 module_perfcounter

(Win32 only)

Obtains data from the performance counter through the PDH interface (the library pdh.dll should be installed in the system. PDH.DLL is a Windows library. If you have not installed it then you would have to install the Windows performance analysis tool (that usually is installed by default).

module_begin
module_name perfcounter
module_type generic_data
module_perfcounter \Memory\Pages/sec
module_end

The Windows performance monitor is a powerful tool that has hundreds of parameters that could be used to monitor. Each manufacturer also adds his owns monitors, so this is a powerful, versatile and easy to use tool to monitor the system parameters and also the devices that run on it.

The syntax of the perfcounter elements depends on the language, this is, in a German version ,Windows will have specific identification strings, and in an English version, Windows will have other ones. This makes difficult to use it at system with heterogeneous languages.

To explore the different values that could be used, you can use the the Windows tool "Performance" to see which strings of performance you could monitor.

In this snapshot you can see the Windows performance monitor.

Perfcounter screen1.png

And in this snapshot see how the interface show things when we want to add a new monitoring element.

Here we could visualize (in spanish) several parameters of the Procesador(in spanish at original version) and that has different sub elements, of which them we have selected % of processor time and in several sub elements. In this case, we are interested in the total _ Total.

Perfcounter screen2.png

In this way, surfing with the SO tool, we could get different elements of the system performance. For this specific example, the module would be:

module_begin
module_name Processor_Time
module_type generic_data_inc
module_perfcounter \Procesador(_Total)\% de tiempo de procesador
module_end

By default the raw value of the counter is shown, to get the cooked value add the module_cooked 1 parameter:

module_begin
module_name Disk_E/S_Seg
module_type generic_data
module_cooked 1
module_perfcounter \DiscoFísico(_Total)\E/S divididas por seg.
module_end

Many of the data that it returns are counters, so you should use generic_data_inc as data type. It can also returns values in very high data scales (several millions), so you could reduce these values using the module post process, with values like 0.000001 or similar.

1.3.6.2.16 module_inventory

In Linux/Unix is implemented as agent plugin

Using predefined WMI consults and queries on the registry.This module obtains information about the different aspects of a machine. From software to hardware.

The module can get different parameters to mark the kind of information that it gets. Here is the parameter list and the kind of information that it gives:

  • Cpu: Gets information about the system CPUs( processor name, watch frequency, and description).
  • CDROM: Gets information about the CD-ROM(name, description and unity letter).
  • Video: Gets information about video cards(description, RAM, and processor).
  • HDs: Gets information about the hard disks(model, size and name in the system).
  • NICs: Gets information about the network interface controllers(description, MAC address and IP address).
  • Patches: Gets information about the installed patches(identifier, description and comments).
  • Software: Gets information about MSI packages installed(name and version).
  • RAM: Gets information about RAM modules(tag, capacity and name).
  • Services: Gets information about the installed services. The short name shown in the first column is the name of the service that Pandora FMS uses to could monitor services.

Additional Module Parameters:

  • module_interval: This module has an additional line to specify the interval, in days, where he can obtain the information for the module.

An example of the use of this module would be this:

module_begin
module_name Inventory
module_interval 7
module_type generic_data_string
module_inventory RAM Patches Software Services
module_description Inventory
module_end
1.3.6.2.17 module_logevent

(Windows only)

This new module allows to obtain information from the Window event log file. It returns those elements that agree with a given pattern, allowing also to filter by the source and event type. The module that exists in version 2.0 has been improved, using now the Win32 native API to have access to the events from the file, instead of using the subsystem WMI (much slower). This method is quicker and allow to work in systems with many elements. The new implementation also allows to filter through much more fields that in the previous version. The standard format of the module is the following:

module_begin
module_name MyEvent
module_type async_string
module_logevent
module_source <logName>
module_eventtype <event_type/level>
module_eventcode <event_id>
module_application <source>
module_pattern <text substring to match>
module_description
module_end

To avoid showing that has been already shown, we only consider those events that had taken place from the last time the agent was executed, as it happens with other modules (regexp, p.e).

module_logevent accepts the following parameters (all of them case-sensitive):

  • module_source: Event source (System, Application, Security). This field is compulsory.
  • module_eventtype: Event type(failure, information). It is an optional field.
  • module_pattern: Pattern to search (substring). It is an optional field.
  • module_eventcode: It is a numeric ID of the event, p.e: 5112. It is an optional field.
  • module_application: Application source of the event. Watch out not mistake with module_source that shows the name or the source or log file where the events are looked for.

For example, for showing all events of an error type system we should define the following module:

module_begin
module_name log_events
module_type generic_data_string
module_description System errors
module_logevent
module_source System
module_eventtype error
module_end

To show all events that have the word PandoraAgent:

module_begin
module_name log_events_pandora
module_type async_string
module_description PandoraAgent related events
module_logevent
module_source System
module_pattern PandoraAgent
module_end

Another example, filtering the event showed in the snapshot:

Event sample.png
module_begin
module_name MyEvent
module_type async_string
module_source Application
module_eventtype Information
module_eventcode 6000
module_application Winlogon
module_pattern unavailable to handle
module_description
module_end

It is very important to understand that Pandora FMS is not a system to collect logs and that this tool should be used to select those critical or important events for monitoring, and that collect all events, without classify them, from, a common source, as could be the "System" one, will only cause problems so the DDBB will be collapsed and the system will work in a very bad way.It is extremely important understand that the event collection with Pandora FMS should be done taking this in account and not using Pandora FMS as a generic event collector.

1.3.6.2.18 module_odbc

(Windows only) (only for 32 bits ODBC drivers)

NOTE: For 64 bits Windows systems it is needed to use a 32 bits ODBC system that it's called odbcad32.exe and set it like a file DSN.

Generic module of access to the database through ODBC interface in Windows agent. This allow to do now SQL queries to the database servers that have this system, as Microsoft SQL Server, Oracle, MySQL or PostgreSQL between others.

In order to could use ODBC modules, first you have to define the ODBC connector in the main section of the agent configuration, with some lines like these:

# ODBC connections
# Configuring "ExampleDSN" DSN. Notice that this DSN connection must be configured
# under Control panel -> Administrative tools -> ODBC -> DSN
odbc_ExampleDSN_username UserNameForDsn
odbc_ExampleDSN_password Password1234

This create a "ExampleDSN" handler that we could use after in the modules. Let see an example of a module that uses the handler previously created.

# ODBC query example using ExampleDSN connection defined above.
# This module gets the first row in example_table.
module_begin
module_name SQL query example
module_type generic_string
module_odbc ExampleDSN
module_odbc_query SELECT * FROM database.example_table
module_description The first row of example_table
module_end

At present, the ODBC module only allows to return the first line of each query exit.

NOTE: THE SYNTAX database.example_table IS REQUIRED TO ACCESS THE TABLE USING ODBC MODULE

1.3.6.2.19 module_plugin

Is a parameter to define the data that is obtained as an exit of a plugin agent. It is an special case of module, that builds all its XML and that does not requires any other delimiter,such as type module_begin, module_type, etc.They follow this format:

module_plugin plugin_filename parámetro_1 parámetro_2 parámetro_3

Each plugin has its own syntax. We are going to describe one of the plugins that comes by default with the Agent, the regular expressions plugin:

module_plugin grep_log /var/log/syslog Syslog ssh

In this example, the name of the plugin is "grep_log "and will search in the file "/var/log/syslog" the regular expression "ssh" and will kept it in a module called "Syslog".

Another example in windows systems, (solo version 3.1 o superior)

module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df_percent.vbs"

File collection and plugins

When you use file collections, this also works at the same level, but you need to know where are the collection files stores the files. File collections uses a "handle" or short name, generated when you first create the collection, and has a name similar to "fc_2". Let's see some examples of module_plugin usage, using file collections:

Unix:

module_plugin /etc/pandora/collections/fc_1/always_1.sh 

Windows:

module_plugin cscript //B "%ProgramFiles%\pandora_agent\collections\fc_2\df_percent.vbs"

It's very important to remark that plugin execution output could return more than one module, because it returns a full XML structure. This is, for example, the plugin output of the /util/df.vbs plugin in windows:

<module>
    <name><![CDATA[C:]]></name>
    <description><![CDATA[Drive C: free space in MB]]></description>
    <![CDATA[2361]]>
</module>
<module>
    <name><![CDATA[D:]]></name>
    <description><![CDATA[Drive D: free space in MB]]></description>
    <![CDATA[32020]]>
</module>
<module>
    <name><![CDATA[Z:]]></name>
    <description><![CDATA[Drive Z: free space in MB]]></description>
    <![CDATA[10168]]>
</module>
1.3.6.2.20 module_ping <host>

(From version 4.0.1 onwards, Windows only)

This module pings the given host and returns 1 if it is up, 0 otherwise. It is a wrapper for ping.exe.

Is supports the following configuration parameters:

  • module_ping_count x: Number of ECHO_REQUEST packets to be sent (1 by default).
  • module_ping_timeout x: Timeout in milliseconds to wait for each reply (1000 by default).
  • module_advanced_options: Advanced options for ping.exe.

Example:

module_begin
module_name Ping
module_type generic_proc
module_ping 192.168.1.1
module_ping_count 2
module_ping_timeout 500
module_end
1.3.6.2.21 module_snmpget

(From version 4.0.1 onwards, Windows only)

This module performs an SNMP get query and returns the requested value. It is a wrapper for snmpget.exe.

It supports the following configuration parameters:

  • module_snmpversion [1,2c,3]: SNMP version (1 by default).
  • module_snmp_community <community>: SNMP community (public by default).
  • module_snmp_agent <host>: Target SNMP agent.
  • module_snmp_oid <oid>: Target OID.
  • module_advanced_options: Advanced options for snmpget.exe.

Example:

module_begin
module_name SNMP get
module_type generic_data
module_snmpget
module_snmpversion 1
module_snmp_community public
module_snmp_agent 192.168.1.1
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.148
module_end

1.3.7 Examples

Example of a Windows module, checking if the EventLog works. It could 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
Tipos de agentes software

1.3.8 Advanced issues about software agents

With Pandora FMS it is possible to monitor any system. This could be done, either with a Software agent installed in the system, that collect data straigh from the system to be monitored, or using a "Satellite Agent" that consist of an agent that is executed in a server and monitor some parameters of systems that have adjacents, through SNMP or commands defined by the user.

The software agents could be Windows or UNIX agents. The agents could be installed using any of the agents described in the following lines. To use a satellite agent, it will be enough if you install a software agent and define configured modules to collect data from an external system, through, for example, the snmpget tool or through ping.

1.3.8.1 Unix/Linux Agents

Unix has several command line tools that allow that get data through commands would be a very simple thing.The Unix agents are based in this premise.There are two kinds of Unix agents:

  • ShellScript: with a shellscript defined for each kind of SO, based on bash, ksh or csh. In the classic Unix Systems (Solaris, AIX, HPUX) all functionalities are not implemented. But in Linux and MAC they are.
  • Perl: there is a unique multiplataform agent, based on Perl 5.8 that functions equally in all Unix systems. They should necessarily have a Perl 5.8 system or another higher to operate.

The shellscript agents have been designed to function even in the oldest UNIX versions: HPUX11.0, AIX 4.1, Solaris 6... They work, but are limited with some features, such as not having the Tentacle client and having to use the FTP system or SSH to upload the monitoring data to the server.

1.3.8.1.1 Pandora FMS Unix Agents Configuration

There is hardly any difference between AIX, Solaris and GNU/Linux. We are going to describe some of their most important parameters and paths.

After starting the installator, the agent main directory or "home" directory is /usr/share/pandora_agent/ where the Pandora FMS agent would be installed. In the system where this would be not possible by politic reasons, we recommend to create a link to this path from the installation real path,p.e /opt/pandora -> /usr/share/pandora_agent

The other important folders are:

  • /var/spool/pandora/data_out: Folder where the data collected by agents is kept
  • /etc/pandora/pandora_agent.conf: Main agent configuration folder. Where the data that is collected is defined, with the command that will be used for the collection of data.
  • /usr/local/bin/pandora_agent: the current Pandora FMS agent. This file is a shellscript that collects the configured data in the pandora_agent.conf files.It also send the data packages to the Pandora Server. It usually has a link to /usr/bin/pandora_agent
  • /usr/local/bin/tentacle_client: The agent add the Tentacle client to could send the data files to the server.This is a client in Perl 5.8. Usually it has a link to /usr/bin/tentacle_client.
  • /etc/init.d/pandora_agent_daemon: Script of start/ stop. This make a call to pandora_agent. This gives to options, start/stop. In the AIX systems the daemon is /etc/rc.pandora_agent_daemon .
  • /var/log/pandora/pandora_agent.log: Text file where the activity of the Pandora FMS agent is kept, when the agent is executed in depuration mode
  • /etc/pandora/plugins: Directory that keps the agent plugins. It is link to directory /usr/share/pandora_agent/plugins
1.3.8.1.2 Initial Execution of Unix Agent

When you start the Pandora FMS agent, this should copy the data file to the Pandora FMS server through the dispatch system that is specified in the configuration file /etc/pandora/pandora_agent.conf. This dispatch system (Tentacle,SSh,FTP) should be configured previously.

To start the agent you need only to execute:

/etc/init.d/pandora_agent_daemon start

For IPSO systems the agent will be launched with a priority of -10, so it turns into the process with the lowest priority in the system CPU It will be executed when other processes with a higher priority will be waiting in the CPU system queue.The IPSO agent has an special parameter (harmless_mode ) for an special management of the CPU process at systems Checkpoint/NOKIA. This is a very special case.

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

To stop the agent, execute:

/etc/init.d/pandora_agent_daemon stop
1.3.8.1.3 Advanced Configuration for the Unix Agent

The Pandora FMS's real power is on the agent capacity to start working the user defined scripts. This could be used to collect specific data or to make an operation that gives back any wanted value. This is the aim of the agent plugin structure. For more information check the Annex on Creating Agent plugins.

1.3.8.1.4 Examples of Implementation for Unix Agents

Example #1: calculate the number of displays at the Apache Web server main page (it could degrade the running of huge records):

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

Example #2: checks if the process of the DNS(named) is working or it is down:

module_begin
module_name DNS_Daemon
module_type generic_proc
module_exec ps -Af | grep named | grep -v "grep" | wc -l
module_end
1.3.8.1.5 Altering the way Unix Agents obtain system information

This is only valid for Unix Perl agents (version 3.2 or higher).

There are some modules which works like "blackboxes", thus, make things and the user doesn't have to know what is really doing. These modules are:

  • module_procmem
  • module_freedisk
  • module_freepercentdisk
  • module_cpuproc
  • module_proc
  • module_procmem
  • module_cpuusage
  • module_freememory
  • module_freepercentmemory

Modules like module_cpuusage, for example, return a % of current system CPU usage. But the user doesn't need to use a command, Pandora "already knows" what to do, on windows and in Unix systems.

Pandora Unix Agents have a "predefined" commands to do that, for example, to do this, is done in different ways depending on the OS:

	linux => 'vmstat 1 2 | tail -1 | awk \'{ print $13 }\,
	solaris => 'vmstat 1 2 | tail -1 | awk \'{ print $21 }\,
	hpux => 'vmstat 1 2 | tail -1 | awk \'{ print $16 }\

Could happen that your system is slightly different from the tested system, and the command is not valid. You can use your own command with a simple module_exec or redefine internal pandora commands to do that. For that, you need to edit some lines of Pandora FMS Unix Agent code, but doesn't worry, is Perl code, and it's a very basic edition.

Pandora agent is usually in /usr/bin/pandora_agent. Edit with vi or nano (they are common text editors for console), and search for "Commands to retrieve" text. You should see something like:

# Commands to retrieve total memory information in kB
use constant TOTALMEMORY_CMDS => {
	linux => 'cat /proc/meminfo  | grep MemTotal: | awk \'{ print $2 }\,
	solaris => 'MEM=`prtconf | grep Memory | awk \'{print $3}\'` bash -c \'echo $(( 1024 * $MEM ))\,
	hpux => 'swapinfo -t | grep memory | awk \'{print $2}\
};

This is the piece of code which defines how pandora get information from system to get total memory. AIX is not defined because we don't have information on how to get this information in a AIX system. If you see a bit more below:

# Commands to retrieve partition information in kB
use constant PART_CMDS => {
	# total, available, mount point
	linux => 'df -P | awk \'NR > 1 {print $2, $4, $6}\,
	solaris => 'df -k | awk \'NR > 1 {print $2, $4, $6}\,
	hpux => 'df -P | awk \'NR > 1 {print $2, $4, $6}\,
	aix => 'df -kP | awk \'NR > 1 {print $2, $4, $6}\
};

These are the commands to get disk information in KB (total, free and mount point). To change any of predefined values to get information, just edit the command, but be careful with:

  1. Check that lines ends with ";"
  2. Check that commands are between ' ' symbols.
  3. Check that any ' symbol you use, is escaped with \ symbol, for example this command:
df -P | awk 'NR > 1 {print $2, $4, $6}'

Will be

df -P | awk \'NR > 1 {print $2, $4, $6}\'

It's the same used above, so see how it is written in the code.

1.3.8.2 Pandora FMS Windows Agents

1.3.8.2.1 Checking of the Windows agent working

The exit of the Pandora FMS Windows agent can be checked at the file C:\archivos de programa\pandora_agent\pandora_agent.log,plain text file that includes information about the agent execution flow.

To check if Tentacle or SSH are working well, you can use the command tentacle_client or the parameter --test-ssh on the binary.The first command will give an error so neither the address or the file to send is specified, but it checks that the Tentacle client, tentacle-client is in the system. The second one will force to Pandora FMS to connect using SSH internally and copy a file called ssh.test. Remember that you shoul configure SSH correctly if you want to use it, generating the needed keys and importing them in the server.

1.3.8.2.2 Checking of Pandora FMS Agent service

The Pandora FMS 3.0 version has been carefully checked and "debugged" in order to avoid all kinds of memory leaks, handles,of processes , files or TCP/IP ports. It is very stable and has been tested in all Windows platforms where it has to operate. Nevertheless, in some systems could happen that the service fall a few times. For it we have tried to give some solutions to those users that require a restart system or a supplementary control of the agent.

There are two ways of having more control over the agent. The first one is to force the restart of the agent every X days through the Windows internal programmer for tasks through the AT command.

Restart with AT

In English

To schedule a restart on Mondays and Fridays:

at 00:00 /every:Monday,Friday "c:\program files\pandora_agent\scripts\restart_pandora_agent.bat"

In Spanish

For example, to schedule an every day restart:

at 00:00 /every:L,M,Mi,J,V,S,D "c:\archivos de programa\pandora_agent\scripts\restart_pandora_agent.bat"

To see a list of the scheduled tasks, write in the command line

at

This will give you the scheduled tasks.

Automatic control of the service in case of falls

Windows gives an additional way of controlled restart of the service if this, by any reason falls. This allow to say to the Windows service that if this fall, then it pull it up again automatically. For it you have to go to the Windows services dashboard, go to the Pandora FMS agent and click at properties. In the flap " Recovery", we should change the default values to these ones:

Service control restart.png

This does that if the service falls, it restart it automatically, but only once a day, so it falls more times it does not pull it up, avoiding by this that the system would be overload or forces the execution that downs too much and that could be caused by a problem in the system, because Pandora FMS should never be down,and of course, not so frequently. In any case, you can adjust these parameters to do that when the Pandora FMS service fall be controlled by the system and this way be sure that you will always have the agent running.

1.3.8.2.3 Configuration of Pandora FMS Windows Agent

The whole installation is done through file pandora_agent.conf. This file is a list of pairs of keys/values that have been described before. Here is an example of this file.


# General Parameters
# ==================
 
server_ip mypandoraserver.host.com
server_path /var/spool/pandora/data_in
temporal "c:\windows\temp"
interval 300
agent_name myagent_name
 
# Module Definition
# =================
 
# Counting OpenedConnections (check language string)
module_begin
module_name OpenNetConnections
module_type generic_data
module_exec netstat -na | grep ESTAB | wc -l | tr -d " "
module_description Conexiones abiertas (interval 2)
module_interval 2
module_end
 
# Is Eventlog service running ?
module_begin
module_name ServicioReg
module_type generic_proc
module_service Eventlog
module_description Servicio Registro de sucesos
module_end
 
# Is lsass.exe process alive ?
module_begin
module_name Proc_lsass
module_type generic_proc
module_proc lsass.exe
module_description LSASS.exe process.
module_end
 
# Received packets.
# Please notice that "Paquetes recibidos" string must be replaced by
# the correct string in your Windows system language.
module_begin
module_name ReceivedPackets
module_type generic_data
module_exec netstat -s | grep  "Paquetes recibidos  " |  tr -d " " | cut -f 2 -d "=" | tr -d "\n"
module_description Conexiones abiertas (interval 2)
module_end
 
# Free space on disk
module_begin
module_name FreeDiskC
module_type generic_data
module_freepercentdisk C:
module_description Free space on drive C:
module_end

module_begin
module_name FreeMemory
module_type generic_data
module_freepercentmemory
module_description Amount of free memory.
module_end
1.3.8.2.4 Extending the agents functionality of agents with VBS code

Starting witn 3.1 version, Windows agents have plugins, like the Unix agents, but don't forget that they have also the possibility of executing the external scripts, based in VBScript as simple modules. See the VBS code that obtains the CPU total use of a system:

strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
   & "{impersonationLevel=impersonate}!\\" _
   & strComputer & "\root\cimv2")

   Set object1 = objWMIService.Get( _
   "Win32_PerfRawData_PerfOS_Processor.Name='_Total'") 
   N1 = object1.PercentProcessorTime
   D1 = object1.TimeStamp_Sys100NS
   Wscript.Sleep(1000)
   set object2 = objWMIService.Get( _
   "Win32_PerfRawData_PerfOS_Processor.Name='_Total'")
   N2 = object2.PercentProcessorTime
   D2 = object2.TimeStamp_Sys100NS

   ' CounterType - PERF_100NSEC_TIMER_INV
   ' Formula - (1- ((N2 - N1) / (D2 - D1))) x 100
   PercentProcessorTime = (1 - ((N2 - N1)/(D2-D1)))*100

   Wscript.Echo PercentProcessorTime

We keep it a file called "CPUTotal.vbs" and located at c:\program files\pandora_agent\util.

Now we create a new module tipe module_exec with this content:

cscript.exe /NoLogo c:\program_filespandora_agent\util\CPUTotal.vbs

We already have a new module that returns the CPU total use obtained through the external script in VB. There are plenty of things that can be obtained throug VBScript. Microsoft has an excellent documentation on line about VBS that you can check in MSDN [3].

1.3.8.2.5 Running Pandora FMS Agent under a different user than SYSTEM

You can setup the Windows agent to run under a different user, to do that, you need to configure the service startup with a different user, and give that user special privileges. THat user should be included in the Group "administrators".

In the WMI console, all users from group "administrators" have ALL permissions enabled.

This is an example of a user, and the settings of WMI for ROOT space. By default, branches will takes (by hierarchy) the permissions of the root:


Service image001.png



Service image002.png


Some Microsoft links related with this issue on : [4] [5]

1.3.8.3 Auto-upgrading Software Agents

Pandora FMS 3.2 has a new feature called "File collection". File collections are described in a few chapters below, they are a "centralized file distribution system" to copy files (binary, scripts, data) from the console to the agents running the Pandora FMS software agent.

Using that mechanism and a very special tool, we can provide a way to "autoupgrade" the software agents. This works in this way:

1. Agents receive new binaries in the filecollection incoming dir, for example:

c:\program files\pandora_agent\collections\fc_1\pandoraAgent.exe

2. The agent uses a special module to execute the pandora_update tool. This tool receives a single parameter, it's the FileCollection handle (or short name), in this scenario, is fc_1, and check for a file called pandoraagent.exe (or pandora_agent in unix) and see the size and contents (by using a HASH) of both files, the running pandora_agent and the binary provided in the file collection. If they are different, pandora_update stop the agent, replace the binary and restart the agent again, using the new binary.

3. Pandora_update also writes to a small log the update event, to be able to recover in the next execution and warn the user, by using a async_string module, about the agent update process.

This means that modules used to do the update process, could be configured to have a high interval.

Unix standar installation

module_begin
module_name Pandora_Update
module_type async_string
module_interval 20
module_exec nohup /etc/pandora/plugins/pandora_update fc_1 2> /dev/null && tail -1 nohup.out 2> /dev/null
module_description Module to check new version of pandora agent and update itself
module_end

Unix custon installation

module_begin
module_name Pandora_Update
module_type async_string
module_interval 20
module_exec nohup /var/opt/PandoraFMS/etc/pandora/plugins/pandora_update fc_1 /var/opt/PandoraFMS 2> /dev/null && tail -1 nohup.out 2> /dev/null
module_description Module to check new version of pandora agent and update itself
module_end

NOTE: The second parameter of pandora_update command the installation path of Pandora FMS. This parameter is required only when you have installed Pandora FMS in another path different from default path.

Windows

module_begin
module_name Pandora_Update
module_type async_string
module_interval 20
module_exec pandora_update.exe fc_1
module_description Module to check new version of pandora agent and update itself
module_end

NOTE: At Unix, if it has the agent in a non "standard" path, it will have to modify some of the pandora_update utility values, specifically the following lines:


# Setup your particular paths / process settings here
# [SETUP BEGIN] 12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)
# Location of binaries 
 
# Unix 
my $running_binary = "/usr/bin/pandora_agent";
my $updated_binary = "/etc/pandora/collections/$fc_path/pandora_agent";

# Unix style

my $start_pandora = "/etc/init.d/pandora_agent_daemon start";
my $stop_pandora = "/etc/init.d/pandora_agent_daemon stop";

And fix manually the paths to the one that fits with your system.

1.3.8.4 Process to Auto_Upgrade Agents from versions Previous to the 3.2

The first thing is to get the runnables from the Pandora FMS agent and from the pandora_update tool (pandoraAgent.exe and pandora_update.exe in Windows and pandora_agent and pandora_update in Unix)

Many of the steps that we are giving here means the following things:

1. You have a way to copy files to the systems that you want to update. This is a feature that the Pandora FMS 3.2 version provides (File Collection) but just now you want to migrate to the 3.2 version, because it hasn't this feature. It's assumed that you have other alternative mechanism.

2. The agent configuration remote management is activated and working. This will be useful, and you should create several directories and configure a new module in your Pandora FMS agent configuration.

Windows Platforms

We should copy pandora_update to one directory of the system path or to the carpeta /util of our pandora (in Windows)

Supposing that we have Pandora FMS installed at:

C:\Archivos de programa\pandora_agent

We have to copy pandora_update.exe in the directory:

C:\Archivos de programa\pandora_agent\util

Then we create two directories:

C:\Archivos de programa\pandora_agent\collections
C:\Archivos de programa\pandora_agent\collections\fc_1

And after this, we should copy the new agent binary to the last directory that we have created:

C:\Archivos de programa\pandora_agent\collections\fc_1\PandoraAgent.exe

We create one module in the agent as the one that follows:

module_begin
module_name Pandora_Update
module_type async_string
module_interval 20
module_exec pandora_update.exe fc_1
module_description Module to check new version of pandora agent and update itself
module_end

This special module that uses the pandora_update executable, executes an special tool (pandora_update) that compares the current executable with the one that already exist in the directory /collections/xxxx, where xxxx is a parameter that is passed to the module. This location is the one that is specified with the file_collections.After, using the 3.2 version, the distribution of the new .exe of the agents will be done through filecollections and this identifier will be necessary to "locate" in which File Collection is our executable.

UNIX Platforms

In a similar way to the Windows platforms, we have to copy the executable of the Unix agent and the pandora_update feature. If it has a non_standar installation and it has customized paths, then you should have to pay lot of attention to the previous paragraph, where it says which files should be modified.

You have to copy pandora_update in your agent plugins/folder:

/etc/pandora/plugins/pandora_update

And now create directories/collection/fc_1 on the base directory of your /etc/pandora

/etc/pandora/collections/
/etc/pandora/collections/fc_1

The call to pandora_update will be done on its system paths to the plugins, in this case, the standard is /etc/pandora/plugins/pandora_update

The module for the Unix case will be the following one:

module_begin
module_name Pandora_Update
module_type async_string
module_interval 20
module_exec nohup /etc/pandora/plugins/pandora_update fc_1 2> /dev/null && tail -1 nohup.out 2> /dev/null
module_description Module to check new version of pandora agent and update itself
module_end

NOTE: You should check that both pandora_update and pandora_agent have suitable permissions and owners. Executing permissions and the same user that the pandora_agent executable.

1.3.9 Pandora FMS Drone Agents

1.3.9.1 What is a Drone Agent ?

Pandora FMS Drone Agent is a running mode of Pandora FMS Software Agent. This running mode only works on Windows and Linux machines.

Pandora FMS Drone Agent was developed to deal with complicated environments with restricted access to the machines. The Drone Agent has two main features:

  • Proxy mode
  • Broker mode

Furthermore running this mode Drone Agent can report data and use all features of standard Pandora FMS Software Agent.


The picture below shows an architecture of Pandora FMS using Drone Agents:

Architecture il1.png

1.3.9.1.1 Proxy Mode

Proxy Mode is very useful for networks that have restrictions in their communications. The agent running this mode enabled a Tentacle Proxy Server to allow agents communicate with Pandora FMS Server through itself.

The new Tentacle version supports proxy usage (HTTP/Connect mode), so agents can contact directly with the server using an intermediate standard proxy. You also can use a new tool called Tentacle Proxy Server, which as its name says, is used to centralize all communication between Pandora FMS and the agents, allowing the file management and remote configuration for policy based-monitoring. You can see more about Tentacle Proxy Server here.


With this feature you get all functionalities of a proxy but managed by Pandora FMS Software Agent. This mode has two requirements and are that the agent must cannot be run by the root and if you want to use the proxy mode with Unix agent then must be installed with a user without root privileges (the same user will execute later the agent in proxy mode).

All parameters to configure Tentacle Proxy Server are available trough agent configuration file, and are the following:

server_ip

Is the IP address or the name of Pandora FMS server host. Be careful with Proxy Mode enabled this parameter cannot take values such as: 127.0.0.1, locahost, 0.0.0.0, or related.

proxy_mode

Proxy mode status. If proxy_mode is 1 Proxy feature of Drone Agent is activated, If proxy_mode is 0 Proxy feature is off. By default this feature is disabled.

proxy_max_connection

Number of proxy simultaneous connections. By default 10 connections are allowed.

proxy_timeout

Timeout for proxied server. By default 1 second.

1.3.9.1.1.1 Usage Examples

I only have one connection to Pandora FMS Server

This situation is not a problem for Pandora FMS Drone Agent. To configure Proxy Mode just set server_ip to Pandora FMS IP and proxy_mode parameter to 1. If is needed you can configure some parameters like the number of connections and timeout. With this configuration you will have the agent and the Tentacle Proxy Server up and running in the machine that can connect with Pandora FMS Server.

To configure the other agent just set server_ip parameter to IP address of Drone Agent with proxy mode enabled and that all. The agents will use Drone Agent to connect with Pandora FMS Server.

I must do a double proxied connection

If you need you can connect a Drone Agent to another Drone Agent, and it is very easy.

To perform the double proxy you must configure Drone Agent which can connect to Pandora FMS Server setting server_ip to Pandora FMS IP address, proxy_mode to 1 and the other parameters if you need.

To configure the second Drone Agent just set server_ip to first Drone Agent and of course enable the proxy mode by setting proxy_mode to 1.

With this configuration, an agent connected to the second Drone Agent can send data to Pandora FMS Server through the two proxies.

1.3.9.1.2 Broker mode

Broker mode is designed to "recreate" diferent agents (as entity) from a single software agent installed in a server. Broker agent execute different setups, like if it has different personalities or different agents installed in the same server with different configurations. Each configuration file is independent and can have it's own plugins, inventory modules, etc. Of course it can be remotely managed, as any other agent. This is perfecto to monitor servers / comm devices nearby the Broker mode, and useful when you cannot reach a router but can install an agent in a nearby host. You can for example, monitor ten routers from a single agent, and have eleven agents in your Pandora FMS console (10 routers + 1 host).

Is important to note that in the configuration of the agent set like a broker agent the broker_agent token will be ignored.

The main features of "broker mode" are:

  • Send local data with another agent name. Useful to monitoring different instances of a software applicationn as independent agents.
  • Send data from remote devices/checks executed from a single hosts, and have it in Pandora FMS like them are different independent agents.
1.3.9.1.2.1 Examples

Send data to server with different agent names, using different configurations

Modify your pandora_agent.conf with following lines:

broker_agent router_1
broker_agent router_2
broker_agent router_3

Automatically (in next execution or restart) you will have three new files: 'router_1.conf', 'router_2.conf' y 'router_3.conf', will be an exact copy from origial "pandora_agent.conf" file, excepting "agent_name" which will be selected from broker_agent call.

You now have four agents, with different configuration files, you can now add different modules in each configuration file, for example, edit “router_1.conf” and add:

Sample of remote check

Add to remote configuration file 'pandora_agent.conf' following line:

broker_agent server_1

A new file will be created, called 'server_1.conf' and we will edit it to add specific modules for this broker agent:

module_begin
module_name Check SSH Status
module_type generic_proc
module_tcpcheck 192.168.1.1
module_port 22
module_timeout 5
module_end

This configuration can interest us when making checks against another remote machine even has an agent installed Pandora, is unattainable by the server.

This feature is available since 4.0 version.

1.3.10 Agent / Module autocreation from XML file / Learning mode

Pandora FMS supports the creation of agents and/or modules in an automated way, when you receive the information coming from an XML (data server). This happen automatically, unless you disable completely this behaviour by disabling the server autocreate parameter. The "creation" happens only the first time an agent data arrives to the server. That means, you can create the information but you cannot update the agent/module information each time you get a new XML, but except a few exceptions you will see below.



Learning mode.png

This behaviour could be avoided in specific agents by disabling the learning mode of the agent. Disabling this feature, that agent will not create new modules when XML arrives with new module information.


1.3.10.1 Data loaded from the XML in the creation of an agent

Data stored for an agent are following:

In 4.x version:

  • Agent name.
  • IP address.
  • Agent description.
  • Agent's parent.
  • Timezone offset.
  • Group.
  • Operating system.
  • Agent tnterval.
  • Agent version

In 5.x version

The same as in 4.x version, plus following:

  • Custom fields.
  • Custom ID.
  • URL address.

1.3.10.2 Data modified in the agent, when receiving an XML (learnmode enabled)

  • Agent IP address
  • GIS data (if GIS is enabled and GIS data not locked for that agent).
  • Agent parent ( if defined in server setup )
  • OS Version.
  • Agent version.
  • Timezone.

1.3.10.3 Data added to the module on creation time

The first time you get data coming from an XML for a module, data readed from the XML and inserted in the system are:

In 4.x version

  • Name.
  • Type.
  • Description.
  • Máx, Mín value filter.
  • Post proccess.
  • Module interval.
  • Min/max Critical.
  • Min/max Warning.
  • Disabled module.

In 5.x version

The same as in 4.x plus the following:

  • Units.
  • Module group.
  • Custom ID.
  • Str. Warning/Critical.
  • Critical instructions.
  • Warning instructions.
  • Unknown instructions.
  • Tags.
  • Critical inversion mode.
  • Warning inversion mode.
  • Quiet mode.
  • Min. FF Threshold

1.3.10.4 Data loaded when module already exists

When data server process an XML containing information for a pre-existant module, part of it's information will be overwritten / updated. In 5.x version only description and extended information (see next epigraph) are updated.

This behaviour in 4.x version is different, because server updates some parameters in the module on update: max, min, description, post process, module interval, max/min for critical and warning thresholds and flip flip threshold values.

Note: GIS data are always update unless you have the GIS update disabled for that agent (this is configured in agent GIS setup).


1.3.11 Extended module information

This epigraph is for advanced / development environments. You can send custom XML (using your own app or altering pandora agent source code), for example this XML has two "custom" tags (rack_number, and severity):

<module>
    <name><![CDATA[battery_level]]></name>
    <description><![CDATA[The actually device battery level]]></description>
    <type><![CDATA[generic_data]]></type>
    <data><![CDATA[61]]></data>
    <rack_number>2</rack_number>
    <severity>MAJOR</severity>
  </module>

This will be shown as this:



Extended module xml.png

NOTE: This fields doesn't store history values, only stores last received value from XML.

Go back to Pandora FMS documentation index