Pandora:Documentation en:Configuration Agents

Go back to Pandora FMS documentation index

We are working on the translation of the Pandora FMS documentation. Sorry for any inconvenience.

1 Pandora FMS Software Agents

1.1 What is a software Agent?

As its name indicates, they are small pieces of software that are installed in the operating systems and remain running in them to extract monitoring information and send it to the Pandora FMS server regularly.

They use the commands and tools of the operating system in which they are installed to obtain the information. They conform the data in a file in XML format and send them to the Pandora FMS data server, which processes and stores them in the database.

Each of the individual checks is called Module.

1.2 Introduction to the Agent Configuration

The operation of the software agent is determined by its configuration file, called pandora_agent.conf, located in the installation directory on Windows systems, and /etc on Linux systems.

The configuration file contains all the operating parameters and modules of that agent.

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

The agent configuration file encoding is UTF-8 on both Linux and Windows systems. If you make manual edits of this file, verify that the encoding is correct before overwriting it. If the encoding is not UTF-8 and you use symbols (such as stress marks or extended symbols), the agent will misinterpret these symbols, not being able to guarantee a correct interpretation of its configuration.

1.3.1 server_ip

The IP address or the name of the Pandora FMS Server Host where all data will be stored.

1.3.2 server_path

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

1.3.3 temporal

The path where the agent stores the data files before they are sent to the server and deleted locally.

1.3.4 description

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

1.3.5 group

If there is a group with the name specified in this parameter, the agent will be created within this group unless the server forces the creation of all agents in a given group.

1.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 won't continue generating data packets. This prevents the disk from being full if for any reason connection to the server is lost for an extended period of time.

1.3.7 logfile

The path to the Pandora FMS agent events record file.

1.3.8 interval

It is the agent sampling time, in seconds. Each time this interval is completed, the agent will collect information and send it to the Pandora FMS server.

1.3.9 disable_logfile

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

1.3.10 debug

If it is active (1), the agent data files are stored and renamed in the temporary directory and are not deleted after being sent to the server, being able to open XML files and analyze their content.

1.3.11 agent_name

It allows setting a custom name. If it is not enabled, the agent name will be the hostname of the machine.

1.3.12 (>=5.1SP2) agent_name_cmd

Defines the agent name using an external command. If agent_name_cmd is set, agent_name is ignored. The command must return the agent name by STDOUT. If you return more than one line, only the first line will be used.

1.3.13 (>=7.0) agent_alias_cmd

Defines the agent alias using an external command. If agent_alias_cmd is defined, agent_alias is ignored. The command must return the agent name by STDOUT. If you return more than one line, only the first line will be used.

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

1.3.15 encoding

Installs the kind of codification of the local system, such as ISO-8859-15 or UTF-8.

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

1.3.17 transfer_mode

This parameter specifies the transfer mode we have to install in order send the agent data to the server. Tentacle by default.

1.3.18 (>= 6.0) transfer_timeout

It is the timeout for file transfer, if the indicated number of seconds is exceeded without completing the transfer, it will be cancelled.

1.3.19 server_pwd

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

1.3.20 server_ssl

Specific for the Tentacle transfer mode. Allows to authorize ('1') or deny ('0) the SSL network encryption.

1.3.21 server_opts

Specific for the Tentacle transfer mode. Allows to give additional parameters to the Tentacle client for advanced configurations with security options.

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. In order to be able to use the output through a proxy, we use the following advanced option (example):

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

1.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 seconds) after manual execution. It's deactivated by default. This option is only valid on Linux/Unix agents.

1.3.23 pandora_nice

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

1.3.24 autotime

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

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

1.3.26 remote_config

(Pandora FMS Enterprise only)

Enables (1) or disables (0) remote agent configuration. Operation is only allowed with Tentacle transfer mode.

1.3.27 xml_buffer

If enabled (1), the agent will save in its temporary directory the XML files that it could not send to the server in case of a connectivity problem. They will be sent when communications are restored.

1.3.28 timezone_offset

The agent can now install its timezone offset with the server. This allows the server to make a scrolling of the time collected by the agent, so that it matches the local time of 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).

1.3.29 parent_agent_name

Indicates the parent of the software agent. It must be the name of an existing agent in Pandora FMS.

1.3.30 agent_threads <threads>

Number of threads the agent is going to launch to execute modules simultaneously.By default, the modules are executed one after the other without launching any additional thread. This is only available in Linux/Unix agents.

# Number of threads to execute modules in parallel
agent_threads 4

1.3.31 include <filename>

This file can contain additional modules and collections alongside the ones found in the main configuration file. This token is optional. El fichero lo podrán subir aquellos usuarios que tengan permisos de, al menos, escritura sobre agentes(AW).

1.3.32 broker_agent <name>

Enables broker agent functionality. To activate it, you only need to uncomment the parameter and indicate the name that will be assigned to the broker agent:

broker_agent Name_broker

1.3.33 pandora_user <user>

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

1.3.34 (>= 5.X) custom_id

Custom ID of the agent for external applications.

1.3.35 (>= 5.X) url_address

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

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

1.3.37 (>= 5.X) custom_fieldX_value

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

Example:

custom_field1_value C1700

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

Defines a local execution macro that can be used in the definition of a module. These macros are used in the meta console system and local module components system to "abstract" the difficulty of using a module by directly editing the code, presenting a local interface that allows to "fill in" values to a less advanced user. These values are used below, using a macros system, relatively similar to the macros system of the local plugins.

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

1.3.39 (>= 6.0SP5) group_password <password>

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

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

1.3.41 (>= 7.0OUM713) transfer_mode_user <user>

User of files copied in the local transfer mode. In console folders, this user must have reading and writing permissions for the remote configuration to work properly. By default it is apache.

1.3.42 (>= 7.0OUM721) secondary_groups <secondary groups>

Name of the secondary groups assigned to the agent. Several secondary groups separated by commas can be specified. If any of the groups does not exist on the server to which the information is sent, that group will not be assigned, but the creation of the agent will not be affected.

1.3.43 (>= 7.0OUM728) standby <1|0>

If an agent has standby 1 mode, the agent will not perform any check or send or generate any XML. This configuration directive makes sense in enterprise installations where there is remote configuration. Thanks to it, it is possible to silence an agent at will just by disabling it.

The debug mode overwrites this functionality and the agent is executed normally.

1.4 Secondary Server

We can define a secondary server to which the data will be sent in two possible situations depending on the configuration:

• 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

1.5 UDP Server

The Pandora FMS Agent can be configured to listen to remote commands. This server listens to a UDP port spcified by the user and allows orders to be received from a remote system - usually from Pandora FMS' console 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.
• process_<name>_start <command>: Command which is going to start a process defined by the user.
• 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.pl which is used by the Pandora FMS Server as a command of an alert to start processes or services. It has this syntax:

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

E.g. to restart an agent:

./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT"

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

1.6 Modules definition

The local execution modules are defined in the configuration file pandora_agent. conf. Below we explain all the parameters that can be accepted.

The general syntax is the following:

module_begin
module_name <Module Name>
module_type generic_data
module_exec <local command to execute>
module_end 

There are different kinds of modules,; in this example we have only used the common and mandatory lines for most of them.

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

1.6.1.1 module_begin

Defines the beginning of the module (compulsory).

1.6.1.2 module_name <name>

Name of the module (compulsory). This name CANNOT be duplicated.

1.6.1.3 module_type

Type of data the module will return. It is compulsory to choose one of these. The available types are:

• Numerical (generic_data). Simple numerical data, in floating points or wholes.

• 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, which means that when the difference becomes positive again, the previous value will be taken as long as the increment returns to a positive value.

• 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). Collects alphanumeric text strings.

• Booleans (generic_proc). For values that can only be correct/affirmative (1) or incorrect/negative (0). Useful to check if a computer is alive, or a process/service is running. A negative value (0) has the critical status preassigned, while any higher value is considered correct.

• Asynchronous Alphanumeric (async_string). For asynchronous text strings. Asynchronous monitoring depends on events or changes that may or may not occur, so these types of modules are never in unknown status.

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

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

1.6.1.4 module_min <value>

Minimum value that the module must return in order to be accepted. Otherwise it will be discarded by the server.

1.6.1.5 module_max <value>

Maximum value that the module must return to be accepted. Otherwise it will be discarded by the server.

1.6.1.6 module_min_warning <value>

This is the minimum value that will make the module go into 'warning' status.

1.6.1.7 module_max_warning <value>

This is the maximum value that will make the module go into 'warning' status.

1.6.1.8 module_min_critical <value>

This is the minimum value that will make the module go into 'critical' status.

1.6.1.9 module_max_critical <value>

This is the maximum value that will make the module go into 'critical' status.

1.6.1.10 module_disabled <value>

Indicates if the module is enabled ('0') or disabled ('1').

1.6.1.11 module_min_ff_event <value>

Flip flop protection value for false positives. The number of status changes indicated in this value will be necessary for the module to visually modify its status in the web console.

1.6.1.12 (>= 6.0 SP4) module_each_ff <value>

If enabled (1), flip flop thresholds per status will be used (module_min_ff_event_normal, module_min_ff_event_warning and module_min_ff_event_critical). Set to 0 to disable.

1.6.1.13 (>= 6.0 SP4) module_min_ff_event_normal <value>

Flip flop protection value for switching to normal status.

1.6.1.14 (>= 6.0 SP4) module_min_ff_event_warning <value>

Flip flop protection value for switching to warning status.

1.6.1.15 (>= 6.0 SP4) module_min_ff_event_critical <value>

Flip flop protection value for switching to critical status.

1.6.1.16 (>= 6.0 SP4) module_ff_timeout <seconds>

Resets the flip flop threshold counter after the given number of seconds. This implies that the number of status changes determined in module_min_ff_event must occur at an interval module_ff_timeout seconds before the state changes in the console's visual level.

1.6.1.17 (>= 734) module_ff_type <value>

This is an advanced option of the Flip Flop to control the status of a module. By means of "keep counters" we will establish some counter values to pass from one status to another depending, instead of the value, on the status of the module with the received value.

Indicates if the keep counters is enabled ('1') or disabled ('0').

1.6.1.18 module_description <text>

Free text with information about the module.

1.6.1.19 module_interval <factor>

This interval is calculated as a multiplier for the agent interval. If the agent has e.g. an interval 300 (5 minutes) but you want a module which is going to get processed every 15 minutes only; so you should add this line: module_interval 3. This module will be processed every 300sec x 3 = 900sec (15 minutes).

In order for the module_interval to work in broker agents, it must have the same interval as the one of the agent from which it comes. Otherwise, its operation may fail.

1.6.1.20 module_timeout <secs>

In seconds, maximum time allowed for the execution of the module. If this time is exceeded before the end of its execution, it will be interrupted.

1.6.1.21 module_postprocess <factor>

Numerical value by which the data returned by the module will be multiplied. It is useful for unit conversions.

1.6.1.22 module_save <variable name>

Stores the value returned by the module in a variable with the name indicated in this parameter. This value can be used later in other modules.

For example:

module_begin
module_name echo_1
module_type generic_data
module_exec echo 41121
module_save ECHO_1
module_end

It will store the value"41121" in the "ECHO_1" variable.

module_begin
module_name echo_2
module_type generic_data
module_exec echo $ECHO_1
module_end

This second module will show the contents of the variable "$ECHO_1", it being "41121".

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

1.6.1.23 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

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_end

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

Multiple conditions can be specified for a single module. In the following case, the script_1.sh will be executed if the value returned by the module is between 1 and 3, and script_2.sh will be executed if the value of the module is greater than 5.5, so in this case, being 2.5 the value returned in the module_exec line , only the first condition script_1.sh will be executed:

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 of possible real cases:

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

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

In the following example, the module monitoring_variable.bat will only be executed if the result of the execution indicated in the precondition is between 2 and 8. In this case, the execution result indicated in the module_precondition line is 5, a value between 2 and 8, so monitoring_variable.bat will be executed correctly:

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

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

Units shown next to the value obtained by the module.

Example:

module_unit %

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

This is the name of the module group.

Example:

module_group Networking

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

This is a custom identifier for the module.

Example:

module_custom_id host101

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

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

Example:

module_str_warning .*NOTICE.*

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

1.6.1.31 (>= 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

1.6.1.32 (>= 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

1.6.1.33 (>= 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

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

These are the tags which will be assigned to the module separated by commas.

Example:

module_tags tag1,tag2,tag3

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

Allows activating (1) the inverse interval for the warning threshold.

Example:

module_warning_inverse 1

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

Allows activating (1) the inverse interval for the critical threshold.

Example:

module_critical_inverse 1

1.6.1.37 (>= 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.

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

If enabled (1) the module will be in silent mode: it will not generate events or trigger alerts, nor will it store data history.

Example:

module_quiet 1

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

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

Example:

module_ff_interval 2

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

Only applicable to local components from the console. It has no utility in the configuration file.

1.6.1.41 (>= 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>
<data><![CDATA[92]]></data>
</module>

1.6.1.42 module_end

Defines the end of the module (compulsory).

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

1.6.2.1 module_exec <command>

General command execution line. The desired run must be specified to obtain the information in a single line.

On Linux, the command will be executed using the default command prompt. Which is the default interpreter will be determined by the symbolic link /bin/sh. Normally the link points to bash, but in systems like Ubuntu this is not the case (in this case it points to dash). Therefore, it can happen that a command is tested in the terminal and then an error occurs when the agent executes it. A solution that will work in most cases will be to force the bash execution of the command as follows:

module_exec bash -c "<command>"

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

For a Windows agent there are more guidelines for obtaining data, which are described below.

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

Asynchronous Mode

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 300 additional seconds to find out 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.

In Windows Home Edition versions, this asynchronous functionality is not supported and, only in those versions, the Pandora agent makes a periodic query to know if the service is running or not. This can be quite resource-intensive so it is recommended to use the synchronous version if a large number of services are being monitored.

Service Watchdog

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

Unix

In Unix, it works the same as in Windows, the only difference is that for Unix, process and service is the same concept, for example to see if the bash process is active in the system, just run:

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

Watchdog mode and asynchronous detection are not possible in the Unix agent.

1.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 do not 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.

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 just like in Windows. 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 status without waiting for the agent's execution interval to be reached again. In this way, you're able to get informed about the failure of critical processes almost instantly. 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 that allows to act immediately if an agent is down, usually raising the process that went down. The Pandora FMS Windows Agent could act as a watchdog when a process is down.

Since executing a process would require some parameters, there are some additional configuration options for these kind 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 that the module will try to raise the process before deactivating the watchdog. If the limit is reached, the watchdog mechanism for this module will be deactivated and will never attempt to launch the process again until the agent is restarted. Unlimited by default.

• module_startdelay: Number of milliseconds the module is going to wait before starting the process for the first time.

• module_retrydelay: Number of milliseconds that the module will wait before trying to launch the process in each retry.

• module_user_session: it vontrols in which session you want the process to be launched. If set to 'no', the process will start in the services session and therefore remain in the background (default setting). Otherwise, if set to 'yes', the process will be launched in the user's session and will be visible from the PC desktop.

For versions prior to Windows Vista, the module_user_session token can be configured in a general way by enabling the checkbox "Interactive access with desktop" in the Pandora FMS service properties, as shown in the following screenshot:

It's also necessary to understand that Pandora FMS is executed under the "SYSTEM" account if started as a service. The executed process will do it under that user and with that environment, so that if you want to execute any particular process that requires to be used with a certain user, you will have to include in a script (.bat or similar) the previous processes to initialize the environment, environment variables, etc, and execute that script as a watchdog action.

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

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

1.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 in Windows) or the UNIX volume e.g. '/var'.

module_begin
module_name freedisk
module_type generic_data
module_freedisk C:
module_end

module_begin
module_name disk_var
module_type generic_data
module_freedisk /var
module_end

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

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

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

1.6.2.10 module_freememory

Supported in 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

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

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

1.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 [1].

1.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 inserted 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

1.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 with hundreds of parameters that can be used for monitoring. In addition, each manufacturer incorporates its own counters.

Performance counters can be observed using the Performance tool:

New performance counters can be added using the system tool. Its configuration has a management structure with elements and sub-elements. In this case Processor, % of processor time and _Total:

The configuration of the module for this particular check would be as follows:

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

1.6.2.16 module_inventory DEPRECATED

Currently this functionality has been replaced by inventory from agent plugins on both Windows and Linux/Unix systems.

(Win32 only. In linux/unix is implemented as agent plugin)

Using predefined WMI queries and log searches, this module gathers information about the different aspects of a machine, about software and 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 they give:

• CPU: Gets information about the system's CPUs (processor name, clock frequency and description).
• CDROM: Gets information about the CD-ROM (name, description and unit 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

1.6.2.17 module_logevent

(Windows only)

Allows obtaining information from the Windows event log based on the indicated patterns, providing the possibility to filter according to the source and event type.

The general format of this module is as follows:

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

To avoid showing ducplicated information, only those events which occurred since the last time the agent was executed will be considered.

'module_logevent' accepts the following parameters (all of them are 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 mistake it by 'module_source' which shows the name, source or log file where the events are looked for.

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

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

To show all events 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

1.6.2.18 module_logchannel

(Windows only, from 7.0OUM715 on)

Type of module that allows you to obtain information about Windows logging channels. Although module_logevent only has access to Windows Logs, this type of module allows you to extract data from other log files that are configured as channels. In this way, it is possible to obtain the logs included in the services and application logs.

The general format of this module is as follows:

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

To avoid displaying repeated information, only those events that have occurred since the start of the agent are taken into account.

module_logchannel accepts the following parameters (all case-sensitive):

• module_source: Event channel. With the command wevtutil. exe enum-logs a list of all the local log channels of the machine is obtained. Required field.
• module_eventtype: Event type (critical, error, warning, info or verbose). Optional field
• module_pattern: Pattern to search (substring). Optional field.
• module_eventcode: Numeric ID of the event, e.g. 5112.Optional field.
• module_application: Application source of the event. Be careful not to mistake it by 'module_source' which shows the name, source or log file where the events are looked for.

For example, we would define the following module to show all the events of the channel Microsoft-Windows-TaskScheduler/Operational, information type, with code 201 and with log text code 0:

module_begin
module_name New logs
module_type async_string
module_logchannel
module_description Successfully completed tasks
module_source Microsoft-Windows-TaskScheduler/Operational
module_eventtype information
module_eventcode 201
module_pattern code 0
module_end

With this module configuration, the Pandora FMS agent would collect the following log:

To get the name of the event channel we will need to right click on it, choose "properties" and copy the parameter "Full name", which is the one needed in module_source.

1.6.2.19 module_plugin

A parameter to define the data which is obtained at the exit of a plugin agent. It's a special case , since it doesn't require any other delimiter like 'module_begin', 'module_type', nor will it need the module type.

It just requires this format:

module_plugin plugin_filename parámetro_1 parámetro_2 parámetro_3

However, it can be used between the usual module labels to add additional options such as conditions or interval:

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

The parameters to be used will be different for each plugin, so it will be necessary to refer to your particular documentation. We will describe the operation of one of the plugins that comes by default with the Agent, the grep_log plugin to search for matches in a file:

module_plugin grep_log /var/log/syslog Syslog ssh

In this example, the name of the plugin is 'grep_log' and 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"

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

Is supports the following configuration parameters:

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

Example:

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

1.6.2.21 module_snmpget

(Windows only)

This module performs an SNMP get query and returns the requested value.

It supports the following configuration parameters:

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

Example:

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

1.7 Automatic agent configuration

1.7.1 Introduction

Starting from Pandora FMS version 725, you can establish a series of rules for your agents to be configured automatically.

The agent auto-configuration process works as follows:

1- Automatic configurations are prepared in your Pandora FMS Console o Pandora FMS Metaconsole.

2- The agents are installed reporting against your Pandora FMS (if you have a single console, point the agent against your Pandora FMS server, if you have a Metaconsole with the automatic provisioning system configured, set the Metaconsole itself as server).

3- Pandora FMS Server will receive a XML (.data) with the agent's data for the first time.

4- The rules for determining the automatic configuration to be applied will be evaluated.

5- The agent will pick up the new configuration and report in the next cycle with the updated configuration.

1.7.2 Creation of an automatic agent configuration

You can access the form that manages the automatic settings through:

Console Management > Manage automatic agent configuration

Metaconsole Advanced > Agent Management > Automatic Agent Configuration

Once you access the administration page you can create new automatic configurations by pressing the "Create automatic configuration" button.

You will need to choose a name and description for its automatic configuration.

Once the new automatic configuration is created, you can display the configuration forms by clicking on the section you need:

1.7.2.1 Rules

To define the agents to which the automatic configuration will be applied, you can add rules to identify them.

Display the rules section within your automatic configuration, and select "Add new rule".

You can choose a series of options in the rules selector to identify the agents to be configured.

Server name

Server name match

Group name

Group name match

OS

OS name match (uses regular expressions)

Custom field

Match by key/value based on a custom field reported by the agent. Specify the name of the custom field and the value it should have.

IP range

Match by IP range (network), use IP/mask notation, for example

192.168.1.0/24

Script output (> 0)

Result of the execution of a script, the rule will be evaluated as valid as long as the result in the standard output is greater than 0.

The rule script call supports the following macros in the field 'arguments':

_agent_ 

will be replaced by the agent's name

_agentalias_ 

will be replaced by the agent's alias;

_address_ 

will be replaced by the principal IP addresss, reported by the agent

_agentgroup_ 

will be replaced by the group's nname, reported by the agent

_agentos_ 

will be replaced by the agent's OS

You can choose between AND and OR operators to modify the logic of the rules.

Note: If you do not add any rules, the automatic configuration will not apply.

If you need a single configuration for all agents, you can use the following regular expression to match any alias

.*

1.7.2.2 Settings

From this section we will be able to configure:

Agent's group

We can keep it unchanged or force it to be a specific one.

Secondary groups

The groups selected here will be added as secondary groups to the agent.

Policies

We can select policies to be applied automatically when the agent reaches the server.

Configuration block

Adds the extra raw configuration to the agent configuration file.

Note: If you try to access automatic configuration management from a node belonging to a Metaconsole, with centralized management active, the view will be read-only:

1.7.2.3 Extra Actions

From this section you can associate other actions to the autoconfiguration, for example:

1. Launch a personalized event
2. Execute an alert action
3. Execute a script

The system supports the following macros:

_agent_ 

will be replaced by the agent's name

_agentalias_ 

will be replaced by the agent's alias;

_address_ 

will be replaced by the principal IP addresss, reported by the agent

_agentgroup_ 

will be replaced by the group's nname, reported by the agent

_agentos_ 

will be replaced by the agent's OS

_agentid_ 

will be replaced by the agent's ID

1.8 UNIX / Linux Agents

1.8.1 Pandora FMS UNIX Agents Configuration

The fundamental routes and directories to consider are:

• '/usr/share/pandora_agent/': where the Pandora FMS agent is installed. In systems where this isn't possible for reasons like 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'.

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

• /etc/pandora/collections: Directory containing the collections of the agent. It is linked to the directory /usr/share/pandora_agent/collections.

1.8.2 Initial Execution of a UNIX Agent

To start the agent, simply execute:

/etc/init.d/pandora_agent_daemon start

To stop the agent, just execute:

/etc/init.d/pandora_agent_daemon stop

This boot script will be able to start or stop the Pandora FMS agent, which will be running in the system as a daemon by default after started.

1.8.3 Altering the way UNIX Agents obtain system information

As we saw in the configuration section, there are some modules that obtain the information in a predefined way without having to specify a command with module_exec. These modules are:

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

It is possible to modify the operation of these modules by directly editing the agent executable (/usr/bin/pandora_agent by default). The Pandora FMS agent is generally located in /usr/bin/pandora_agent. Searching for the string "Commands to retrieve" we get to the code part that contains the internal commands. We can make the modifications we need to adapt them to our system.

# 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}\
};

# 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}\
};

To change any of the predefined values to get the information, just edit the command but be careful with the following:

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}\'

1.9 Pandora FMS Windows Agents

1.9.1 Configuration of Pandora FMS Windows Agent

The fundamental paths and directories in the Windows agent installation will be found in the directory where the agent is installed, by default C: \Program Files. The most important ones to keep in mind are:

• C:\Program Files\pandora_agent: where the Pandora FMS agent is installed, its executable and its directories.
• C:\Program Files\pandora_agent\pandora_agent.conf: Agent configuration main file. Local execution modules and agent plugins are configured here.
• C:\Program Files\pandora_agent\PandoraAgent.exe: Executable binary of the agent.
• C:\Program Files\pandora_agent\util\tentacle_client.exe: Tentacle executable binary for transferring files to the server.
• C:\Program Files\pandora_agent\scripts: Pandora FMS agent start/stop/restart scripts
• C:\Program Files\pandora_agent\pandora_agent.log: Text file where Pandora FMS agent activity is saved, when the agent is executed in debug mode.
• C:\Program Files\pandora_agent\util: Directory containing the agent plugins.
• C:\Program Files\pandora_agent\collections: Directory containing the agent's collections.

1.10 Auto-upgrading Software Agents

Using the file collections and pandora_update tool we can provide a way to "self-update" the software agents.

Pandora_update tool requires Perl's Digest:MD5 module to function. It is included by default from Perl 5.14, but for earlier versions it has to be manually installed.

It works the following way:

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

Windows example:

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

Linux example:

/etc/pandora/collections/fc_1/pandora_agent

2. The agent runs the pandora_update plugin. This plugin receives a single parameter: the short name of the collection (in this example, fc_1). It will scan the collection directory for the agent binary, compare the binary located in the collection with the one currently running and if they are different, pandora_update stops the agent, replaces the binary and restarts the agent again using the new binary.

To update different architectures, a different collection must be established for each one of them. For example, if you need to update 32-bit and 64-bit Windows agents, you will have to create two collections and include the corresponding PandoraAgent.exe binary in each one of them.

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

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

1.11 Agent / Module Autocreation from XML File / Learning Mode

Agents can be configured from the console in three working modes:

• Learning mode: If the XML received from the software agent contains new modules, they will be automatically created. This is the default behavior.
• Normal mode: No new modules will be created that arrive in XML if they have not been previously declared in the console.
• Autodisable mode: Similar to learning mode, in this mode, also, if all modules pass to unknown state the agent will be automatically disabled, going to be enabled again if it receives new information.

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

The data that is incorporated into the agent at the moment of its creation automatically when receiving an XML is the following:

• Agent name.
• Agent's IP address.
• Agent description.
• Agent's parent.
• Timezone offset.
• Group.
• Operating system.
• Agent interval.
• Agent version
• Custom fields.
• Custom ID.
• URL address.
• Agent mode: Learning, Normal, Autodisable.

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

• Agent's IP address.
• Agent's parent .
• OS Version.
• Agent's version.
• Timezone.
• Custom fields.

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

In addition, with the learning mode activated, new modules will be created in Pandora FMS when received through XMLs.

1.11.3 Data added to the Module on Creation Time

The data entered in the module the first time an XML is received is as follows:

In 4.x version

• Name.
• Type.
• Description.
• Max Min value filter.
• Post process.
• Module interval.
• Min / Max Critical.
• Min / Max Warning.
• Disabled module.
• 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.
• Crontab.

1.11.4 Loaded Data when Module already exists

When an XML containing information from an existing module is received, only the description and extended information are updated, in addition to the module data.

Go back to Pandora FMS documentation index