Pandora:Documentation en:Configuration

Go back Pandora FMS documentation index

Pandora FMS has three basic components which must be properly configured for correct operation. The first two are the server and the web console, which should interact between each other and the database to introduce, to process and to show the stored data. There are also the software agents which transmit the data to the Pandora FMS server.

In this chapter, we are going to explain the configuration files of the three elements and others which are important for a correct performance of the application components.

1 Server

Pandora FMS server has a configuration file that allows several application parameters to be adjusted to obtain excellent performance. The configuration file pandora_server.conf is located at /etc/pandora/ by default.

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. The comments must start the line and as for the entire line, the .conf file must not have any line which shares code and comment.

Now we are going to explain all the configuration parameters.

1.1.1 servername

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

1.1.2 incomingdir

It's the incoming directory of XML data packages. It's located under '/var/spool/pandora/data_in/' by default. You can improve the performance by setting up a RAM disk or very fast hard drive here.

1.1.3 log_file

The Pandora FMS record file (log). It's located under /var/log/pandora/pandora_server.log by default. This is the main logfile and it's very important for debugging.

1.1.4 snmp_logfile

Located under /var/log/pandora/pandora_snmptrap.log by default. This is a log file which contains all received SNMP traps BEFORE the Pandora FMS server processes them. It's not recommended to edit or even touch this file.

1.1.5 errorlog_file

The Pandora FMS error registry file (log). It's located under /var/log/pandora/pandora_server.error by default. This logfile stores all non-controlled errors or non-captured output from tools executed by the server. It's important for locating problems and debugging as well.

1.1.6 dbname

The name of the database the server will connect to. It's located under 'pandora' by default.

1.1.7 dbuser

Username used in the Pandora database connection. It's located under 'pandora' by default.

1.1.8 dbengine

Deprecated: always 'Mysql' (default value).

1.1.9 dbpass

The password for the connection against the Pandora FMS Database.

1.1.10 dbhost

The IP address or equipment name which hosts the Pandora FMS database. In reduced installations, it's usually the same equipment where the server is located, which is localhost.

1.1.11 dbport

It's used to define a different port in your database setup (optional).

1.1.12 daemon

It shows whether or not Pandora server is executed as a daemon. If the server is launched with the '–D' option, it's executed as daemon.

1.1.13 verbosity

The detail level for the server and error messages, the register or log files. 0: default, 1: detailed, 2: debug, 3-10: noisy. If you experience any problem with Pandora FMS, put this value to 10 to get the maximum detail. High values (e.g. 10) are not intended to be used in production systems because they have a great performance impact.

1.1.14 master

Master Server priority. The running server with the highest master value will be the master. Ties are broken at random. If set to 0, this server will never become master. See the High Availability (HA) chapter for more information.

1.1.15 snmpconsole

'1' enables the SNMP traps reception console, '0' disables it. The console depends on the snmptrapd UNIX service. Before starting Pandora FMS server, please make sure that the 'snmptrapd' process IS NOT running on your server.

1.1.16 networkserver

'1' enables the Pandora FMS Network Server, '0' disables it.

1.1.17 dataserver

'1' enables the Pandora FMS Data Server, '0' disables it. This server processes the XML files coming from the agents, among many other tasks. This server should be always running on the system.

1.1.18 reconserver

'1' enables the Pandora FMS Recon Server, '0' disables it. If you don't want to use the recon server, it's better to keep it disabled.

1.1.19 pluginserver

'1' enables the Pandora FMS Plugin Server, '0' disables it.

1.1.20 predictionserver

'1' enables the Pandora FMS Prediction Server, '0' disables it. Prediction server manages Services and synthetic modules, among others.

1.1.21 wmiserver

'1' enables the Pandora FMS WMI Server, '0' disables it.

1.1.22 inventoryserver

(Pandora FMS Enterprise only)

'1' enables the Pandora FMS Inventory Server, '0' disables it. It manages the remote inventory data. The inventory data transmitted by software agents is processed by the Data Server, so there's no need to enable this server unless you want to get inventory data from devices monitored remotely.

1.1.23 exportserver

(Pandora FMS Enterprise only)

'1' enables the Pandora FMS Export Server, '0' disables it.

1.1.24 webserver

(Pandora FMS Enterprise only)

'1' enables the Pandora FMS Web Server (also known as Goliath Server), '0' disables it.

1.1.25 eventserver

(Pandora FMS Enterprise only)

'1' enables the Pandora FMS Event correlation Server, '0' disables it (default value is '1').

1.1.26 icmpserver

(Pandora FMS Enterprise only)

Enables (1) or disables (0) the Enterprise ICMP server (default value is 0). The Enterprise ICMP server uses NMAP to perform block ICMP requests. The XML output of older versions of NMAP does not report round-trip time. If all your ICMP latency modules return a value of '0', please set this configuration variable to '0'. If the version is incorrect, please install NMAP 5.51 or higher. If you're unsure, you may run NMAP and see if the round-trip time is returned:

nmap -nsP -PE -oX - www.pandorafms.com | grep srtt

1.1.27 snmpserver

(Pandora FMS Enterprise only)

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

1.1.28 network_timeout

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

1.1.29 server_keepalive

Time before classifying the server as 'down' in seconds. The default value is '45'.

1.1.30 server_threshold

The number of seconds for the main loop. Its value is '5' by default. This is a very important configuration token, because it defines how many times Pandora FMS looks into the database or on the hard drives for new data to process. '5' through '10' are good values in most cases - the minimum value is '1'. If you set it to '1', the system CPU load will be very high. You can set it to '1' in in specific cases, e.g. your server has been down for a while and you're required to process the pending XML files and network modules as quick as the system can. Set this to '1', wait for all pending modules / XML processes to be finished and set them to 5 - 15 again. This value, used in conjunction with 'server_threads' and 'max_queue_files', is used to adjust the performance of your server.

1.1.31 network_threads

Number of threads for the network server. It shows how many checks can be done at the same time, but as it increases it requires much more processing capacity. Its default value is 5. Please do not use more than 20 - 25 threads or the system could either get unstable or have very low performance.

1.1.32 icmp_checks

Defines the number of pings to each 'icmp_proc' kind of module. At least one of these checks has to give back '1' to the module for getting classified as correct. Its default value is '1'. If you set '5' here and the first ping is OK, the other 4 will be skipped.

1.1.33 (> 5.1SP2) icmp_packets

Defines the number of ICMP packets sent in each ping request. 1 by default.

1.1.34 tcp_checks

Number of TCP retries in case the first one fails. Its default value is 1.

1.1.35 tcp_timeout

Specific timeout for TCP connections. The default value is '30'.

1.1.36 snmp_checks

Number of SNMP retries in case the first one fails. The default value is '1'.

1.1.37 snmp_timeout

Specific expiration time for SNMP connections. Its default value is '3'.

1.1.38 snmp_proc_deadresponse

Gives back 'DOWN' if it's impossible to connect with a boolean SNMP module (proc) or if it gets 'NULL' as a response. If set to '0' it should be ignored.

1.1.39 plugin_threads

Number of threads for the plugin server. It shows how many checks could be done simultaneously. Its default value is '3'.

1.1.40 plugin_timeout

Timeout for the checks with plugins. After this time, the module status will be shown as 'unknown'. Its default value is 5, so you'll need to raise this value if your plugins' execution take a few seconds. If a plugin has a higher timeout value, the value set at this parameter of the server will prevail.

1.1.41 wmi_timeout

WMI timeout checks. After this time, the module status will be shown as 'unknown'. Its default value is '10'.

1.1.42 wmi_threads

Number of threads for the WMI server. It shows how many checks can be done simultaneously. Its default value is '2'.

1.1.43 prediction_threads

Number of threads for the prediction server.

1.1.44 recon_threads

Number of threads for the network recon server. Shows how many checks can be done simultaneously. Its default value is '2'.

1.1.45 dataserver_threads

Number of threads for the data server. Shows how many threads for XML processing can be active simultaneously. Its default value is '2'. Recommended max. is '4'.

1.1.46 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.47 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.48 web_threads

(Pandora FMS Enterprise only)

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

1.1.49 web_timeout

(Pandora FMS Enterprise only)

Default timeout in seconds for web modules.

1.1.50 web_engine

(Pandora FMS Enterprise only)

Set this parameter to "curl" to use cURL instead of LWP for web monitoring. The cURL binary must be installed and set in PATH.

1.1.51 mta_address

Mail Server IP address (Mail Transfer Agent)

1.1.52 mta_port

Mail server port ('25' by default)

1.1.53 mta_user

Mail server user (if necessary for use with authentication)

1.1.54 mta_pass

Password for the mail server (if necessary with authentication)

1.1.55 mta_auth

Mail server authentication system (if necessary. The supported values are: 'LOGIN', 'PLAIN', 'CRAM-MD5' and 'DIGEST-MD')

1.1.56 mta_from

Mail address from which messages will be sent. The default value is [email protected].

1.1.57 mail_in_separate

'1' by default. If set to '1', it delivers separate mail for each destination. If set to '0', the mail will be shared among all destinations.

1.1.58 xprobe2

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

1.1.59 snmpget

Required for SNMP checks. The default path is /usr/bin/snmpget. It refers to the location of the SNMP standard client for the system. It's recommended not to change this parameter unless you know exactly what you're doing.

1.1.60 nmap

Required for the recon server. The default path is /usr/bin/nmap. It's recommended not to change this parameter unless you know exactly what you're doing.

1.1.61 (> 5.1) nmap_timing_template

A value that specifies how aggressive nmap should be, from 1 to 5. '1' means slower but more reliable, '5' means faster but less reliable. '2' by default.

1.1.62 (> 5.1) recon_timing_template

Like nmap_timing_template, but applies to Satellite Server and Recon Server network scans.

1.1.63 plugin_exec

Shows the absolute path to the program which executes the plugins in a controlled way in time. The default path is /usr/bin/timeout. It's recommend not to change this parameter unless you know exactly what you're doing. If your base system doesn't have a timeout command, you should use the path /usr/bin/pandora_exec instead.

1.1.64 autocreate_group

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

1.1.65 autocreate

If you change this value to '1' the agents will be created automatically when processing a XML file which hasn't been sent by an existing agent. When set to '0', autocreation is disabled and XML files sent by unknown agents will be discarded, so they will have to be created by hand (bear in mind, agent names are case sensitive).

1.1.66 max_log_size

Maximum size of Pandora FMS log file, in bytes. When this size is reached, the log file's name is changed to pandora_server.log.old and the server generates a new one. Default size is 65536 Bytes.

1.1.67 max_queue_files

Maximum number of XML data files read by the Pandora FMS Data Server from the directory specified by incomingdir. This prevents the Data Server from trying to process too many files, which would affect server performance. Default value is 5000.

Incremental modules may not work properly if this value is not big enough to hold all the XML data files.

1.1.68 use_xml_timestamp

Deactivated by default. If activated ('1') it uses the XML file timestamp, generated with time and date of the server in the moment of reception, instead of the internal XML file timestamp, which was generated by the server. This can be deactivated globally in case of conflict with the use of the dates generated by the agents and date / hour (timestamp) of the server as a reference for all data. In systems which experience problems with synchronization or systems with wrong date / hour, it's an option which could solve almost any problem.

1.1.69 auto_restart

Deactivated by default. If it's 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 a degradation or loss of control of any thread or specific server in use with Pandora FMS.

1.1.70 restart

Default value is '0'. If set to '1', the server will restart on critical errors after a given number of seconds.

1.1.71 restart_delay

Default value is '60'. The number of seconds the server will wait before restarting after a critical error if restart is enabled.

1.1.72 self_monitoring

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

1.1.73 (>= 5.1SP1) self_monitoring_interval

Time interval for self_monitoring in seconds.

1.1.74 update_parent

Although the server has a parameter to define if the agent can update it's parent by sending the parents name on the XML: If this parameter is not defined or set to '0', the agent information is ignored. If not, when the server receives an XML with 'parent_name' attribute, it is going to look for an agent with this name - and if it's found, it updates the parent of the agent from the XML.

1.1.75 icmp_threads

(Pandora FMS Enterprise only)

Number of threads for the ICMP Enteprise server (default value is '3').

1.1.76 snmp_threads

(Pandora FMS Enterprise only)

Number of threads for the Enteprise SNMP server (default value is '3').

1.1.77 block_size

(Pandora FMS Enterprise only)

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

1.1.78 braa

(Pandora FMS Enterprise only)

Location of the braa binary required for the Enterprise SNMP server (default path is '/usr/bin/braa').

1.1.79 braa_retries

(Pandora FMS Enterprise only)

Number of retries before braa handles a module over to the Network Server in case of an error.

1.1.80 event_window

(Pandora FMS Enterprise only)

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

1.1.81 wmi_client

Default WMI client used (default value is 'wmic'). Changing this value is not recommended.

1.1.82 activate_gis

Flag to activate GIS (positional information for agents and maps). It's deactivated by default.

1.1.83 location_error

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

1.1.84 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 tries to query the SQL database to geolocate the IP discovered.
• file The recon task tries to find the geolocation information of the IP discovered in the file indicated in the 'recon_reverse_geolocation_file' parameter.

1.1.85 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.86 recon_location_scatter_radius

Radius (in meters) of the circle where the agents are randomly placed when found by a recon task. Center of the circle is guessed by geolocating the IP.

1.1.87 google_maps_description

This enables realtime reverse geocoding using Google Maps public API. This requires Internet access and could have performance penalties processing GIS information due to the connection needed to resolve all GIS input. NOTE: If you don't pay the Google, they are going to ban your IP in a few days.

1.1.88 openstreetmaps_description

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

1.1.89 event_file

This configuration token lets you configure a text file where events, generated by Pandora FMS, will be written in CSV format.

For example:

event_file /var/log/pandora/pandora_events.txt

The first line of the text file is a header containing a list of field names. The contents of pandora_events.txt could be:

id_agente,id_grupo,evento,timestamp,estado,utimestamp,event_type,id_agentmodule,id_alert_am,criticity,user_comment,tags,source,id_extra,id_usuario,critical_instructions,warning_instructions,unknown_instructions,ack_utimestamp
Agent_1,Servers,Module Connections opened (136.00) is going to NORMAL,2013-07-01 19:00:57,1,1372698057,going_down_normal,Connections  opened,,2,,,Pandora,,,,,,1372698057
Agent_2,Servers,Alert recovered (Critical condition) assigned to (Network Traffic (Outgoing)),2013-07-01 19:00:59,0,1372698059,alert_recovered,Network Traffic (Outgoing),Critical condition,4,,,Pandora,,,,,,0

1.1.90 snmp_storm_protection

Pandora FMS's SNMP Console will not process more than this number of SNMP traps from a single source in a defined time interval. If this number is reached, an event is generated.

1.1.91 snmp_storm_timeout

Time interval for snmp_storm_protection in seconds.

To e.g. prevent a single source from sending more than 1000 traps per 10 minutes:

snmp_storm_protection 1000
snmp_storm_timeout 600

1.1.92 text_going_down_normal

Text for the event that is generated when a module goes to normal status. The macros '_module_ and _data_' are supported.

text_going_down_normal Module '_module_' is going to 'NORMAL'(_data_)

1.1.93 text_going_up_critical

Text for the event which is generated when a module goes to 'critical' status.

1.1.94 text_going_up_warning

Text for the event which is generated when a module goes from 'normal' to 'warning' status.

1.1.95 text_going_down_warning

Text for the event which is generated when a module goes from 'critical' to 'warning' status.

1.1.96 text_going_unknown

Text for the event which is generated when a module goes to 'unknown' status.

1.1.97 event_expiry_time

Events older that the specified time (in seconds) will be auto-validated. Set to '0' to disable this feature.

To e.g. automatically validate events 10 hours after they were generated, just use the command:

'event_expiry_time 36000'

1.1.98 event_expiry_window

This parameter is used to reduce the impact of 'event_expiry_time' so the entire event table does not have to be searched. Only events more recent than the specified time window (in seconds) will be automatically validated. This value must be bigger than event_expiry_time.

The default value ('86400') is the equivalent of one day:

event_expiry_window 86400

1.1.99 (>= 5.X) snmp_forward_trap

Enables ('1') or disables ('0') the SNMP trap forwarding to the host specified in snmp_forward_ip.

1.1.100 (>= 5.X) snmp_forward_ip

IP address of the host to which SNMP traps will be forwarded to.

Bear in mind that setting a local IP address will cause a forwarding loop that is going to induce a collapse of the Monitoring Server.

1.1.101 (>= 5.X) snmp_forward_version

SNMP version to use when forwarding SNMP traps. This token can only have the following values:

• 1
• 2c
• 3

1.1.102 (>= 5.X) snmp_forward_secName

Only for SNMP version 3. It defines the security name. More information at snmpcmd's man page.

1.1.103 (>= 5.X) snmp_forward_engineid

Only for SNMP version 3. It defines the authoritative (security) engine ID. More information at snmpcmd's man page.

1.1.104 (>= 5.X) snmp_forward_authProtocol

Only for SNMP version 3. It defines the authentication protocol. This token can only have the following values:

• MD5
• SHA

More information at snmpcmd's man page.

1.1.105 (>= 5.X) snmp_forward_authPassword

Only for SNMP version 3. It defines the authentication pass phrase. For more information, please go to snmpcmd's man page.

1.1.106 (>= 5.X) snmp_forward_privProtocol

Only for SNMP version 3. It defines the privacy protocol. This token can only have the following values:

• DES
• AES

More information at snmpcmd's man page.

1.1.107 (>= 5.X) snmp_forward_privPassword

Only for SNMP version 3. It defines the privacy pass phrase. More information at snmpcmd's man page.

1.1.108 (>= 5.X) snmp_forward_secLevel

Only for SNMP version 3. It defines the security level. This token can only have the following values:

• noAuthNoPriv
• authNoPriv
• authPriv

More information at snmpcmd's man page.

1.1.109 (>= 5.1) claim_back_snmp_modules

If set to 1, SNMP modules run by the Network Server will be claimed back by the SNMP Enterprise Server when the database maintenance script (pandora_db) is run.

1.1.110 (> 5.1) snmpconsole_threads

Number of threads for the SNMP Console. Each thread processes an SNMP trap. Set to '1' by default.

1.1.111 (> 5.1) translate_enterprise_strings

(Pandora FMS Enterprise only)

If set to 1 the SNMP console will attempt to translate enterprise strings when processing SNMP traps. Set to '1' by default.

1.1.112 (> 5.1) translate_variable_bindings

(Pandora FMS Enterprise only)

If set to 1 the SNMP console will attempt to translate variable bindings when processing SNMP traps. Set to '0' by default.

1.1.113 (> 5.1SP1) async_recovery

If set to 1 asynchronous modules that do not receive data for twice their interval will become normal. Set to 0 to disable.

1.1.114 (>= 6.0) console_api_url

Console's api direction. Usually the direction of the server and the console ending with the route /include/api.php.

1.1.115 (>= 6.0) console_api_pass

Password of the console's api. This password can be found in the general section of the setup and can be left empty.

1.1.116 (>= 6.0) console_user

User of the console with permissions to execute the required actions, like get a module graph image to put it in an alert email.

1.1.117 (>= 6.0) console_pass

Password of the previously introduced console user.

1.1.118 (>= 6.0) unknown_interval

Time interval (as a multiple of the module interval) before a module becomes unknown. Twice the module's interval by default.

1.1.119 (>= 6.0) global_alert_timeout

Defines -in seconds- the maximum processing time of an alert. When that time is elapsed, the execution is interrupted. By default, it is 15 seconds. If this token is set to 0, Pandora Server ignores it and the alert execution will not be interrupted.

1.1.120 (>= 6.0) remote_config

This parameter controls the possibility to configure the server remotely from the console Manage servers view. It works by Tentacle similarly to agents remote configuration. It's deactivated by default. This parameter, in addition to other remote configuration tokens, is only useful in the Enterprise version.

1.1.121 (>= 6.0) remote_config_address

Machine IP Address where remote configuration files will be sent. It is localhost by default.

1.1.122 (>= 6.0) remote_config_port

Tentacle port for remote configuration. It is 41121 by default.

1.1.123 (>= 6.0) remote_config_opts

Allows to give additional parameters to the Tentacle client for advanced configurations. They should be between "" (e.g. "-v-r 5").

1.1.124 (> 6.0) warmup_event_interval

Module status change events will not be generated and module alerts will not be executed for the specified number of seconds since the server starts up (disabled by default). System events will be generated when the warmup interval starts and ends, but the ending event will be delayed until a status change or an alert check occurs.

1.1.125 (> 6.0) warmup_unknown_interval

Modules will not become unknown (so no unknown events will be generated) and keepalive modules will not be set to 0 for the specified number of seconds since the server starts up (5 minutes by default). System events will be generated when the warmup interval starts and ends.

1.1.126 (> 6.0SP4) enc_dir

Path to a directory containing additional .enc files for the XML parser. This files will be automatically loaded by the Data Server at startup.

1.1.127 (> 6.0SP4) unknown_events

Enable (1) or disable (0) events related to the unknown module status.

1.1.128 (>= 7.0) dynamic_updates

The number of times dynamic thresholds will be recalculated per dynamic interval.

1.1.129 (>= 7.0) dynamic_warning

Percentage relative to the length of the critical interval used to calculate dynamic warning thresholds. The lower the value, the closer the critical and warning thresholds will be.

1.1.130 (>= 7.0) dynamic_constant

Percentage relative to the module's mean used to adjust the module's standard deviation for constant data. A higher value results in wider dynamic threshold intervals.

1.2 Snmptrapd configuration

The SNMP Console of Pandora FMS 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 version 5.3, access control checks will be applied to incoming notifications.

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

You're probably required to configure your snmptrapd using the file /etc/snmp/snmptrapd.conf. If it doesn't exist, please 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.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 send data in alternative ways: local transfer (NFS,SMB),SSH or FTP, etc. IF you want them to send the data packages using the Tentacle protocol, then you're required to configure a Tentacle server where this data is intended to be received. When a Pandora FMS server is installed, a Tentacle server is also installed in the same machine by default.

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

/etc/init.d/tentacle_serverd

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

PANDORA_SERVER_PATH

The path to the entry directory of data. The default path is /var/spool/pandora/data_in

TENTACLE_DAEMON

The Tentacle daemon. The default command is 'tentacle_server'.

TENTACLE_PATH

The path to the Tentacle binary. The default path is '/usr/bin'.

TENTACLE_USER

User from which the Tentacle demon will be launched. The default value is pandora.

TENTACLE_ADDR

Direction to listen to the data packages. If you fix 0.0.0.0. it listens to all of them. The default value is to listen in all directions. This is true when it's IP is 0.0.0.0.

TENTACLE_PORT

The listening port for package reception. By default it's 41121 (official port assigned by IANA).

TENTACLE_EXT_OPTS

Additional options for executing the Tentacle server. You can set up Tentacle to use authentication with certs (x509) and/or symmetric password in both sides here.

1.4 Tentacle secure configuration

Both the server and the agents can use a secure configuration with SSL and/or password using Tentacle. The communication can be established tentacle_client -> tentacle_server, or tentacle_client -> tentacle_proxy -> tentacle_server.

The most common actions are:

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 on the client side (TENTACLE_EXT_OPTS)

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

1.4.1 Secure configuration, real case

How to configure the agents and the Tentacle server for a secure connection, using Tentacle proxy as well.

Firstly, we recommend carrying out the previous testing manually from the shell terminal to make sure that the configuration, parameters and certificates are correct.

Manual testing:

1. Start tentacle_server manually:

 sudo -u user tentacle_server -x password -e tentaclecert.pem -k tentaclekey.pem -f cacert.pem -s /tmp -v

2. Start proxy manually (only if you will use a Tentacle proxy, if not, skip this step):

 sudo -u user tentacle_server -b ip_server -g 41124

3. Launch tentacle_client manually:

 sudo -u user tentacle_client -a ip_proxy/ip_server -x password -e tentaclecert.pem -k tentaclekey.pem -v /bin/ls (or any file)

It is necessary to ALWAYS specify the absolute path where the certificates are stored, for example /home/tentaclecert.pem

Once we have checked that the sending of the file has been successful, we can proceed to permanently configure tentacle_server and the clients.

To configure tentacle_server with the secure certificate options, you have to edit the starting script of the tentacle_serverd service, commonly on /etc/init.d/tentacle_serverd, the same for the intermediate proxy. To configure the agents to use the secure tentacle communication, you have to edit the configuration files of the agent pandora_agent.conf, commonly on /etc/pandora/pandora_agent.conf.

Permanent configuration:

1. Start the server with SSL. Modify the script /etc/init.d/tentacle_serverd. Search the line TENTACLE_EXT_OPTS, and add "-x password -e tentaclecert.pem -k tentaclekey.pem -f cacert.pem". It should look like this:

 TENTACLE_EXT_OPTS="-i.*\.conf:conf;.*\.md5:md5;.*\.zip:collections -x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem -f /home/cacert.pem"

2. Start the proxy. Modify the script /etc/init.d/tentacle_serverd on the system that will act as a proxy. Same as in the previous step, search for the line TENTACLE_EXT_OPTS, and add "-b ip_server -g 41121". Like this:

 TENTACLE_EXT_OPTS="-i.*\.conf:conf;.*\.md5:md5;.*\.zip:collections -b 192.168.70.208 -g 41121"

3. Launch the agent with the related options. Modify the pandora_agent.conf file, search the token server_opts and add "-x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem". Don't forget to set the token server_ip with the ip of the proxy instead of the main server if you use it. It should look like this:

 server_opts -x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem

If you don't want to use any of the options, like for example the password, just don't set it on the configuration.

2 WEB Console

The Pandora FMS web console has a configuration file which usually is created and configured when it's installed. If the installation is done through the DEB or RPM packages or from the Pandora FMS installation CD, then it's configured automatically. If it's installed manually, it's contained in the tarball package. It could also be configured by the web assistant through http://ip_instalacion_consola/pandora_console/install.php

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

2.1 Configuration File config.php

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

$config["dbname"]

Database name to connect to. The default value is 'pandora'.

$config["dbuser"]

User name for the connection against the Pandora database. The default value is 'pandora'.

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

$config["dbhost"]

IP address or equipment name which hosts the Pandora FMS database. In a reduced installation, it is usually on the same equipment as the server, which is 'localhost'.

$config["homedir"]

Directory where the Pandora FMS web console is located. This is usually '/var/www/pandora_console' or '/srv/www/htdocs/pandora_console'.

$config["homeurl"]

Base directory for Pandora FMS. This is usually '/pandora_console'.

$config["public_url"]

The full URL is set with the string value, the value is the URL of inside Pandora FMS Server if you use an inverse proxy e.g. 'mod_proxy' from Apache.

2.1.1 Redirection to '/pandora_console' from /

If you only have one Pandora FMS in your Apache server then it's possible that you could benefit by automatically re-addressing '/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' or '/srv/www/htdocs'):

For the case if users connect with the URL / of their server. You can create the following file index.html and put it in the web server's root directory:

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

3 Pandora FMS Software Agents

3.1 What is an Agent?

Pandora FMS software agents collect all data from their systems. They are executed on local systems, but they can also collect information remotely through the monitoring system's agent installation on several different machines.

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

Pandora FMS is 100% open code, e.g. in the way the agents collect and send information is documented and could analyze and / or modify the code to suit to your needs. An agent could be created again in any programming language and could also be easily updated to improve aspects of the program that hadn't been covered completely.

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

3.1.1 General Role of Software Agents

The Software Agents general role is based on obtaining information about the operating system on which they are installed, to collect this information and send it to the Server.

Pandora FMS software agents use the specific commands of the operating system in order to obtain the information. The Pandora FMS Data Server keeps and processes the data generated by these commands and sends it to the server in an XML file.

The information returned by these commands is kept in what is called a 'Module'. If the agent has been added in 'learning mode', the modules which have been sent and which haven't been previously defined in the logical agent will be created automatically by the server.

3.2 Introduction to the Agent Configuration

The agent is controlled by a unique configuration file which has a syntax which is almost identical in UNIX systems as in Windows Systems. This file is named pandora_agent.conf and it's located in the agent installation directory (in Windows Systems) and under /etc/pandora/pandora_agent.conf in Unix systems.

This configuration file is a plain text file with different options which could all be modified by the administrator. To modify it or its performance, just configure where the data is supposed to get sent to, which things have to be monitored and how it's going to be done.

Configuration file encoding. It's very important and has to have the same value which is set in the encoding configuration parameter. If the encoding is set properly, the reception of data with improper encoding characters is going to be avoided.

Now we're going to deal with all the general parameters for the Software Agent and the monitoring modules - which are the ones defining how and what is locally monitored with the Software Agent.

3.3 General Agent Parameters

The Configuration of the General Agent Parameters is defined in this section. Some of them are common for all systems and others are intended specifically for Windows or Unix machines. The general parameters are:

The first time the server receives data from an agent is going to save all of the information into the database. For the following received data it will only update (depending on learning mode status enabled/disabled) the following fields from XML file: version, date, OS version, and the following parameters from the configuration file: gis_exec, latitude, longitude, altitude parent_agent_name, timezone_offset, address and custom_field.

3.3.1 server_ip

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

3.3.2 server_path

The server path is the comprehensive file path where the server stores all the data which was sent by the agent. The default path is '/var/spool/pandora/data_in'.

3.3.3 temporal

This is the complete path of the folder where the agent stores the local data before sending it to the server.

Remember! Data packages are deleted by default once the agent tries to contact with the Pandora FMS Server. Whether the connection was successful or not is not taken into account (although this function could be changed, as we see later).

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

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

3.3.4 description

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

3.3.5 group

Sends the name of the group we want the agent to own, and that is only used in the moment the agent is created. The Pandora FMS Server will automatically use this group to put the agent in the selected group.

3.3.6 temporal_min_size

If the free space (in MB) of the partition in which the temporary directory is located is lower than this value, it would continue generating data packages. It avoids the disk becoming full if the connection with the server is lost during an extended interval under any circumstances.

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.

3.3.8 interval

This is the time interval (in seconds) in which the agent is going to collect data from the host system and send the data packages to the server. The range of recommended values constitutes from 300 (5 minutes) to 600 (10 minutes). This value could be bigger, but it's important to consider the impact of a higher value in the database. The execution is not recommended if it's configured to be below 30-60 seconds.

3.3.9 disable_logfile

This parameter disables log writing in pandora_agent.log. Only for Windows.

3.3.10 debug

This parameter is used to check the creation of data in the files, so the data content of the files could be checked. No data is destroyed when the process has been completed, 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).

Before Pandora 6.0, an agent in debug mode did not report to server.

3.3.11 agent_name

This is an alternative name for the host. This parameter is optional. 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.

3.3.12 (>=5.1SP2) agent_name_cmd

If you want to define agent name using external command, set this parameter. This is optional. When this parameter is set, 'agent_name' is ignored. External command should return agent name string to STDOUT. If that returns several rows, the string in the first row is used as the agent name.

3.3.13 (>=7.0) agent_alias_cmd

If you want to define agent alias using external command, set this parameter. This is optional. When this parameter is set, 'agent_alias' is ignored. External command should return agent alias string to STDOUT. If that returns several rows, the string in the first row is used as the agent alias.

3.3.14 address

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

3.3.15 encoding

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

3.3.16 server_port

This parameter allows to identify the remote port of the server that is waiting. By default it's 41121 for Tentacle. In case Tentacle is not used or that the server is configured to use another port, this is the place where it should be changed.

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

3.3.18 (>= 6.0) transfer_timeout

This parameter specifies timeout in seconds for file transfer programs execution. The default value is '30' if not defined.

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

3.3.20 server_ssl

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

3.3.21 server_opts

Specific for the Tentacle transfer mode. Allows to give additional parameters to the Tentacle client for advanced configurations. For example: server_opts -v -r 5

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

server_opts -y user:[email protected]:8080

This will force the tentacle client to use 'proxy.inet' on port 8080 using "user" and "pass" for authentication. If you intend to use a proxy on e.g. 192.168.1.2 on port 9000 without credentials, the command would have to be:

server_opts -y 192.168.1.2:9000

3.3.22 delayed_startup

This parameter allows the Pandora FMS agent to be configured in order to start working after any specific amount of time (in minutes) after manual execution. Useful for systems with a lot of load packages. It's deactivated by default, which means the Pandora FMS agent is going to start working from the moment it is executed manually. This option is only valid for UNIX agents.

3.3.23 pandora_nice

This parameter allows the priority the Pandora FMS agent process will have within the system to be specified. It's only available for Unix / Linux agents.

3.3.24 autotime

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

3.3.25 cron_mode

With this parameter, it's possible to make the agents using the Linux crontab functions to execute itself in a predetermined interval instead of using the agents internal system to execute itself at a certain time. It's deactivated by default and it's -not- recommended to use it unless it's an absolute necessity.

3.3.26 remote_config

This parameter controls the possibility to configure the agent remotely from the console. '1': The remote configuration is allowed. '0': The remote configuration is not allowed. It's deactivated by default.

3.3.27 xml_buffer

The default value is '0'. If set to '1', the agent is going to save any XML data files which couldn't be sent and retries later.

if you are in a secured environment under UNIX and want to enable the XML buffer, you should consider changing the temporal directory, since anyone has the right to write into '/tmp'.

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
interval        300 
debug           0 
agent_name      box01 
server_port     41121 
transfer_mode   tentacle 
remote_config   1 

3.3.28 timezone_offset

The agent can set its timezone offset with the server now. It's very useful to have agents with a different timezone synchronized on the same time with a server in another timezone. Agents will send the shifted timezone to the server.

# Timezone offset: Difference with the server timezone
timezone_offset 3

It is calculated by subtracting the agent's timezone from the server's timezone. For example, if the server's timezone is UTC+1 and the agent's timezone is UTC-5, the timezone offset should be 6 = 1 - (-5).

3.3.29 parent_agent_name

If the server allows it, it's also now possible to update the parent of an agent by sending the name of the parent agent in XML.

parent_agent_name parent_name

3.3.30 agent_threads <threads>

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

3.3.31 include <filename>

This is the alternative configuration file path. This file can contain additional modules and collections alongside the ones found in the main configuration file. This token is optional. In matters related to perl agents, it allows for filename wildcards.

3.3.32 broker_agent <name>

It manages configuration and data collection from an agent as if they were be multiples of the same. 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 it. These new agents will start reporting after the next execution. This token is optional.

3.3.33 pandora_user <user>

This parameter is optional and allows the agent to be executed with the specified system user. This user has to have permissions to execute the agent and all associated resources.

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

3.3.34 (>= 5.X) custom_id

Custom ID of the agent for external applications.

3.3.35 (>= 5.X) url_address

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

3.3.36 (>= 5.X) custom_fieldX_name

Name of an agent custom field which already exists on the system. If doesn't exist, it will be ignored.

Example:

custom_field1_name Model

3.3.37 (>= 5.X) custom_fieldX_value

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

Example:

custom_field1_value C1700

3.3.38 (> 5.1 Unix agent only) macro<macro> <value>

It defines a local execution macro which can be used in the module definition. These kind of macros are used mostly in the metaconsole system, and in the local module component system to "abstract" the difficulty of use a local module, to not have to edit the source module definition. With these, a new field will appear in the GUI. The local execution macros have similar names to the local plugin macros: _field1_, _field2_....

Example:

module_begin
module_name FreeDisk_opt
module_type generic_data
module_exec df -kh _field1_ | tail -1 |  awk '{ print $5}' | tr -d "%"
module_macro_field1_ /opt
module_end

3.3.39 (>= 6.0SP5) group_password <password>

Password for the agent group. Leave commented if the group is not password protected.

3.3.40 (>= 7.0) ehorus_conf <path>

Absolute path to a valid eHorus agent configuration file. The agent will create a custom field named eHorusID that contains the eHorus agent's identifying key.

Sample:

ehorus_conf /etc/ehorus/ehorus_agent.conf (linux)
ehorus_conf /usr/local/ehorus_agent/ehorus_agent.conf (mac)
ehorus_conf "c:\program files\ehorus_agent\ehorus_agent.conf" (windows)

3.3.41 (>= 7.0OUM13) transfer_mode_user <usuario>

Usuario de los ficheros copiados en el modo de transferencia local. En las carpetas de la consola este usuario debe tener permisos de lectura y escritura para que funcione correctamente la configuración remota. Por defecto es apache.

3.4 Secondary Server

A special kind of general configuration parameter is the definition of a secondary server. This allows the definition of a server to send data to, in a complementary way to the standard definition of a server. The secondary server mode works in two different ways:

• on_error: Send data to the secondary server only in cases it could not send them to the primary one.
• always: Always send data to the secondary server, no matter if it's able to contact the main server or not.

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

3.5 UDP Server

The Pandora FMS Agent (both, Unix and Windows) allows the agent to be configured for listening to remote commands. This server listens on a user specified UDP port and allows orders to be received from a remote system - ideally from Pandora FMS through the execution of alerts on the server.

There are several options to configure the UDP remote server. The default file is pandora_agent.conf

• udp_server: To activate the UDP server, set it on '1'. This is deactivated by default.
• udp_server_port: Port where it listens.
• udp_server_auth_address: Authorized IP address to send orders. Several Addresses can be set separated by commas. If it is configured with 0.0.0.0, UDP Server will accept orders from all addresses. Nevertheless, for security reasons, please restrict the access to this agent from known IPs.
• process_<name>_start <command>: Command which is going to start a user-defined process.
• process_<name>_stop <command>: Command which is going to stop the process.
• service_<name> 1: Allows the service <name> to be started or stopped remotely from the 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 accepts the following commands:

* <START|STOP> SERVICE <name of the service>: Starting or stopping a service.
* <START|STOP> PROCESS <name of the process>: Starting or stopping a process.
* REFRESH AGENT <name of the agent>: Forces one execution of the agent and refreshes data.

In 5.0 version, Unix agent only implements REFRESH AGENT command.

For example:

STOP SERVICE messenger
START PROCESS firefox
REFRESH AGENT 007

There is a script on the server at /util/udp_client.plwhich is 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>

To e.g. restart an agent:

./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT"

For more information, please go to the Alert Configuration section.

3.6 Modules definition

Each piece of information which is collected has to be perfectly defined in each module, using the most precise syntax. You can implement as many values as necessary in order to be collected, adding, at the end of the general parameters as many modules as the number of values to compile. Each module is composed of several directives. The list which appears below is a descriptive list of all available modules and signals for UNIX agents (almost all of them can also apply to the Windows 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 sub-options, but all modules have a structure similar to this. The parameters module_interval and module_description are optional and the rest of them completely compulsory. First, we're going to see the common elements.

3.6.1 Common elements of all modules

Module fields (except module data, description and extended info) are only stored on module creation and will never be updated if the module is already created. This behavior is identical to the agent's enabled learning mode.

3.6.1.1 module_begin

Defines the beginning of the module (compulsory).

3.6.1.2 module_name <name>

Name of the module. This is the module ID. Please pick 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 CANNOT be duplicated ' with a similar name in the same agent. This name could be duplicated with other modules in other agents. Just like in other chapters, Pandora FMS is case-sensitive.

3.6.1.3 module_type

The data type that the module is going to use. There are several data types for agents:

• Numerical (generic_data). Simple numerical data, in floating points or wholes. If the values are in the floating point type, they are going to be cut to their whole value.

• Incremental (generic_data_inc). Numeric data equal to the difference between the current value and the previous one divided by the elapsed time in seconds. When this difference is negative, the value is reset.

• Absolute incremental (generic_data_inc_abs). Numeric data equal to the difference between the current value and the previous one, with no division made, so the value is the total difference or increment, and not the increment per second. When this difference is negative, the value is reset, this means that at the time when the difference is again a positive value, the base value used to make this calculation is the last one from which the incremental value is positive.

• 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 a '0' to a 'false' state and any value higher than '1' to a 'true' state.

• Asynchronous Alphanumeric (async_string). Collects alphanumeric text strings which could enter any moment without a fixed periodicity. The rest of the parameters (generic) work synchronously, which means they expect the data entry every XX time, and if they don't arrive then it's said they are in an unknown state (unknown). The asynchronous modules are unable to adopt this state.

• Asynchronous Monitor (async_proc). Similar to 'generic_proc' but asynchronous (compulsory).

• Asynchronous Numerical (async_data). Similar to 'generic_data' but asynchronous (compulsory).

3.6.1.4 module_min <value>

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

3.6.1.5 module_max <value>

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

3.6.1.6 module_min_warning <value>

This is the minimum value which will make the module state go to the 'warning' status. This guideline is not compulsory. If the module doesn't exist in the dashboard, then it's going to get created automatically when the learning mode is in use.

3.6.1.7 module_max_warning <value>

This is the maximum value which will make the module go to 'warning' status. This guideline is not compulsory. It uses a <= (less than) operator.

3.6.1.8 module_min_critical <value>

This is the minimum value which will make the module state go to 'critical' status. This guideline is not compulsory. This uses a > operator, not a >= operator.

3.6.1.9 module_max_critical <value>

This is the maximum value which will make the module state go to 'critical' status. This guideline is not compulsory. This uses a <= operator.

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, it's going to get created automatically when the learning mode is in use.

3.6.1.11 module_min_ff_event <value>

This is the interval between new status changes which are filtered to avoid continuous changes of module state. This guideline is not compulsory. If the module doesn't exist in the dashboard, it's going to be created automatically when the learning mode is in use.

3.6.1.12 (>= 6.0 SP4) module_each_ff <value>

If enabled (1), per status flip flop thresholds are used instead of module_min_ff_event (module_min_ff_event_normal, module_min_ff_event_warning and module_min_ff_event_critical). Set to 0 to disable.

3.6.1.13 (>= 6.0 SP4) module_min_ff_event_normal <value>

Per status flip flop thresholds. See module_min_ff_event and module_each_ff.

3.6.1.14 (>= 6.0 SP4) module_min_ff_event_warning <value>

Per status flip flop thresholds. See module_min_ff_event and module_each_ff.

3.6.1.15 (>= 6.0 SP4) module_min_ff_event_critical <value>

Per status flip flop thresholds. See module_min_ff_event and module_each_ff.

3.6.1.16 (>= 6.0 SP4) module_ff_timeout <seconds>

Reset the flip flop threshold counter after the given number of seconds. This means module_min_ff_event status changes must be triggered within module_ff_timeout seconds before the status is actually changed.

3.6.1.17 module_description <text>

This guideline will be employed to add a comment to the module. This guideline is not compulsory and it doesn't overwrite the value defined by the agent. If the module doesn't exist in the dashboard, it's going to get created automatically when the learning mode is in use.

3.6.1.18 module_interval <factor>

Since Pandora 1.2 introduced this new type, it's possible for each module to fix its own interval. This interval is calculated as a multiplier for the agent interval. If the agent has e.g. an interval 300 (5 minutes) and you want a module which is going to get processed every 15 minutes only, you should add this line: module_interval 3. This module will be processed every 300sec x 3 = 900sec (15 minutes).

3.6.1.19 module_timeout <secs>

(Windows only)

In the 3.1 version, Pandora FMS supports specifying the total of seconds in each module independently. The agent is going to wait for the execution of the module, so if it takes more than XX seconds, it's going to abort the execution of the module (to avoid becoming 'dead' in the implementation of a module). In version 3.1, it's supported on Windows only - but in future versions, it's also going to get implemented into the UNIX agents.

3.6.1.20 module_postprocess <factor>

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

3.6.1.21 module_save <variable name>

From version 3.2, it's possible to save the modules return value in an environment mode variable, so it could be used in other modules later. It's important to consider the values are updated after the modules are executed in the same order in which they were 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

In Windows agents the module would have to be formed with %var% instead of $var. Following the example

module_begin
module_name echo_2
module_type generic_data
module_exec echo %ECHO_1%
module_end

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

From version 3.2, it's possible to schedule modules in the order they'll be executed on a specific date. To do this, you're required 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 a divider.

In order for one module to be executed e.g. 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 it to 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

3.6.1.23 module_condition <operation> <command>

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

• > [value]: Executes the command if the module value is higher than the given one.

• < [valor]: Executes the command if the module value is lower than the given one.

• = [valor]: Executes the command if the module value is equal to the given one.

• != [valor]: Executes the command if the module value is different to the given one.

• =~ [regular expression]: Executes the command if the module value coincides with the given regular expression.

• (valor, valor): Executes the command if 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, it's recommended to use cmd.exe /c to execute the command to ensure it's 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

3.6.1.24 module_precondition <operation> <command>

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

• > [value]: Executes the command if the module value is higher than the given one.

• < [value]: Executes the command if the module value is lower than the given one.

• = [value]: Executes the command if the module value is equal to the given one.

• != [value]: Executes the command if the module value is different to the given one.

• =~ [regular expression]: Executes the command if the module value coincides with the given regular expression.

• (value, value): Executes the command if the module value is ranged between the given values.

An example of a module using preconditions 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, it's also possible to use several preconditions. The module is only going to be executed if all preconditions are met:

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, it's recommended to use cmd.exe /c to execute the command to ensure it's proper execution. 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

3.6.1.25 (>= 5.x) module_unit <value>

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

Example:

module_unit %

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

This is the name of the module group. If the group doesn't exist, the module will be created without getting assigned.

Example:

module_group Networking

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

This is a custom identifier for the module.

Example:

module_custom_id host101

3.6.1.28 (>= 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.*

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

This is a regular expression to define the 'critical' status in the string type modules.

Example:

module_str_critical .*CRITICAL.*

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

These are the instructions to the operator if the module changes to 'warning' status.

Example:

module_warning_instructions Increase incident priority

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

These are the instructions to the operator if the modules changes to 'critical' status.

Example:

module_critical_instructions Call to sys department

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

These are the instructions to the operator if the module changes to 'unknown' status.

Example:

module_unknown_instructions Open incident

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

These are the tags which will be assigned to the module separated by commas. It will only be assigned to tags which exist in the system.

Example:

module_tags tag1,tag2,tag3

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

This is a flag (0/1) which will inverse the 'warning' threshold of the defined value when activated.

Furthermore, if you use a negative value for the interval, e.g. the 'warning' status for values under '-50', you need set the 'min_warning' to '-50' and set this parameter.

Example:

module_critical_inverse 0

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

This is a flag (0/1) which will inverse the 'critical' threshold of the defined value when activated.

Furthermore, if you use a negative value for the interval, e.g. the critical state for values under '-75', you're required to set the 'min_critical' to '-75' and set this parameter.

Example:

module_critical_inverse 1

3.6.1.36 (>= 5.x) module_native_encoding <value>

(Win32 only)

This configuration token only affects executed modules by command line, that is, there is a module_exec in the module configuration.

Windows manages three encodings for its processes: the command line encoding (OEM), the system encoding (ANSI) and UTF-16. Both encodings are agree on basic characters, but they are different on less common characters, like written accent. With this token, the Pandora's agent transforms the output to the encoding specified in the configuration file (pandora_agent.conf).

module_native_encoding has four acceptable values:

• module_native_encoding OEM: to command line encoding
• module_native_encoding ANSI: to system encoding
• module_native_encoding UTFLE: to UTF-16 little-endian
• module_native_encoding UTFBE: to UTF-16 big-endian

If module_native_encoding does not appear, no re-encoding will be done.

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

This is a flag (0/1) which will turn the module into quiet mode when activated. It won't generate events or alerts anymore, and won't store historic data, so the reports such as SLA won't be affected.

Example:

module_quiet 1

3.6.1.38 (>= 5.x) module_ff_interval <value>

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

Example:

module_ff_interval 2

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

This is a macro generated by the console in conjunction with the components macro system. Setting this parameter from the configuration file is futile, because it's intended for modules created with local components only.

Example:

module_macro_field1_ 8080

3.6.1.40 (>= 5.1 SP4) module_alert_template <template_name>

This macro assigns to the module the alert template that corresponds to the name introduced as parameter(see Alert templates)

Example:

<module>
<name><![CDATA[CPU usage]]></name>
<type>generic_data</type>
<module_interval>1</module_interval>
<min_critical>91</min_critical>
<max_critical>100</max_critical>
<min_warning>70</min_warning>
<max_warning>90</max_warning>
<alert_template><![CDATA[Critical condition]]></alert_template>
<![CDATA[92]]>
</module>

3.6.1.41 module_end

Defines the end of the module (compulsory).

3.6.2 Specific guidelines to obtain information

Furthermore, there are the specific guidelines that could be specified for each module in order to obtain information. Only one kind of them can be used in each module.

3.6.2.1 module_exec <command>

This is the general way to gather information by executing a command. Both for the UNIX and for the Windows agent. There is only one guideline to obtain data the generic way, executing only one command (it's able to use pipes to re-address the execution to another command). This guideline executes a command and keeps the return value. This method is also available under the agents for Windows; it's the general purpose method for both agents.

If execution returns a return code different from '0', it will be interpreted as "execution error" and the information will be discarded.

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

top -n 1 

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

top -n 1 | grep ""

There are the following, additional guidelines for the agents to obtain data:

3.6.2.2 module_service <service>

Checks if a specific service is being executed on 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 one 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 can 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 (case sensitivity).

UNIX

Under Unix, it works like under Windows, but under UNIX, 'service' and 'process' is considered the same concept. For example, to see if the process named bash is running, the module definition would be:

module_begin
module_name Service_bash
module_type generic_proc
module_service /bin/bash
module_description Process bash running
module_end

'service watchdog' and 'service asynchronous detection' aren't possible under UNIX agents.

Asynchronous Way

Pandora FMS usually executes a test battery (each of it defined by a module) every X seconds (300 seg. = 5 min. by default). If a service is down just after an execution of Pandora, it's going to take additional 300 seconds to recognize the service went down. The difference on asynchronous mode is that modules immediatly notify Pandora FMS about the fail or shutdown of this service. This is called asynchronous operation mode. It would be sufficient to add the following command to the guideline to use it:

module_async yes

This feature is not supported on broker agents.

Watchdog of services

There is a watchdog mode for the services, so the agent is able to restart them if they stop. In this case, the restarted service doesn't require any parameter, because Windows already knows how to do it. In such cases, the configuration is a lot easier:

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

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 «" " », please consider that the name of the process should have the .exe extension. The module is going to return the number of processes executed with this name. Same as in the other cases, it's important to know that the name of the process has to be exactly the same as the one shown by the Windows Task Manager, including blanks, capital letters / small letters; e.g. cmd.exe is not the same as CMD.exe (case sensitivity).

This is an example of the monitoring of the process 'cmd.exe':

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

UNIX

Under UNIX, this module works like '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. The Windows agent supports asynchronous checking for the module_proc. module now. In this case, the agent immediately reports it if the process changes its state without waiting for the agent to execute the verification as it's configured in the agent interval again. In this way, you're able to get informed about the failure of critical processes almost in the moment they happen. This is an example of asynchronous monitoring of the processes:

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

The difference is located in the configuration token 'module_async yes'. This feature is not supported on broker agents.

Processes Watchdog

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

Executing a process would require some parameters, so here are some additional configuration options for these kinds of modules. It is important to keep in mind that the watchdog mode only works if the module type is set to asynchronous. This is an example of configuration of 'module_proc' with 'watchdog' enabled:

module_begin
module_name Notepad
module_type generic_proc
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 additional parameters for 'module_proc' with watchdog enabled:

• module_retries: Number of consecutive attempts for the module will try to start the process before deactivating the watchdog. If the limit is reached, the watchdog device for this module will be deactivated. It's never going to try and start the process, even if it's recovered by the user (at least until the agent gets rebooted). There is no limit for the number of retries for the watchdog by default.

• module_startdelay: Number of milliseconds the module is going to wait before starting the process for the first time. If the process takes lot of time at starting, it would be a good idea to order the agent to wait by using this parameter until it starts checking for if the process has been started or not. In this example, it has been set to wait for 3 seconds.

• module_retrydelay: Similar to the previous one but for subsequent falls / reattempts, after having detected a fall. When Pandora detects a fall, it relaunches the process, waits for the preset number of milliseconds and checks if the process is already up again.

It's important to keep in mind that Pandora FMS is executed as a service. If you want to utilize the watchdog functionality to execute processes which allow interaction with the desktop, you should check the box 'Interactive access with desktop' under the Pandora FMS service functionalities as shown in this snapshot:

It's also necessary to understand that Pandora FMS is executed under the count of "SYSTEM" if started as a service. The executed process is going to run with the user and environment of the one who started it, so if it wants to e.g. execute a specific process which requires the environment and rights of a specific user, one should include the previous processes for starting the environment (environment variables, etc.) and execute this script as a watchdog action in a script (.bat or similar).

3.6.2.4 module_cpuproc <process>

(UNIX only)

Returns 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

3.6.2.5 module_memproc <process>

(Unix only)

Returns 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

3.6.2.6 module_freedisk <unit_letter:>|<volume>

This module works under UNIX and Windows. It checks for the free space in the disk unit (don't forget «":"» after the unit_letter) or the UNIX volume e.g. '/var'.

3.6.2.7 module_freepercentdisk <unit_letter:>|<volume>

This module returns the free disk percentage under 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

3.6.2.8 module_occupiedpercentdisk <unit_letter:>|<volume>

(Unix only)

This module returns the occupied disk percentage in a UNIX volume e.g. '/var'.

module_begin
module_name disk_var
module_type generic_data
module_occupiedpercentdisk /var
module_end

3.6.2.9 module_cpuusage <cpu id>

This works under UNIX and Windows. It returns the CPU usage in a CPU number. If there is only one CPU, please leave it blank or use 'all'. It's also possible to obtain the average use of all CPU in multiprocessor systems in this way:

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

To check the 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

3.6.2.10 module_freememory

Supported under Windows and UNIX. It returns the free memory of the whole system:

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

3.6.2.11 module_freepercentmemory

Supported under UNIX and Windows. This module returns the free memory percentage on one system:

module_begin
module_name freepercentmemory
module_type generic_data
module_freepercentmemory
module_end

3.6.2.12 module_tcpcheck

(Windows only)

This module tries to connect with an IP and a specified port. It returns '1' if successful and '0' if not. It's also recommended to specify a timeout:

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

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 depend on the module type:

• generic_data_string, async_string: Returns all the lines which fit the regular expression.
• generic_data: Returns the number of lines which fit with the regular expression.
• generic_proc: Returns '1' if there is a coincidence and '0' if not.
• module_noseekeof: With this configuration token active, with a '0' default value in each module execution and independently from any modification of the target file, the module will restart its check process without searching for the file's EOF flag. It will always extract from the XML output all lines that correspond to our search patterns.

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 regular expressions in general, please visit [2].

3.6.2.14 module_wmiquery

(Windows only)

The WMI modules allow to locally execute any WMI query without the use of an external tool. It's configured through two parameters:

• module_wmiquery: Used WQL query. As a result, several lines could be obtained which will be placed as several data.

• module_wmicolumn: Name of the column which 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 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

3.6.2.15 module_perfcounter

(Win32 only)

Obtains data from the performance counter (http://msdn.microsoft.com/en-us/library/aa373083(v=vs.85).aspx Performance Counters (Documentación en ingles Performance Counters Documentation) 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 yet, you have to install the Windows performance analysis tool (which is usually 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 which has hundreds of parameters that could be used for monitoring. Each manufacturer also adds their own monitors, so this is a powerful, versatile and easy to use tool to monitor the system parameters and also the devices which run on it.

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

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

You can see the Windows performance monitor on this snapshot:

On this snapshot you can see how the interface shows things if we want to add a new monitoring element.

We can view several parameters of the Procesador (in Spanish in the original version) which has different sub elements, of which we have selected % of processor time and in several sub elements here. We're interested in total _Total in this case.

Surfing with the SO tool in this way, 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

Most of the returned data that are counters, so you should use 'generic_data_inc' as data type. It's also able to return 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.

3.6.2.16 module_inventory

It's implemented as an agent plugin under Linux / Unix

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 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 probably uses to monitor services.

Additional Module Parameters:

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

This is an example to use this module:

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

3.6.2.17 module_logevent

(Windows only)

This new module allows information to be obtained from the Windows event log file. It returns the elements which fit to a given pattern, also allowing to filter by source and event type. The module implemented in version 2.0 has been improved, using the Win32 native API now to have access to the events from the file, instead of using the WMI subsystem (much slower). This method is quicker and works on systems with many elements. The new implementation also allows much more field filtering compared to 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 repeating what has already been shown, we only consider those events which occurred since the last time the agent was executed, as with other modules (e.g. 'regexp').

'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). This is an optional field.
• module_pattern: Pattern to search (substring). It's an optional field.
• module_eventcode: It's a numeric ID of the event, e.g. 5112. It's an optional field.
• module_application: Application source of the event. Be careful not to confuse it with 'module_source' which shows the name, source or log file where the events are looked for.

For showing all events of an error type system we e.g. 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 which contain 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 on the snapshot:

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's very important to understand that Pandora FMS is not a system to collect logs. This tool is intended to be used to select critical or important events for monitoring which collects all events without classifying them from a common source (as the 'system' could be one). Doing so will only cause problems in a way that e.g. the database can collapse and the system will work very badly. It's extremely important to understand that the event collection which comes with Pandora should always be used with taking this into account and not to abuse Pandora FMS as a generic event collector.

3.6.2.18 module_plugin

A parameter to define the data which is obtained at the exit of a plugin agent. It's a special case of a module which builds all its XML on its own. It also doesn't require any other delimiter like 'module_begin', 'module_type', etc. It requires this format:

module_plugin plugin_filename parámetro_1 parámetro_2 parámetro_3

In order to configure additional parameters for the plugin, please use the standard syntax:

module_begin
module_plugin plugin_filename parameter_1 parameter_2 parameter_3
module_interval 2
module_condition (0, 1) script.sh
module_end

Each plugin has its own syntax. We are going to describe the regular expressions plugin which comes with the agent by default.

module_plugin grep_log /var/log/syslog Syslog ssh

In this example, the name of the plugin is 'grep_log'. It's going to search for the regular expression 'ssh' in the file '/var/log/syslog' which will be kept in a module called 'Syslog'.

Another example intended to be solely used on Windows-based systems (and only on versions 3.1 or later):

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

File collection and plugins

When you use file collections, you need to know where the file collection stores the files. File collections use a "handle" or short name which is generated when you first create the collection. It has to have a name similar to "fc_2". Here are 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 know the plugin execution output could return more than one module, because it returns a full XML structure. This is e.g. 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>

3.6.2.19 module_ping <host>

(Only for Windows versions 4.0.1 or newer)

This module pings the preset host and returns '1' if it's up and '0' if not. It's 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

3.6.2.20 module_snmpget

(From version 4.0.1 onwards, Windows only)

This module performs an SNMP get query and returns the requested value. It's 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

3.7 Examples

Example of a Windows module, checking if 'EventLog' works. Example:

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

An example for 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

3.8 Specific Configuration by Technologies

With Pandora FMS it's possible to monitor any system. This could either be done with an installed Software agent on the system, which collects data straight from the system to be monitored, or by using a 'Satellite Agent' which consists of an agent which is executed in a server and monitors some parameters of systems which have adjacents through SNMP or user-defined commands.

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's enough to install a software agent and define the configured modules to collect data from an external system through, e.g. the snmpget tool or ping.

3.8.1 UNIX / Linux Agents

UNIX has several command line tools that allow data to be received through commands. The Unix agents are based in this premise. There are two kinds of UNIX agents:

• ShellScript: With a defined shellscript for each kind of SO based on bash, ksh or csh. In the classical UNIX Systems (Solaris, AIX, HPUX), all functionalities are not implemented yet - but under Linux or MAC they are.

• Perl: There is a unique multi-platform agent based on Perl 5.8 that works alike in all Unix systems. You're required to have a Perl 5.8 system or higher installed for proper functioning.

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

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 installer, the agents main directory or 'home' directory is '/usr/share/pandora_agent/' where the Pandora FMS agent is installed. In the system where this isn't possible for reasons of e.g. a strict system policy, we recommend creating a link to this path from the real installation path, e.g. '/opt/pandora' -> '/usr/share/pandora_agent'.

The other important folders are:

• /var/spool/pandora/data_out: Folder where the collected data from the agents is kept.

• /etc/pandora/pandora_agent.conf: Main agent configuration folder. The definition of where the data is collected is defined by the used command.

• /usr/local/bin/pandora_agent: The current Pandora FMS agent. This file is a shellscript which collects the configuration data in the 'pandora_agent.conf' files and sends the data packages to the Pandora Server. It usually has a link to '/usr/bin/pandora_agent'.

• /usr/local/bin/tentacle_client: The agent which adds the Tentacle client for being able to send the data files to the server. This is a client written in Perl 5.8. It usually has a link to '/usr/bin/tentacle_client'.

• /etc/init.d/pandora_agent_daemon: Script for starting and stopping. This daemon calls up 'pandora_agent' and gives two options (start / stop). On the AIX systems, the daemon's name is /etc/rc.pandora_agent_daemon.

• /var/log/pandora/pandora_agent.log: Text file where the activity of the Pandora FMS agent is kept if the agent is executed in depuration mode.

• /etc/pandora/plugins: Directory which keeps the agent's plugins. It's a link to /usr/share/pandora_agent/plugins.

3.8.1.2 Initial Execution of a UNIX Agent

When you start the Pandora FMS agent, this should copy the data file to the Pandora FMS server through the dispatch system which is specified in the configuration file of /etc/pandora/pandora_agent.conf. It's recommended to configure the dispatch system (Tentacle, SSH, FTP) before that.

To start the agent, 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 are waiting in the CPU system queue. The IPSO agent has a special parameter (harmless_mode ) for a special management of the CPU process on systems Checkpoint/NOKIA. This is a very special case.

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

To stop the agent, just execute:

/etc/init.d/pandora_agent_daemon stop

3.8.1.3 Advanced Configuration for the UNIX Agent

The real power of Pandora FMS is on the agent's capacity to start processing the user defined scripts. This could be used to collect specific data or to make an operation which returns any desired value, because it's the aim of the agent plugin structure. For more information, please check the Annex on creating Agent Plugins.

3.8.1.4 Examples of Implementation for UNIX Agents

Example #1: Calculate the number of displays on 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 (named) DNS is working or not:

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

3.8.1.5 Altering the way UNIX Agents obtain system information

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

There are some modules which work like "blackboxes". They are performing operations the user doesn't have to know about. These modules are:

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

Modules like e.g. 'module_cpuusage' return a percentage of the current system CPU usage, but the user doesn't need to use a command. On windows and on UNIX systems, Pandora 'already knows' what to do.

Pandora UNIX Agents have predefined commands to do that. The below mentioned commands are executed 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 }\

It could happen that your system is slightly different from the tested system and the command is not valid. You're able to use your own command with a simple 'module_exec' or redefine internal pandora commands to do that. You need to edit some lines of Pandora FMS Unix Agent code for that, but don't worry - it's Perl code and it's very basic editing.

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

# 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 gets information from the system to get the total memory. AIX is not defined because we don't have the information on how to get this information in an AIX system yet.

# 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 the predefined values to get the information, just edit the command but be careful with it:

1. Check that lines end with ";"
2. Check that commands are between ' ' symbols.
3. Check that any ' symbol you use ends on the \ symbol, e.g.:

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's written in the code.

3.8.2 Pandora FMS Windows Agents

3.8.2.1 Check Windows agent is working

The exit of the Pandora FMS Windows agent can be checked in the file C:\archivos de programa\pandora_agent\pandora_agent.log. It's a plain text file that contains information about the agent's 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 return an error, because neither the address nor the file to send is specified, but it checks if the Tentacle client tentacle-client is in the system. The second one will force Pandora FMS to connect using SSH internally and copy a file called ssh.test. Remember that you're required to configure SSH properly, to generate the required keys and to import them onto the server if you want to use it.

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's very stable and has been tested on all Windows platforms where it has to operate. Nevertheless, it could happen that the service crashes a few times on some systems. We have tried to give some solutions to those users which require a restarted system or a supplementary control of the agent for it.

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, just execute the following command in the command line:

at

This will give you the scheduled tasks.

Automatic control of the service in case of crashes

Windows provides an additional way of controlled restart of the service if this crashes for any reason. This allows you to tell the Windows service to restart automatically in case of a crash. You have to go to the Windows services dashboard and to the Pandora FMS agent and click on 'Properties' for it. On the 'Recovery' slide, you're required to change the default values into this:

This causes an automatic restart if the service crashes - but only once a day. If it happens to crash more than once a day, it won't get restarted again. The reason for this configuration is avoidance of a possible system overload due to a forced execution that downs too much of the other services, which is caused by a problem within the system. Pandora FMS should never be down. In any case, you can adjust these parameters if a Pandora FMS service crash should be controlled by the system and to make sure that you'll always have the agent running this way.

3.8.2.3 Configuration of Pandora FMS Windows Agent

The whole installation is done through the file pandora_agent.conf. This file is a list of pairs of keys and values which 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 (please 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

3.8.2.4 Extending the agents functionality with VBS code

Starting with the 3.1 version, Windows agents started to have plugins like the Unix agents, but don't forget they also have the possibility of executing the external scripts, based on VBScript as simple modules. Take a look at the VBS code which 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 in a file called "CPUTotal.vbs" which is located at c:\program files\pandora_agent\util.

Now we're going to create the new module type of '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 through VBScript. Microsoft has an excellent online documentation about VBS that you can check in MSDN: [3].

3.8.2.5 Running the Pandora FMS Agent under a different user than SYSTEM

You can setup the Windows agent to run under a different user. You're required to configure the startup service with a different user and provide this user with special privileges to do that. That user is required to be included in the 'Administrators' group.

In the WMI console, all users from the group 'Administrators' have ALL permissions enabled.

This is an example of a user and it's WMI settings for the ROOT environment. Branches will inherit the root permissions by default:

You can look up some Microsoft links related to this issue on : [4] [5]

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 and data) from the console to the agents running the Pandora FMS software agent.

We can provide a way to 'auto-upgrade' the software agents using that mechanism and a very special tool. It works in the following way:

1. Agents receive new binaries e.g. in the file collection's incoming directory:

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

2. The agent utilizes a special module to execute the pandora_update tool. This tool receives a single parameter, the FileCollection handle (or short name). In this scenario, it's fc_1. It checks for a file called 'pandoraagent.exe' (or 'pandora_agent' under UNIX), looks at the size and contents of both files (by using a HASH), the running 'pandora_agent' and the binary provided in the file collection. If they are different, 'pandora_update' stops the agent, replaces the binary and restarts the agent again, using the new binary.

3. Furthermore, 'Pandora_update' writes the update event to a small log to be able to recover the next execution and warns the user about the agent's updating process by means of an 'async_string' module.

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

UNIX Standard 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 the 'pandora_update' command is the installation path of Pandora FMS. This parameter is only required if Pandora FMS is installed in a path different from the 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: If it has the agent in a non "standard" path under UNIX, you're required 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";

Please change the paths to the ones which fit with your system manually.

3.8.4 Process to Auto Upgrade Agents from versions previous to 3.2

The first thing is to get the executables from the Pandora FMS agent and the 'pandora_update' tool ('pandoraAgent.exe' and 'pandora_update.exe' under Windows and 'pandora_agent' and 'pandora_update' under 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 which you want to update. This is a feature which the Pandora FMS 3.2 version provides (File Collection) but just now, you want to migrate to the 3.2 version, because this feature is missing there. It's assumed that you have alternative mechanisms.

2. The agent's configuration and remote management is activated and working. This will be useful. It's recommended to 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 directory '/util' of our Pandora (in Windows).

Supposing that we have Pandora FMS installed in:

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's binary to the last directory which 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 a special tool ('pandora_update') which compares the current executable with the one that already exists in the directory '/collections/xxxx', where 'xxxx' is a parameter that is passed on to the module. This location is the one specified with the file collections. After using the 3.2 version, the distribution of the new *.exe of the agents will be done through file collections and this identifier will be necessary to 'locate' in which file collection our executable is located.

UNIX Platforms

Similar to the Windows platforms, we have to copy the executable of the UNIX agent and the 'pandora_update' feature. If it has a non-standard installation and possesses customized paths, you should have to pay lot of attention to the previous paragraph where it's described which files should be modified.

You have to copy pandora_update into your agent's plugins / folder:

/etc/pandora/plugins/pandora_update

Now create directory 'collection/fc_1' in 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 default path is '/etc/pandora/plugins/pandora_update'.

The module for the UNIX case will be the following:

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: It's recommended to check if both 'pandora_update' and 'pandora_agent' have suitable permissions and owners, executing permissions and the same user which owns the 'pandora_agent' executable.

3.9 Pandora FMS Drone Agents

3.9.1 What is a Drone Agent ?

The Pandora FMS Drone Agent is a running mode of Pandora FMS Software Agent. This running mode only works on Windows and Linux machines. It was developed to deal with complicated environments with restricted access to the machines. The Drone Agent has two main features:

• Proxy mode
• Broker mode

Running in this mode, the Drone Agent can report data and utilize all features of the standard Pandora FMS Software Agent.

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

3.9.1.1 Proxy Mode

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

The new Tentacle version supports proxy usage (HTTP/Connect mode), so that agents can contact with the server using an intermediate standard proxy directly. You also can use a new tool called 'Tentacle Proxy Server' 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 the Tentacle Proxy Server here.

You'll get all functionalities of a proxy but managed by Pandora FMS Software Agent with this feature. This mode has two requirements 1. The agent cannot be run by the root. 2. If you want to use the proxy mode with Unix agent then it must be installed with a user without root privileges (the same user will execute the agent in proxy mode later).

All parameters to configure the Tentacle Proxy Server are available trough its agent configuration file:

server_ip

It's the IP address or the name of Pandora FMS server host. Be careful with the enabled Proxy Mode. This parameter cannot take values like 127.0.0.1, locahost, 0.0.0.0 or related.

proxy_mode

Proxy mode status. If the 'proxy_mode' is set to '1', the proxy feature of the drone agent is activated. If the proxy_mode is set to '0', the proxy feature is off. This feature is disabled by default.

proxy_max_connection

Number of max. simultaneous connections of the proxy. 10 connections are allowed by default.

proxy_timeout

Timeout for the proxied server. Default value is '1 second'.

3.9.1.1.1 Usage Examples

I only have one connection to the Pandora FMS Server

This situation is not a problem for the Pandora FMS Drone Agent. To configure the proxy mode, just set 'server_ip' to the Pandora FMS IP and the 'proxy_mode' parameter to '1'. You can configure some parameters like the number of connections and timeout if needed. You'll have the agent and the Tentacle Proxy Server up and running on the machine which can connect with Pandora FMS Server with this configuration.

To configure the other agent, just set the 'server_ip' parameter to the IP address of the Drone Agent with proxy mode enabled. That's all you have to do. The agents are going to use the drone agent to connect to the Pandora FMS Server.

I'm required to setup a double proxied connection

You're able to connect a Drone Agent to another. It's very easy.

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

To configure the second Drone Agent, just set the 'server_ip' to the one of the first Drone Agent and 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.

3.9.1.2 Broker Mode

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

It's important to know that the broker_agent token will be ignored in the configuration of an agent which is set like a broker agent.

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 host and have it under Pandora FMS like they were different independent agents.

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

On the next execution or restart you will have three new files: 'router_1.conf', 'router_2.conf' and 'router_3.conf'. They are an exact copy from origial "pandora_agent.conf" file, except the attribute of 'agent_name' which will be selected from the 'broker_agent' call.

You now have four agents with different configuration files. You can now add different modules in each configuration file, e.g. edit 'router_1.conf' and add:

Sample of remote check

Please add the following line to the remote configuration file 'pandora_agent.conf':

broker_agent server_1

A new file called 'server_1.conf' will be created and we'll edit it for the purpose of adding 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 be interesting when making checks against another remote machine. Even if it has an agent installed Pandora, is unattainable by the server.

This feature is available from version 4.0 onward.

3.10 Agent / Module Autocreation from XML File / Learning Mode

Pandora FMS supports the automatic creation of agents and/or modules if you receive the information coming from an XML (data server). This happens automatically, unless you completely disable this behavior by disabling the server autocreate parameter. The 'creation' only happens the first time agent data arrives on the server. That means you can create the information but you cannot update the agent or module information each time you're getting a new XML - with a few exceptions as you can see below.

This behavior can be avoided in specific agents by disabling the learning mode of the agent. By disabling this feature, the agent will not create new modules when the XML arrives with the new module. The information won't update the agent configuration parameters.

Autodisable mode: From version 6.1 onward agents have this third mode available. In terms of creating agents and modules it behaves exactly the same as an agent in learning mode: when the first XML reaches it, the first agent is created and, on each report, if there are new modules they can also be added automatically. Nevertheless, when all modules from an agent that are in autodisable mode are also marked as unknown, the agent is automatically disabled. In any case, if the agent reports again, it gets enabled again on its own.

3.10.1 Loaded Data from the XML in the Creation of an Agent

Stored Data for an agent is the following:

In 4.x version:

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

In 5.x version

It's the same as in 4.x version, plus the following:

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

In 6.1 version

• Agent mode: (Learning -default-, No-learn, Autodisable).

3.10.2 Data modified in the Agent when receiving XML (Learning Mode enabled)

• Agent's IP address
• Agent's parent (if defined in server setup, for v4.x parents it's always updated)
• OS Version.
• Agent's version.
• Timezone.
• Custom fields.

The GIS data are always updated. It doesn't matter at all if the learning mode is enabled or not.

By enabling the learning mode the new modules which get received through the XML file are going to be created under Pandora FMS.

3.10.3 Data added to the Module on Creation Time

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

In 4.x version

• Name.
• Type.
• Description.
• Max Min value filter.
• Post process.
• 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.
• Alert template (from SP4)

In 6.x version

• Crontab

3.10.4 Loaded Data when Module already exists

If the data server processes an XML containing information for a pre-existent module, part of its information will be overwritten / updated. The description and extended information (see next epigraph) are updated.

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

3.11 Extended Module Information

This epigraph is for advanced and development environments. You're able to send custom XML data (using your own application or altering the Pandora agent's source code). This XML file has two 'custom' tags named '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>

The module is going to be shown like on the picture below.

These fields don't store history values. They're only going to store the last received value from the XML data.

Go back to Pandora FMS documentation index