Difference between revisions of "Pandora: Documentation en: Configuration Agents"
(→(>= 7.0OUM721) secondary_groups) |
Laura.cano (talk | contribs) |
||
(140 intermediate revisions by 10 users not shown) | |||
Line 1: | Line 1: | ||
+ | [[Pandora:Documentation_en|Go back to Pandora FMS documentation index]] | ||
+ | |||
+ | |||
= Pandora FMS Software Agents = | = Pandora FMS Software Agents = | ||
Line 5: | Line 8: | ||
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. | 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. | + | 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 [https://en.wikipedia.org/wiki/XML 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''. | + | Each of the individual checks is called '''''Module'''''. |
== Introduction to the Agent Configuration == | == Introduction to the Agent Configuration == | ||
− | The operation of the software agent is determined by its configuration file, called | + | The operation of the software agent is determined by its configuration file, called <code>pandora_agent.conf</code>, located in the installation directory (default value) <code>%ProgramFiles%\pandora_agent</code> on Windows systems, and <code>/etc</code> on GNU/Linux® systems. The configuration file contains all the operating parameters and modules of that agent. |
− | |||
− | The configuration file contains all the operating parameters and modules of that agent. | ||
== General Agent Parameters == | == General Agent Parameters == | ||
− | The Configuration of the General Agent Parameters is defined in this section. Some of them are common for | + | The Configuration of the General Agent Parameters is defined in this section. Some of them are common for MS Windows® y GNU/Linux® systems. |
+ | {{Warning|'''The agent configuration file encoding is UTF-8''' on both GNU/Linux® and MS Windows® systems. If you edit this file manually, check 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.}} | ||
− | {{warning|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: | + | {{warning|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: <code>version</code>, <code>date</code>, <code>OS version</code>, and the following parameters from the configuration file: <code>gis_exec</code>, <code>latitude</code>, <code>longitude</code>, <code>altitude</code>, <code>parent_agent_name</code>, <code>timezone_offset</code>, <code>address</code> and <code>custom_field</code>.}} |
− | + | You may find more information about Pandora FMS XML file format [[Pandora:Documentation_en:Development_and_Extension#Pandora_FMS_XML_data_file_format|here]]. You may also access [[Pandora:Documentation_en:Optimization#Pandora_FMS_XML_Stress|test data generation]] (capacity analysis tools). | |
===server_ip=== | ===server_ip=== | ||
Line 30: | Line 32: | ||
===server_path=== | ===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 | + | The server path is the comprehensive file path where the server stores all the data sent by the agents. The default path is <code>/var/spool/pandora/data_in</code>. |
===temporal=== | ===temporal=== | ||
Line 50: | Line 52: | ||
===logfile=== | ===logfile=== | ||
− | The path to the Pandora FMS agent events | + | The path to the Pandora FMS agent events log file. |
===interval=== | ===interval=== | ||
Line 58: | Line 60: | ||
===disable_logfile=== | ===disable_logfile=== | ||
− | This parameter disables log writing in pandora_agent.log. Only for | + | This parameter disables log writing in <code>pandora_agent.log</code>. Only for MS Windows®. |
===debug=== | ===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. | + | If it is active (<code>1</code>), 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. |
===agent_name=== | ===agent_name=== | ||
Line 68: | Line 70: | ||
It allows setting a custom name. If it is not enabled, the agent name will be the hostname of the machine. | It allows setting a custom name. If it is not enabled, the agent name will be the hostname of the machine. | ||
− | === | + | === agent_name_cmd=== |
+ | |||
+ | {{Tip|Version 5.1 SP2 or superior.}} | ||
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. | 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. | ||
− | === | + | === 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. | + | {{Tip|Version NG 7 or superior.}} |
+ | |||
+ | Defines the agent alias using an external command. If <code>agent_alias_cmd</code> is defined, <code>agent_alias</code> 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. | ||
===address=== | ===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 | + | This is the IP address of the software agent. It could be an IP address with the format <code>X.X.X.X</code> or a domain name such as <code>localhost</code> or <code>auto</code>. 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 <code>auto</code>, it will obtain the IP address from the host and added to the agent as in the previous case. |
===encoding=== | ===encoding=== | ||
− | Installs the kind of codification of the local system, such as ISO-8859-15 or UTF-8. | + | Installs the kind of codification of the local system, such as <code>ISO-8859-15</code> or <code>UTF-8</code>. |
===server_port=== | ===server_port=== | ||
− | + | Port where Pandora FMS [[Pandora:Documentation_en:Tentacle|Tentacle server]] listens to receive data files,<code>41121</code> by default. | |
===transfer_mode=== | ===transfer_mode=== | ||
− | This parameter specifies the transfer mode we have to install in order send the agent data to the server. Tentacle by default. | + | This parameter specifies the transfer mode we have to install in order send the agent data to the server. <code>Tentacle</code> by default. |
− | === | + | === transfer_timeout === |
+ | |||
+ | {{Tip|Version 6.0 or superior.}} | ||
It is the timeout for file transfer, if the indicated number of seconds is exceeded without completing the transfer, it will be cancelled. | It is the timeout for file transfer, if the indicated number of seconds is exceeded without completing the transfer, it will be cancelled. | ||
Line 98: | Line 106: | ||
===server_pwd=== | ===server_pwd=== | ||
− | + | Server password for authentication: specific for Windows® FTP and for the Tentacle transfer mode, although the [[Pandora:QuickGuides_EN:Secure_communication_with_tentacle|password for the latter is optional]]. | |
===server_ssl=== | ===server_ssl=== | ||
− | + | It specifies the Tentacle transfer mode. Allows to enable (<code>1</code>) or disable (<code>1</code>) SSL network encryption. Learn more about Tentacle safe communication [[Pandora:QuickGuides_EN:Secure_communication_with_tentacle|in this section]]. | |
===server_opts=== | ===server_opts=== | ||
Line 112: | Line 120: | ||
server_opts -y user:[email protected]:8080 | server_opts -y user:[email protected]:8080 | ||
− | This will force the Tentacle client | + | This will force the Tentacle client send data through a proxy located at <code>proxy.inet</code> on port <code>8080</code> using <code>user</code> and <code>pass</code> for authentication. If you intend to use a proxy on e.g. <code>192.168.1.2</code> on port <code>9000</code> without credentials, the command would have to be: |
server_opts -y 192.168.1.2:9000 | server_opts -y 192.168.1.2:9000 | ||
+ | |||
+ | Get more information about safe Tentacle communication [[Pandora:QuickGuides_EN:Secure_communication_with_tentacle|in this section]]. | ||
===delayed_startup=== | ===delayed_startup=== | ||
− | + | ''Disabled by default''. Waiting time ('''seconds''' or '''minutes''') until the agent starts running once started. For all Software Agents except for MS Windows®. | |
+ | |||
+ | ===startup_delay=== | ||
+ | |||
+ | ''Disabled by default''. Waiting time, in seconds, until the agent starts running once started. For MS Windows® only. | ||
===pandora_nice=== | ===pandora_nice=== | ||
Line 126: | Line 140: | ||
===autotime=== | ===autotime=== | ||
− | If it's enabled ( | + | If it's enabled (<code>1</code>) it sends a timestamp of special execution (AUTO) that makes the server use its local date / time to establish the data time, ignoring 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. |
===cron_mode=== | ===cron_mode=== | ||
− | With this parameter, it | + | With this parameter, it is 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 is deactivated (<code>0</code>) by default. |
===remote_config=== | ===remote_config=== | ||
− | + | [[Image:icono-modulo-enterprise.png|left|Versión Enterprise.]] | |
− | + | It enables (<code>1</code>) or disables (<code>0</code>) remote agent configuration. Operation is only allowed with Tentacle transfer mode. | |
===xml_buffer=== | ===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. | + | If enabled (<code>1</code>), 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. |
===timezone_offset=== | ===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. | + | The agent can now install its [https://en.wikipedia.org/wiki/Time_zone 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: Difference with the server timezone | ||
Line 154: | Line 168: | ||
Indicates the parent of the software agent. It must be the name of an existing agent in Pandora FMS. | Indicates the parent of the software agent. It must be the name of an existing agent in Pandora FMS. | ||
− | === agent_threads | + | === agent_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 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. | ||
Line 161: | Line 175: | ||
agent_threads 4 | agent_threads 4 | ||
− | ===include | + | ===include === |
+ | |||
+ | include <file> | ||
+ | |||
+ | It allows to include an additional configuration file. This file can contain additional modules and collections alongside the ones found in the main configuration file. This token is optional. The file can be uploaded by those users with (<code>AW</code>) Agent writing [[Pandora:Documentation_en:Managing_and_Administration#Profiles_in_Pandora_FMS|permissions]]. | ||
− | + | ===broker_agent === | |
− | + | broker_agent <broker_name> | |
− | + | It enables broker agent feature. To activate it, you only need to uncomment the parameter and indicate the name (<code><broker_name></code>) that will be assigned to the broker agent. | |
− | + | ===pandora_user=== | |
− | + | pandora_user <user> | |
− | This parameter is optional and allows the agent to be executed with a specified system user. This user | + | This parameter is optional and allows the agent to be executed with a specified system user(<code><user></code> . This user must have permissions to execute the agent and all associated resources. |
− | === | + | ===custom_id=== |
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
Custom ID of the agent for external applications. | Custom ID of the agent for external applications. | ||
− | === | + | ===url_address=== |
+ | |||
+ | {{Tip|Version 5.X or superior.}} | ||
Custom URL to open it from the agent in the console. | Custom URL to open it from the agent in the console. | ||
− | === | + | ===custom_fieldX_name=== |
− | + | {{Tip|Version 5.X or superior.}} | |
− | Example: | + | Name of an agent custom field which already exists on the system. If does not exist, it will be ignored. Example: |
custom_field1_name Model | custom_field1_name Model | ||
− | === | + | ===custom_fieldX_value=== |
− | + | {{Tip|Version 5.X or superior.}} | |
− | Example: | + | Value for the [[Pandora:Documentation_en:Configuration_Agents#custom_fieldX_name|custom_fieldX_name]] in the previous parameter. Example: |
custom_field1_value C1700 | custom_field1_value C1700 | ||
− | === | + | === macro=== |
+ | |||
+ | {{Tip|Version 5.X or superior.}} | ||
− | + | macro<macro> <value> | |
+ | |||
+ | It defines a [[Pandora:Documentation_en:Templates_and_components#Local_execution_macros|local execution macro]] that can be used in the definition of a module. These macros are used in the Metaconsole 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. | ||
+ | |||
+ | Local execution macros start by <code>_fieldx_</code>. | ||
Example: | Example: | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | === | + | module_begin |
+ | module_name Particion_opt | ||
+ | module_type generic_data | ||
+ | module_exec df -kh _field1_ | tail -1 | awk '{ print $5}' | tr -d "%" | ||
+ | module_macro_field1_ /opt | ||
+ | module_end | ||
+ | |||
+ | === group_password <password> === | ||
+ | |||
+ | {{Tip|Version 6.0 SP5 or superior.}} | ||
+ | |||
+ | Password for the agent group. Leave it commented if the group is not password-protected. | ||
+ | |||
+ | === ehorus_conf=== | ||
+ | |||
+ | {{Tip|Version NG 7 or superior.}} | ||
+ | |||
+ | ehorus_conf <path> | ||
+ | |||
+ | Absolute path to a valid [[Pandora:Documentation_en:Configuration_Console#eHorus|eHorus]] agent configuration file. The agent will create a custom field named <code>eHorusID</code> that contains the eHorus agent's identifying key. | ||
+ | |||
+ | === transfer_mode_user === | ||
− | + | {{Tip|Version NG 7.0 OUM713 or superior.}} | |
− | + | 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 <code>apache</code>. | |
− | === | + | === secondary_groups === |
− | |||
− | + | {{Tip|Version NG 7.0 OUM721 or superior.}} | |
+ | |||
+ | secondary_groups <group name1>, <group name2>, ... <group nameN> | ||
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. | 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. | ||
− | === | + | ===standby === |
− | + | {{Tip|Versión NG 7.0 OUM728 o superior.}} | |
− | + | standby <1|0> | |
+ | |||
+ | If an agent is in <code>standby 1</code> 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 feature and the agent is executed normally. | ||
== Secondary Server == | == Secondary Server == | ||
Line 252: | Line 298: | ||
== UDP Server == | == UDP Server == | ||
− | + | {{Warning|Bear in mind that UDP is unsafe by nature (but efficient to send messages without compromising a true response).}} | |
− | + | The Pandora FMS Agent can be configured to listen to [[Pandora:Documentation_en:Operations#UDP_remote_commands|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. | |
− | * '''udp_server''': To activate the UDP server, set it | + | There are several options to configure the UDP remote server, the following options in its [[Pandora:Documentation_es:Configuracion_Agentes#Introducci.C3.B3n_a_la_configuraci.C3.B3n_del_Agente_Software|configuration file]] <code>pandora_agent.conf</code>: |
+ | |||
+ | * '''udp_server''': To activate the UDP server, set it to <code>1</code>. This is deactivated by default. | ||
* '''udp_server_port''': Port where it listens. | * '''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. | * '''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. | ||
+ | |||
+ | {{Warning|Although it can be set to ''0.0.0.0'' for accepting from all sources, said practice is not recommended. If you have several Pandora FMS servers and/or use IPv6, you may add different IP adresses separated by commas. For instance, if you have in IPv6:<br><code>2001:0db8:0000:130F:0000:0000:087C:140B</code><br> and its abbreviation is <br><code>2001:0db8:0:130F::87C:140B</code><br>, use both separated by commas.}} | ||
+ | |||
* '''process_<name>_start <command>''': Command which is going to start a process defined by the user. | * '''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. | * '''process_<name>_stop <command>''': Command which is going to stop the process. | ||
Line 274: | Line 325: | ||
The server accepts the following commands: | The server accepts the following commands: | ||
− | + | ;<code><START|STOP> SERVICE <service name></code>: Starting or stopping a service (''service name''). | |
− | + | ;<code><START|STOP> PROCESS <process name></code>: Starting or stopping a process (''process name''). | |
− | + | ;<code>REFRESH AGENT <agent name></code>: Forces one execution of the agent (''agent name'') and refreshes data. | |
− | |||
− | |||
For example: | For example: | ||
Line 286: | Line 335: | ||
REFRESH AGENT 007 | REFRESH AGENT 007 | ||
− | There is a script on the server at | + | There is a script on the server at <code>/util/udp_client.pl</code> 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> | ./udp_client.pl <address> <port> <command> | ||
Line 294: | Line 343: | ||
./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT" | ./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT" | ||
− | For more information, please go to the Alert Configuration section. | + | For more information, please go to the [[Pandora:Documentation_en:Alerts#Predefined_Commands|Alert Configuration section]]. |
== Modules definition == | == Modules definition == | ||
− | The local execution modules are defined in the configuration file pandora_agent. conf. | + | The local execution modules are defined in the [[Pandora:Documentation_en:Configuration_Agents#Introduction_to_the_Agent_Configuration|configuration file]] <code>pandora_agent.conf</code>. The general syntax is the following: |
− | |||
− | The general syntax is the following: | ||
module_begin | module_begin | ||
Line 308: | Line 355: | ||
module_end | module_end | ||
− | There are | + | Where ''module name'' is the name of the module and ''local command'' the command to be executed. There are multiple additional options for modules, in this example only common and mandatory lines have been used for most of the cases. |
+ | |||
+ | Learn more in our video tutorials: | ||
+ | * [https://www.youtube.com/watch?v=Ya-aZ7EpaD4 "How to configure a Linux module in Pandora FMS"]. | ||
+ | * [https://www.youtube.com/watch?v=iJXvKySFZ8M "Windows local module creation in Pandora FMS"]. | ||
+ | |||
+ | The following sections explain each one of them in detail. | ||
=== Common elements of all modules === | === Common elements of all modules === | ||
− | {{warning|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. }} | + | {{warning|Module fields (except for module data, description and extended info) are only stored on module creation and will never be updated if the module is already created. }} |
==== module_begin ==== | ==== module_begin ==== | ||
− | |||
− | ==== module_name | + | Tag at the beginning of the module. It is '''mandatory'''. |
+ | |||
+ | ==== module_name ==== | ||
+ | |||
+ | module_name <name> | ||
− | Name of the module ( | + | Name of the module ('''mandatory'''). This name must be unique within the agent. |
==== module_type ==== | ==== module_type ==== | ||
− | Type of data the module will return. It is | + | module_type <type> |
+ | |||
+ | Type of data the module will return. It is '''mandatory''' to choose one of these. The available types are: | ||
− | * '''Numerical''' (generic_data) | + | * '''Numerical''' (<code>generic_data</code>): Simple numerical data, in floating points or wholes. |
− | * '''Incremental''' (generic_data_inc) | + | * '''Incremental''' (<code>generic_data_inc</code>): 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) | + | * '''Absolute incremental''' (<code>generic_data_inc_abs</code>): 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) | + | * '''Alphanumeric''' (<code>generic_data_string</code>): It collects alphanumeric text strings. |
− | * '''Booleans''' (generic_proc) | + | * '''Booleans''' (<code>generic_proc</code>): 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) | + | * '''Asynchronous Alphanumeric''' (<code>async_string</code>): 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) | + | * '''Asynchronous Boolean''' (<code>async_proc</code>): Similar to 'generic_proc' but asynchronous. |
− | * '''Asynchronous Numerical''' (async_data) | + | * '''Asynchronous Numerical''' (<code>async_data</code>): Similar to 'generic_data' but asynchronous. |
==== module_min <value> ==== | ==== module_min <value> ==== | ||
− | Minimum value that the module must return to be accepted. Otherwise it will be discarded | + | module_min <value> |
+ | |||
+ | Minimum value that the module must return in order to be accepted. Otherwise it will be discarded by the server. | ||
==== module_max <value> ==== | ==== module_max <value> ==== | ||
− | Maximum value that the module must return to be accepted. Otherwise it will be discarded | + | module_max <value> |
+ | |||
+ | Maximum value that the module must return to be accepted. Otherwise it will be discarded by the server. | ||
+ | |||
+ | ==== module_min_warning ==== | ||
+ | |||
+ | module_min_warning <value> | ||
+ | |||
+ | This is the minimum value that will make the module go into <code>warning</code> status. | ||
+ | |||
+ | ==== module_max_warning ==== | ||
+ | |||
+ | module_max_warning <value> | ||
+ | |||
+ | This is the maximum value that will make the module go into <code>warning</code> status. | ||
+ | |||
+ | ==== module_min_critical ==== | ||
+ | |||
+ | module_min_critical <value> | ||
+ | |||
+ | This is the minimum value that will make the module go into <code>critical</code> status. | ||
+ | |||
+ | ==== module_max_critical ==== | ||
+ | |||
+ | module_max_critical <value> | ||
+ | |||
+ | This is the maximum value of the <code>critical</code> status threshold. | ||
+ | |||
+ | ==== module_disabled ==== | ||
+ | |||
+ | module_disabled <0|1> | ||
+ | |||
+ | It indicates whether the module is enabled (<code>0</code>) or disabled (<code>1</code>). | ||
+ | |||
+ | ==== module_min_ff_event ==== | ||
+ | |||
+ | module_min_ff_event <value> | ||
+ | |||
+ | [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|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. | ||
+ | |||
+ | ==== module_each_ff ==== | ||
+ | |||
+ | {{Tip|Version 6.0 SP4 or superior.}} | ||
+ | |||
+ | module_each_ff <0|1> | ||
+ | |||
+ | If enabled (<code>1</code>), [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|flip flop'' thresholds]] per status will be used instead of <code>module_min_ff_event</code>: | ||
+ | * <code>module_min_ff_event_normal</code>. | ||
+ | * <code>module_min_ff_event_warning</code>. | ||
+ | * <code>module_min_ff_event_critical</code>. | ||
+ | |||
+ | ==== module_min_ff_event_normal ==== | ||
+ | |||
+ | {{Tip|Version 6.0 SP4 or superior.}} | ||
− | + | module_min_ff_event_normal <value> | |
− | + | [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|Flip flop]] protection value for switching to <code>normal</code> status. | |
− | ==== | + | ==== module_min_ff_event_warning ==== |
− | + | {{Tip|Version 6.0 SP4 or superior.}} | |
− | + | module_min_ff_event_warning <value> | |
− | + | [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|Flip flop]] protection value for switching to <code>warning</code> status. | |
− | ==== | + | ==== module_min_ff_event_critical ==== |
− | + | {{Tip|Version 6.0 SP4 or superior.}} | |
− | + | module_min_ff_event_critical <value> | |
− | |||
− | + | [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|Flip flop]] protection value for switching to <code>critical</code> status. | |
− | + | ==== module_ff_timeout ==== | |
− | + | {{Tip|Version 6.0 SP4 or superior.}} | |
− | + | module_ff_timeout <seconds> | |
− | |||
− | + | It resets the [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|flip flop]] threshold counter after the given number of seconds. This implies that the number of status changes set in <code>module_min_ff_event</code> must take place at an interval of <code>module_ff_timeout</code> seconds before the state changes in the console's visual level. | |
− | ==== | + | ==== module_ff_type ==== |
− | + | {{Tip|Version NG 734 or superior.}} | |
− | + | module_ff_type <value> | |
− | |||
− | + | This is a [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|Flip Flop]] advanced option to control the status of a module. By means of <code>Keep counters</code> 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 <code>Keep counters</code> is enabled (<code>1</code>) or disabled (<code>0</code>). | |
− | ==== module_description | + | ==== module_description ==== |
+ | |||
+ | module_description <text> | ||
Free text with information about the module. | Free text with information about the module. | ||
− | ==== module_interval | + | ==== module_interval ==== |
− | + | module_interval <factor> | |
− | ==== module_timeout | + | |
+ | This interval is calculated as a multiplier for the agent interval. If the agent has e.g. the agent's interval is 300 (5 minutes) but you wish for a module to be processed only every 15 minutes, add this line: | ||
+ | |||
+ | module_interval 3 | ||
+ | |||
+ | That way the module will be processed every 300 seconds x 3 = 900 seconds (15 minutes). | ||
+ | |||
+ | {{Warning|In order for the <code>module_interval</code> 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.}} | ||
+ | |||
+ | ==== module_timeout ==== | ||
+ | |||
+ | 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. | 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. | ||
− | ==== module_postprocess | + | ==== module_postprocess ==== |
+ | |||
+ | module_postprocess <factor> | ||
Numerical value by which the data returned by the module will be multiplied. It is useful for unit conversions. | Numerical value by which the data returned by the module will be multiplied. It is useful for unit conversions. | ||
− | ==== module_save | + | ==== module_save ==== |
− | + | module_save <nowiki><var name></nowiki> | |
− | + | It stores the value returned by the module in a variable with the name indicated in this parameter (<code><nowiki><var name></nowiki></code>). This value can be used later in other modules. | |
+ | |||
+ | Example in Unix/Linux:: | ||
module_begin | module_begin | ||
Line 432: | Line 559: | ||
This second module will show the contents of the variable "$ECHO_1", it being "41121". | 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. | + | In Windows agents the module would have to be formed with <code>%var%</code> instead of <code>$var</code>. Following the example: |
− | Following the example: | ||
module_begin | module_begin | ||
Line 441: | Line 567: | ||
module_end | module_end | ||
− | ==== module_crontab | + | ==== module_crontab ==== |
From version 3.2, it's possible to schedule modules in the order they'll be executed on a specific date. | From version 3.2, it's possible to schedule modules in the order they'll be executed on a specific date. | ||
Line 456: | Line 582: | ||
* Day of the week 0-6 (0 is Sunday) | * Day of the week 0-6 (0 is Sunday) | ||
− | It | + | It is 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, | + | In order for one module to be executed e.g. every Monday between 12 and 15, the following configuration should be used: |
module_begin | module_begin | ||
Line 476: | Line 602: | ||
module_end | module_end | ||
− | ==== module_condition <operation> <command> | + | ==== module_condition ==== |
+ | |||
+ | module_condition <operation> <command> | ||
− | + | It is possible to define actions that will be executed by the agent according to the value returned by the module. Only available for numerical values. The syntax is the following: | |
− | * '''>''' [value]: | + | * '''>''' [value]: It executes the command if the module value is higher than the given one. |
− | * '''<''' [valor]: | + | * '''<''' [valor]: It executes the command if the module value is lower than the given one. |
− | * '''=''' [valor]: | + | * '''=''' [valor]: It executes the command if the module value is equal to the given one. |
− | * '''!=''' [valor]: | + | * '''!=''' [valor]: It executes the command if the module value is different to the given one. |
− | * '''=~''' [regular expression]: | + | * '''=~''' [regular expression]: It executes the command if the module value coincides with the given regular expression. |
− | * '''('''valor, valor''')''': | + | * '''('''valor, valor''')''': It 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 | + | Multiple conditions can be specified for a single module. In the following case, the <code>script_1.sh</code> will be executed if the value returned by the module is between 1 and 3, and <code>script_2.sh</code> 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 <code>module_exec</code> line , only the first condition <code>script_1.sh</code> will be executed: |
module_begin | module_begin | ||
Line 509: | Line 637: | ||
module_exec tasklist | grep MyProcess | wc -l | module_exec tasklist | grep MyProcess | wc -l | ||
module_condition > 2 taskkill /IM MyProcess* /F | module_condition > 2 taskkill /IM MyProcess* /F | ||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
module_end | module_end | ||
Line 525: | Line 646: | ||
module_end | module_end | ||
− | *'''NOTE''': On Windows platforms, it | + | *'''NOTE''': On Windows platforms, it is recommended to use '''cmd.exe /c''' to execute the command to ensure it's executed properly. For example: |
module_begin | module_begin | ||
Line 534: | Line 655: | ||
module_end | module_end | ||
− | ==== module_precondition | + | ==== module_precondition ==== |
− | + | module_precondition <operation> <command> | |
− | + | It allows to determin whether a module is executed or not depending on the result of a given execution. Syntax: | |
− | * ''' | + | * '''>''' [value]: It executes the command if the module value is higher than the given one. |
− | * ''' | + | * '''<''' [value]: It executes the command if the module value is lower than the given one. |
− | * ''' | + | * '''=''' [value]: It executes the command if the module value is equal to the given one. |
− | * '''= | + | * '''!=''' [value]: It executes the command if the module value is different to the given one. |
− | * ''' | + | * '''=~''' [regular expression]: It executes the command if the module value coincides with the given regular expression. |
− | 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 | + | * '''('''value, value''')''': It 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 <code>module_precondition</code> line is 5, a value between 2 and 8, so ''monitoring_variable.bat'' will be executed correctly: | ||
module_begin | module_begin | ||
Line 559: | Line 682: | ||
module_end | module_end | ||
− | Like postconditions, it's also possible to use several preconditions. The module | + | Like postconditions, it's also possible to use several preconditions. The module will only be executed if all preconditions are met: |
module_begin | module_begin | ||
Line 569: | Line 692: | ||
module_end | module_end | ||
− | *'''NOTE''': On Windows platforms, it | + | *'''NOTE''': On Windows platforms, it is recommended to use '''cmd.exe /c''' to execute the command to ensure it's proper execution. For example: |
module_begin | module_begin | ||
Line 578: | Line 701: | ||
module_end | module_end | ||
− | ==== | + | ==== module_unit ==== |
− | + | {{Tip|Version 5.x or superior.}} | |
− | Example: | + | module_unit <string> |
+ | |||
+ | Units shown as a text string next to the value obtained by the module. Example: | ||
module_unit % | module_unit % | ||
− | ==== | + | ==== module_group ==== |
+ | |||
+ | {{Tip|Version 5.X or superior.}} | ||
+ | |||
+ | module_group <value> | ||
− | |||
− | Example: | + | It allows to indicate the module group (value) the module will be assigned to. Example: |
module_group Networking | module_group Networking | ||
− | ==== | + | ==== module_custom_id ==== |
− | + | {{Tip|Version 5.X or superior.}} | |
− | Example: | + | module_custom_id <value> |
+ | |||
+ | This is a custom identifier for the module. Example: | ||
module_custom_id host101 | module_custom_id host101 | ||
− | ==== | + | ==== module_str_warning ==== |
+ | |||
+ | {{Tip|Version 5.X or superior.}} | ||
− | + | module_str_warning <value> | |
− | Example: | + | This is a regular expression to define the <code>warning</code> threshold in alphanumeric modules (string). Example: |
module_str_warning .*NOTICE.* | module_str_warning .*NOTICE.* | ||
− | ==== | + | ==== module_str_critical ==== |
+ | |||
+ | {{Tip|Version 5.X or superior.}} | ||
− | + | module_str_critical <value> | |
− | Example: | + | This is a regular expression to define the <code>critical</code> status threshold in the string modules. Example: |
+ | |||
+ | module_str_critical .*ERROR.* | ||
+ | |||
+ | ==== module_warning_instructions ==== | ||
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
+ | |||
+ | module_warning_instructions <value> | ||
− | + | These are the instructions shown in the module-generated event when going into <code>warning</code> status. | |
− | + | Example to show the message indicating an issue getting higher priority: | |
− | + | module_warning_instructions Raise advocacy priority | |
− | + | ==== module_critical_instructions ==== | |
− | + | {{Tip|Version 5.x or superior.}} | |
− | + | module_critical_instructions <value> | |
− | These are the instructions | + | These are the instructions shown in de module-generated event when going into <code>critical</code> status. |
− | Example: | + | Example of a message to alert the system department: |
module_critical_instructions Call to sys department | module_critical_instructions Call to sys department | ||
− | ==== | + | ==== module_unknown_instructions ==== |
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
− | + | module_unknown_instructions <value> | |
− | Example: | + | These are the instructions shown in the module-generated event when going into <code>unknown</code> status. |
+ | |||
+ | Example of message to open issue: | ||
module_unknown_instructions Open incident | module_unknown_instructions Open incident | ||
− | ==== | + | ==== module_tags ==== |
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
+ | |||
+ | module_tags <value> | ||
− | + | Tags to be assigned to the module separated by commas. | |
Example: | Example: | ||
Line 650: | Line 800: | ||
module_tags tag1,tag2,tag3 | module_tags tag1,tag2,tag3 | ||
− | ==== | + | ==== module_warning_inverse ==== |
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
− | + | module_warning_inverse <value> | |
+ | |||
+ | It allows activating (<code>1</code>) the inverse interval for the <code>warning</code> threshold. | ||
Example: | Example: | ||
− | + | module_warning_inverse 1 | |
− | ==== | + | ==== module_critical_inverse ==== |
− | + | {{Tip|Version 5.x or superior.}} | |
+ | |||
+ | module_critical_inverse <value> | ||
+ | |||
+ | It allows activating (<code>1</code>) the inverse interval for the <code>critical</code> threshold. | ||
Example: | Example: | ||
Line 666: | Line 824: | ||
module_critical_inverse 1 | module_critical_inverse 1 | ||
− | ==== | + | ==== module_native_encoding ==== |
− | |||
− | + | {{Tip|Version 5.x or superior on Win32 only.}} | |
− | + | module_native_encoding <value> | |
− | + | This configuration token only affects executed modules by command line, that is, there is a <code>module_exec</code> in the module configuration. | |
− | |||
− | |||
− | |||
− | |||
− | + | MS Windows® manages [https://en.wikipedia.org/wiki/Windows_code_page#UTF-8,_UTF-16 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 accents. With this token, the Pandora FMS agent transforms the output to the encoding specified in the configuration file. | |
− | + | <code>module_native_encoding</code> has four acceptable values: | |
− | If enabled (1) the module will be in silent mode: it will not generate events or trigger alerts, nor will it store data history. | + | <code>module_native_encoding OEM</code>: to command line encoding |
+ | * <code>module_native_encoding ANSI</code>: to system encoding | ||
+ | * <code>module_native_encoding UTFLE</code>: to UTF-16 little-endian | ||
+ | * <code>module_native_encoding UTFBE</code>: to UTF-16 big-endian | ||
+ | |||
+ | If <code>module_native_encoding</code> does not appear, no re-encoding will be done. | ||
+ | |||
+ | ==== module_quiet ==== | ||
+ | |||
+ | {{Tip|Version 5.x or superior.}} | ||
+ | |||
+ | module_quiet <value> | ||
+ | |||
+ | If enabled (<code>1</code>) the module will be in silent mode: it will not generate events or trigger alerts, nor will it store data history. | ||
Example: | Example: | ||
Line 689: | Line 855: | ||
module_quiet 1 | module_quiet 1 | ||
− | ==== | + | ==== module_ff_interval ==== |
− | + | {{Tip|Version 5.x or superior.}} | |
− | + | module_ff_interval <value> | |
+ | |||
+ | This is the [[Pandora:Documentation_en:Glossary#Flip-Flop_Protection|Flip Flop]] execution threshold of the module (in seconds). For instance: | ||
module_ff_interval 2 | module_ff_interval 2 | ||
− | ==== | + | ==== module_macro ==== |
+ | |||
+ | module_macro<macro> <value> | ||
+ | |||
+ | |||
+ | It only applies to local components from the console. It is not useful in the configuration file. | ||
− | + | ==== module_alert_template ==== | |
− | + | module_alert_template <template_name> | |
− | This macro assigns to the module the alert template that corresponds to the name introduced as parameter(see [http://wiki.pandorafms.com/index.php?title=Pandora:Documentation_en:Alerts#Alert_Templates Alert templates]) | + | This macro assigns to the module the alert template that corresponds to the name introduced as parameter (see [http://wiki.pandorafms.com/index.php?title=Pandora:Documentation_en:Alerts#Alert_Templates Alert templates]). |
Example: | Example: | ||
Line 716: | Line 889: | ||
<max_warning>90</max_warning> | <max_warning>90</max_warning> | ||
<alert_template><![CDATA[Critical condition]]></alert_template> | <alert_template><![CDATA[Critical condition]]></alert_template> | ||
− | <data><![CDATA[92]]></data> | + | <nowiki><data><![CDATA[92]]></data></nowiki> |
</module> | </module> | ||
==== module_end ==== | ==== module_end ==== | ||
− | Defines the end of the module | + | Defines the end of the module. It is '''mandatory'''. |
=== Specific guidelines to obtain information === | === 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 | + | Furthermore, there are the specific guidelines that could be specified for each module in order to '''obtain information''' as such. Only one type can be used in each module. |
− | ==== module_exec | + | ==== module_exec ==== |
+ | |||
+ | module_exec <command> | ||
General command execution line. The desired run must be specified to obtain the information in a single line. | 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. | + | On GNU/Linux, the command will be executed using the default command prompt. The default interpreter will be determined by the symbolic link <code>/bin/sh</code>. Usually the link points to''' bash''', but in systems like Ubuntu this is not the case (in this case it points to [http://manpages.ubuntu.com/manpages/hirsute/man1/dash.1.html '''dash''']). Therefore, it could happen that a command is tested in the terminal and then there is an error when the agent executes it. A solution that will work in most cases will be forcing the '''bash''' execution of the command as follows: |
module_exec bash -c "<command>" | module_exec bash -c "<command>" | ||
− | {{Warning|If execution returns a return code different from | + | {{Warning|If execution returns a return code different from 0, it will be interpreted as '''execution error''' and the information will be discarded.}} |
− | For a | + | For a Windows® agent there are more guidelines for obtaining data, which are described below. |
− | ==== module_service | + | ==== module_service ==== |
− | + | module_service <service> | |
+ | |||
+ | It checks whther a specific service is being executed on the machine. | ||
+ | |||
+ | ===== In MS Windows ===== | ||
+ | |||
+ | Remember to use the <code>" "</code> characters if the name of the service contains blank spaces. | ||
module_begin | module_begin | ||
Line 750: | Line 931: | ||
module_end | module_end | ||
− | The service is identified with the short name of the service ( | + | The service is identified with the short name of the service (<code>Service name</code>), as it appears in the Windows services manager. |
− | + | ||
− | [[ | + | [[Image:Service_name_id.png|center|400px]] |
− | |||
'' Asynchronous Mode '' | '' Asynchronous Mode '' | ||
− | Pandora FMS usually executes a test battery (each of | + | Pandora FMS usually executes a test battery (each of them defined by a module) every N seconds (300 sec. = 5 min. by default). If a service is down just after a Pandora FMS execution, it will take 300 additional seconds to find out the service that went down. The difference on asynchronous mode is that modules notify Pandora FMS right away about the fail or shutdown of this service. This is called ''asynchronous'' operation mode. It would be enough to add the following command to the guideline to use it: |
module_async yes | module_async yes | ||
Line 763: | Line 943: | ||
This feature is not supported on broker agents. | This feature is not supported on broker agents. | ||
− | {{Warning| | + | {{Warning|In Windows Home Edition®, this asynchronous feature is not supported and, only in those versions, Pandora FMS agent makes a periodic query to find out whether 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.}} |
− | In Windows Home | ||
'' Service Watchdog '' | '' 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 | + | 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 does not require any parameter, because Windows® already knows how to do it. In such cases, the configuration is a lot easier: |
module_begin | module_begin | ||
Line 779: | Line 958: | ||
module_end | module_end | ||
− | + | ===== In Unix ===== | |
− | In Unix, | + | In Unix, it works the same as in MS Windows®, the only difference is that for Unix, process and service are the same concepts, for example to see if the '''bash''' process is active in the system, just run: |
module_begin | module_begin | ||
Line 792: | Line 971: | ||
Watchdog mode and asynchronous detection are not possible in the Unix agent. | Watchdog mode and asynchronous detection are not possible in the Unix agent. | ||
− | ==== module_proc <process> ==== | + | ==== module_proc ==== |
+ | |||
+ | module_proc <process> | ||
+ | |||
+ | It checks whether a specific process name is working in this machine. | ||
+ | |||
+ | ===== In MS Windows ===== | ||
− | + | {{Tip|Quotation marks are not needed for the process name. Bear in mind that the name of the process must have the <code>.exe</code> extention. The module will return the number of processes executed with this name.}} | |
− | This is an example of the monitoring of the | + | This is an example of the monitoring of the <code>cmd.exe</code> process: |
module_begin | module_begin | ||
Line 804: | Line 989: | ||
module_description Process Command line | module_description Process Command line | ||
module_end | module_end | ||
− | |||
− | |||
− | |||
− | |||
'' Asynchronous mode '' | '' Asynchronous mode '' | ||
− | In a similar way to the services, monitoring processes can be critical in some cases. The | + | In a similar way to the services, monitoring processes can be critical in some cases. The Windows® software agent supports '''asynchronous''' checking for the <code>module_proc</code> parameter. 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. That way, you may get informed about failed of critical processes right away. This is an example of process asynchronous monitoring: |
module_begin | module_begin | ||
Line 821: | Line 1,002: | ||
module_end | module_end | ||
− | The difference is located in the configuration token | + | The difference is located in the <code>module_async yes</code> configuration token. This feature is not supported on broker agents. |
''Processes Watchdog '' | ''Processes Watchdog '' | ||
− | A Watchdog is a system that allows to act immediately if an agent is down, usually | + | A Watchdog is a system that allows to act immediately if an agent is down, usually activating the process that went down. Pandora FMS Windows® Agent could work 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. | ||
− | + | {{Tip|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 <code>module_proc</code> with watchdog enabled: | ||
module_begin | module_begin | ||
Line 842: | Line 1,027: | ||
module_end | module_end | ||
− | This is the definition of additional parameters for | + | This is the definition of additional parameters for <code>module_proc</code> with watchdog enabled: |
− | + | ;module_retries: Number of consecutive attempts that the module will try to activate 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 will 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 controls in which session you want the process to be launched. If set to <code>no</code>, the process will start in the service session and therefore remain in the background (default setting). Otherwise, if set to <code>yes</code>, the process will be launched in the user's session and will be visible from the PC desktop. | |
− | {{Warning|For versions prior to Windows | + | {{Warning|For versions prior to Windows Vista®, the <code>module_user_session</code> token can be configured in a general way by enabling the checkbox "Interactive access with desktop" in the Pandora FMS service properties ('''Allow service to interact with desktop'''):[[Image:Service_interactive.png|center|400px]]}} |
− | < | + | {{Tip|Pandora FMS is executed under the <code>SYSTEM</code> 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 a certain user, you will have to include in a script (<code>.bat</code> or similar) the previous processes to initialize the environment, environment variables, etc., and execute that script as a watchdog action.}} |
− | [[ | + | |
− | + | ===== In Unix ===== | |
+ | |||
+ | Under UNIX, this module works just like [[Pandora:Documentation_en:Configuration_Agents#module_service|module_service]]. It does not support asynchronous and/or watchdog mode. | ||
− | + | ==== module_cpuproc ==== | |
− | + | {{Tip|Only for Unix}} | |
− | + | module_cpuproc <process> | |
− | + | It returns the CPU usage of a specific process. Example: | |
module_begin | module_begin | ||
Line 873: | Line 1,060: | ||
module_end | module_end | ||
− | ==== module_memproc | + | ==== module_memproc ==== |
− | + | module_memproc <process> | |
− | + | '''Only for Unix'''. It returns the memory used by a specific process. | |
module_begin | module_begin | ||
Line 886: | Line 1,073: | ||
module_end | module_end | ||
− | ==== module_freedisk < | + | ==== module_freedisk ==== |
+ | |||
+ | module_freedisk <disk_letter:>|<vol> | ||
+ | |||
+ | It checks for the free space in the disk unit. | ||
+ | |||
+ | ;In Windows: Place <code>:</code> after the <code><disk_letter:></code>. | ||
+ | |||
+ | module_begin | ||
+ | module_name freedisk | ||
+ | module_type generic_data | ||
+ | module_freedisk C: | ||
+ | module_end | ||
− | + | ;In Unix: The volume to test, such as <code>/var</code>. | |
+ | module_begin | ||
+ | module_name disk_var | ||
+ | module_type generic_data | ||
+ | module_freedisk /var | ||
+ | module_end | ||
− | + | ==== module_freepercentdisk ==== | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | < | + | module_freepercentdisk <disk_letter:>|<vol> |
− | |||
− | |||
− | |||
− | |||
− | |||
− | < | ||
− | + | This module returns the free disk percentage under a logic unit. | |
− | + | ;In Windows: Type <code>:</code> after <code><disk_letter:></code>. | |
− | |||
module_begin | module_begin | ||
module_name freepercentdisk | module_name freepercentdisk | ||
Line 917: | Line 1,108: | ||
module_freepercentdisk C: | module_freepercentdisk C: | ||
module_end | module_end | ||
− | </ | + | |
+ | ;In Unix: The volume to check, such as <code>/var</code>. | ||
module_begin | module_begin | ||
Line 925: | Line 1,117: | ||
module_end | module_end | ||
− | ==== module_occupiedpercentdisk | + | ==== module_occupiedpercentdisk ==== |
− | + | module_occupiedpercentdisk <vol> | |
− | This module returns the occupied disk percentage | + | '''Only for Unix'''. This module returns the occupied disk percentage, for instance: |
module_begin | module_begin | ||
Line 937: | Line 1,129: | ||
module_end | module_end | ||
− | ==== module_cpuusage | + | ==== module_cpuusage ==== |
− | + | module_cpuusage [<cpu id>|all] | |
− | It | + | It returns the CPU usage in a CPU number. If there is only one CPU, please leave it blank or use <code>all</code>. For Windows® and Unix. |
+ | |||
+ | It is also possible to obtain the average use of all CPUs in multiprocessor systems this way: | ||
module_begin | module_begin | ||
− | module_name | + | module_name CPU_use |
module_type generic_data | module_type generic_data | ||
module_cpuusage all | module_cpuusage all | ||
− | module_description | + | module_description CPU average use |
module_end | module_end | ||
Line 953: | Line 1,147: | ||
module_begin | module_begin | ||
− | module_name | + | module_name CPU_1 |
module_type generic_data | module_type generic_data | ||
module_cpuusage 1 | module_cpuusage 1 | ||
− | module_description | + | module_description CPU #1 average use |
module_end | module_end | ||
==== module_freememory ==== | ==== module_freememory ==== | ||
− | Supported in | + | Supported in Windows® and UNIX. It returns the free memory of the whole system: |
module_begin | module_begin | ||
Line 972: | Line 1,166: | ||
==== module_freepercentmemory ==== | ==== module_freepercentmemory ==== | ||
− | Supported under UNIX and | + | Supported under UNIX and Windows®. This module returns the free memory percentage on one system: |
module_begin | module_begin | ||
Line 982: | Line 1,176: | ||
==== module_tcpcheck ==== | ==== module_tcpcheck ==== | ||
− | + | '''Only MS Windows®'''. This module tries to connect with the specified IP and port. It returns <code>1</code> if successful and <code>0</code> if not. It is also recommended to specify an expiration time with <code>module_timeout</code>. Example: | |
− | |||
− | This module tries to connect with | ||
module_begin | module_begin | ||
module_name tcpcheck | module_name tcpcheck | ||
module_type generic_proc | module_type generic_proc | ||
− | module_tcpcheck www. | + | module_tcpcheck www.pandorafms.com |
module_port 80 | module_port 80 | ||
module_timeout 5 | module_timeout 5 | ||
Line 996: | Line 1,188: | ||
==== module_regexp ==== | ==== module_regexp ==== | ||
− | ( | + | Only for MS Windows®. This module monitors a record file (log) looking for matches using [http://www.regular-expressions.info/reference.html 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''': It returns all the lines matching the regular expression. | |
− | + | * '''generic_data''': It returns the number of lines matching the regular expression. | |
− | * '''generic_data_string''', '''async_string''': | + | * '''generic_proc''': It returns 1 if there is a match and 0 if not. |
− | * '''generic_data''': | + | * '''module_noseekeof''': By default disabled <code>0</code>. With this configuration token active <code>1</code>, in each module execution and regardless of any target file modification, the module will restart its check process without searching for the file's <code>EOF</code> flag. It will always retrieve from the XML all lines that correspond to your search pattern. Example: |
− | * '''generic_proc''': | ||
− | * '''module_noseekeof''': With this configuration token active, | ||
module_begin | module_begin | ||
module_name regexp | module_name regexp | ||
module_type generic_data_string | module_type generic_data_string | ||
− | module_regexp | + | module_regexp %SystemRoot%\my.log |
module_pattern ^\[error\].* | module_pattern ^\[error\].* | ||
module_noseekeof 1 | module_noseekeof 1 | ||
module_end | module_end | ||
− | |||
− | |||
==== module_wmiquery ==== | ==== module_wmiquery ==== | ||
− | + | Only Windows®. The WMI modules allow to locally execute any WMI query without the use of an external tool. It is configured through two parameters: | |
− | |||
− | The WMI modules allow to locally execute any WMI query without the use of an external tool. It | ||
* '''module_wmiquery''': Used WQL query. As a result, several lines could be obtained which will be inserted as several data. | * '''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 | + | * '''module_wmicolumn''': Name of the column which will be used as a data source. |
− | For example, | + | For example, for a list of the installed services: |
module_begin | module_begin | ||
Line 1,045: | Line 1,231: | ||
==== module_perfcounter ==== | ==== module_perfcounter ==== | ||
− | + | {{Tip|Only for MS Windows®.}} | |
− | + | It obtains data from the performance counter ([https://docs.microsoft.com/en-gb/windows/win32/perfctrs/about-performance-counters performance counter]) through the PDH interface. The library <code>pdh.dll</code> 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, usually installed by default. | |
module_begin | module_begin | ||
Line 1,055: | Line 1,241: | ||
module_end | module_end | ||
− | The | + | 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 | + | Performance counters can be seen using the '''Performance''' tool: |
− | + | [[Image:Perfcounter_screen1.png|center|800px]] | |
− | [[ | ||
− | |||
− | 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'': | + | 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'': |
− | + | [[Image:Perfcounter_screen2.png|center|700px]] | |
− | [[ | ||
− | |||
The configuration of the module for this particular check would be as follows: | The configuration of the module for this particular check would be as follows: | ||
Line 1,074: | Line 1,256: | ||
module_name Processor_Time | module_name Processor_Time | ||
module_type generic_data_inc | module_type generic_data_inc | ||
− | module_perfcounter \Procesador(_Total)\% | + | module_perfcounter \Procesador(_Total)\% of processor time |
module_end | module_end | ||
− | By default the raw value of the counter is shown, to get the cooked value add the '''module_cooked 1''' parameter: | + | By default the raw value of the counter is shown, to get the ''cooked'' value add the '''module_cooked 1''' parameter: |
module_begin | module_begin | ||
Line 1,083: | Line 1,265: | ||
module_type generic_data | module_type generic_data | ||
module_cooked 1 | module_cooked 1 | ||
− | module_perfcounter \DiscoFísico(_Total)\E/S | + | module_perfcounter \DiscoFísico(_Total)\E/S divided by secs. |
module_end | module_end | ||
− | Most of the returned data | + | Most of the returned data are just counters, so you should use generic_data_inc as data type. It is 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. |
==== module_inventory DEPRECATED ==== | ==== module_inventory DEPRECATED ==== | ||
− | {{Warning|Currently this | + | {{Warning|Currently this feature has been replaced by [[Pandora:Documentation_en:Inventory#Local_inventory_through_software_agents|inventory from agent plugins]] on both Windows and Linux/Unix® systems.}} |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
==== module_logevent ==== | ==== module_logevent ==== | ||
− | + | Only for MS Windows®. It 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: | The general format of this module is as follows: | ||
Line 1,142: | Line 1,292: | ||
module_end | module_end | ||
− | To avoid showing | + | To avoid showing duplicated information, only those events which occurred since the last time the agent was executed will be considered. |
− | + | <code>module_logevent</code> accepts the following parameters (all of them are [https://en.wikipedia.org/wiki/Case_sensitivity case-sensitive]): | |
− | * '''module_source''': Event source (System, Application, Security). This field is | + | * '''module_source''': Event source (System, Application, Security). This field is mandatory. |
− | * '''module_eventtype''': Event type (failure, information). This is an optional field. | + | * '''module_eventtype''': Event type (failure, information...). This is an optional field. |
− | * '''module_pattern''': Pattern to search (substring). It | + | * '''module_pattern''': Pattern to search (substring). It is an optional field. |
− | * '''module_eventcode''': It | + | * '''module_eventcode''': It is a numeric event ID, e.g. 5112. It is an optional field. |
− | * '''module_application''': Application source of the event. Be careful not to mistake it by | + | * '''module_application''': Application source of the event registered on the log. Be careful not to mistake it by <code>module_source</code> which shows the source name or log file where the events are looked for. |
− | For example, to show all events of an error type system | + | For example, to show all events of an error type system,: |
module_begin | module_begin | ||
Line 1,163: | Line 1,313: | ||
module_end | module_end | ||
− | To show all events | + | To show all events that contain the word <code>PandoraAgent</code>: |
module_begin | module_begin | ||
Line 1,174: | Line 1,324: | ||
module_end | module_end | ||
− | + | Example for filtering the following event: | |
− | + | [[Image:Event sample.png|center|800px]] | |
− | [[Image:Event sample.png|center| | ||
− | |||
module_begin | module_begin | ||
Line 1,192: | Line 1,340: | ||
==== module_logchannel ==== | ==== module_logchannel ==== | ||
− | |||
− | Type of module that allows you to obtain information about | + | {{Tip|Version NG 715 or superior, only for MS Windows®.}} |
+ | |||
+ | Type of module that allows you to obtain information about Windows® log channels. Although <code>module_logevent</code> only has access to Windows® Logs, this type of module allows you to retrieve data from other log files that are configured as channels. That way, it is possible to obtain the logs included in service and application logs. | ||
The general format of this module is as follows: | The general format of this module is as follows: | ||
Line 1,205: | Line 1,354: | ||
module_eventtype <event_type/level> | module_eventtype <event_type/level> | ||
module_eventcode <event_id> | module_eventcode <event_id> | ||
+ | module_application <source> | ||
module_pattern <text substring to match> | module_pattern <text substring to match> | ||
module_description <description> | module_description <description> | ||
module_end | module_end | ||
− | To avoid displaying repeated information, only those events that | + | To avoid displaying repeated information, only those events that took place since the start of the agent are taken into account. |
− | module_logchannel accepts the following parameters (all case-sensitive): | + | <code>module_logchannel</code> accepts the following parameters (all ([https://en.wikipedia.org/wiki/Case_sensitivity case-sensitive]): |
− | * '''module_source''': Event channel. With the command | + | * '''module_source''': Event channel. With the command <code>wevtutil.exe enum-logs</code>, a list of all the local log channels of the machine is obtained. Required field. |
− | * '''module_eventtype''': Event type ( | + | * '''module_eventtype''': Event type (<code>critical</code>, <code>error</code>, <code>warning</code>, <code>info</code> or <code>verbose</code>). Optional field. |
* '''module_pattern''': Pattern to search (substring). Optional field. | * '''module_pattern''': Pattern to search (substring). Optional field. | ||
− | * '''module_eventcode''': Numeric ID of the event | + | * '''module_eventcode''': Numeric ID of the event. Optional field. |
+ | * '''module_application''': Application source of the event. Be careful not to mistake it with <code>module_source</code> which shows the source name or log file where events are looked for. | ||
− | For example, | + | For example, the following module shows all information events of the channel ''Microsoft-Windows-TaskScheduler/Operational'', with code ''201'' and with log text ''code 0'': |
module_begin | module_begin | ||
Line 1,231: | Line 1,382: | ||
module_end | module_end | ||
− | With this module configuration, | + | With this module configuration, Pandora FMS agent would collect the following log: |
− | + | [[Image:Logchannel example.png|center|700px|Click to zoom in]] | |
− | [[Image:Logchannel example.png|center|700px]] | + | |
− | < | + | {{Warning|To get the name of the event channel, right click on it, choose '''Properties''' and copy the parameter '''Full name''', which is the one needed in <code>module_source</code>.}} |
− | < | ||
==== module_plugin ==== | ==== module_plugin ==== | ||
− | + | For agent plugin execution. It is a special case, since '''it does not require any other tag''' like <code>module_begin</code> or <code>module_end</code>, nor will it need the module type. | |
− | + | Syntax with its corresponding parameters: | |
− | module_plugin plugin_filename | + | module_plugin plugin_filename parameter_1 parameter_2 (...) parameter_X |
However, it can be used between the usual module labels to add additional options such as conditions or interval: | However, it can be used between the usual module labels to add additional options such as conditions or interval: | ||
Line 1,264: | Line 1,414: | ||
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df_percent.vbs" | module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df_percent.vbs" | ||
− | ==== module_ping | + | ==== module_ping ==== |
− | + | '''Only for Windows®'''. | |
− | + | module_ping <host> | |
− | + | This module pings the preset host and returns <code>1</code> if it is online. | |
− | * '''module_ping_count x''': Number of | + | Configuration parameters: |
− | * '''module_ping_timeout x''': Timeout in milliseconds to wait for each reply ( | + | |
− | * '''module_advanced_options''': Advanced options for | + | * '''module_ping_count x''': Number of ECHO_REQUEST packages 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 <code>ping.exe</code>. | ||
Example: | Example: | ||
Line 1,288: | Line 1,440: | ||
==== module_snmpget ==== | ==== module_snmpget ==== | ||
− | + | '''Only for MS Windows®.''' | |
− | + | module_snmpget | |
− | + | This module performs an <code>SNMP get</code> query and returns the requested value. The configuration parameters must be specified in the following lines like this: | |
* '''module_snmpversion [1,2c,3]''': SNMP version (1 by default). | * '''module_snmpversion [1,2c,3]''': SNMP version (1 by default). | ||
Line 1,298: | Line 1,450: | ||
* '''module_snmp_agent <host>''': Target SNMP agent. | * '''module_snmp_agent <host>''': Target SNMP agent. | ||
* '''module_snmp_oid <oid>''': Target OID. | * '''module_snmp_oid <oid>''': Target OID. | ||
− | * '''module_advanced_options''': Advanced options for | + | * '''module_advanced_options''': Advanced options for <code>snmpget.exe</code>. |
Example: | Example: | ||
Line 1,313: | Line 1,465: | ||
== Automatic agent configuration == | == Automatic agent configuration == | ||
+ | === Introduction === | ||
− | + | {{Tip|Version NG 725 or superior.}} | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
+ | In the agent configuration process, you may set a series of rules for your agents to be configured automatically. It works like this: | ||
− | + | # '''Prepare automatic configurations''' in your Pandora FMS Console o Pandora FMS Metaconsole. | |
+ | # '''Install the agents''' reporting towards your Pandora FMS (if you have a Metaconsole with the automatic provisioning system configured, set the Metaconsole itself as server). | ||
− | < | + | # '''Pandora FMS Server will receive''' an XML (<code>.data</code>) with the agent's data for the first time. |
− | |||
− | + | # '''Rules will be evaluated''' for determining the automatic configuration to be applied. | |
− | + | # '''The agent will retrieve the new configuration''' and report in the next cycle with the updated configuration. | |
− | |||
− | + | === Creation of an automatic agent configuration === | |
− | |||
− | + | ;Console: Access automatic configuration management through '''Configuration''' -> '''Manage agent autoconfiguration''': | |
+ | [[Image:autoconf_menu_console.png|center|400px]] | ||
− | + | ;Metaconsole: Go to '''Advanced''' -> '''Agent management''' -> agent automatic configuration icon: | |
+ | [[Image:Autoconf1.png|center|800px|Haga clic para ampliar]] | ||
− | Once the new automatic | + | Once you access the management page, you may create new automatic configurations by clicking "Add new configuration definition". You will need to choose a name and description for its automatic configuration. |
+ | [[Image:Autoconf_new.png|center|600px]] | ||
− | + | Once the new automatic configuration is created, you may see the configuration forms by clicking on the section you need: | |
+ | [[Image:Autoconf_options.png|center|200px]] | ||
− | === Rules === | + | ==== Rules ==== |
− | To define the agents to which the automatic configuration will be applied, | + | To define the agents to which the automatic configuration will be applied, first add rules to identify them. |
− | + | Deploy the rules section within your automatic configuration, and select '''Add new rule'''. You may choose a series of options in the rule selector to identify the agents to be configured. | |
− | + | [[Image:autoconf_rules1.png|center|600px]] | |
− | + | ;Server name: Server name match. | |
− | + | ;Group name: Group name match. | |
− | ; Server name: Server name match | + | ;OS: OS name match (uses regular expressions). |
− | ; Group name: Group name match | + | ;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. |
− | ; OS: OS name match (uses regular expressions) | + | ;IP range: Match by IP range (network), use IP/mask notation, for example: |
− | ; 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 | 192.168.1.0/24 | ||
− | ; Script output (> 0): | + | ;Script output (> 0): Conceived to execute a script, whose result will be evaluated as valid as long as the standard output is higher than 0. |
− | + | ;Call to the rule script: It supports the following macros in the 'arguments' field (you may choose between operators <code>AND</code> and <code>OR</code> to modify rule logic): | |
− | |||
− | |||
− | |||
− | |||
− | |||
+ | ** ''' _agent_ :''' It will be replaced by the agent name. | ||
+ | ** ''' _agentalias_ : '''It will be replaced by the agent's alias. | ||
+ | ** '''_address_ :''' It will be replaced by the main IP address, reported by the agent. | ||
+ | ** ''' _agentgroup_ :''' It will be replaced by the group's nname, reported by the agent. | ||
+ | ** ''' _agentos_ :''' It will be replaced by the agent's OS . | ||
− | + | [[Image:autoconf_rules2.png|center|400px]] | |
− | |||
+ | {{Tip|If you do not add any rules, the automatic configuration will not be applied. If you need a single configuration for all agents, you may use the following regular expression to match any ''alias'': <code>.*</code>}} | ||
− | |||
− | |||
− | + | ==== Settings ==== | |
− | |||
− | |||
− | |||
− | === Settings === | ||
From this section we will be able to configure: | From this section we will be able to configure: | ||
− | ; Agent's group: | + | ;Agent's group: You may 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. | + | ;Secondary groups: The groups selected here will be added as secondary groups to the agent. |
− | ; Policies: | + | ;Policies: You may select policies to be applied automatically when the agent reaches the server. |
− | ; Configuration block: | + | ;Configuration block: It adds the extra raw configuration to the agent configuration file. |
− | + | [[Image:autoconf_config.png|center|560px]] | |
− | |||
<b>Note:</b> 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: | <b>Note:</b> 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: | ||
− | + | [[Image:autoconf_ro.png|center|560px]] | |
− | |||
− | |||
− | |||
− | |||
− | + | ==== Extra Actions ==== | |
− | + | From this section you may associate other actions to the auto-configuration, for example: | |
− | |||
− | |||
+ | #Launch custom event | ||
+ | #Launch alert alert action | ||
+ | #Launch script | ||
− | + | [[Image:autoconf_actions.png|center|400px]] | |
− | |||
The system supports the following macros: | The system supports the following macros: | ||
− | ; _agent_ : will be replaced by the agent | + | ; _agent_ : It will be replaced by the agent name. |
− | ; _agentalias_ : will be replaced by the agent | + | ; _agentalias_ : It will be replaced by the agent alias. |
− | ; _address_ : will be replaced by the | + | ; _address_ : It will be replaced by the main IP address, reported by the agent. |
− | ; _agentgroup_ : will be replaced by the group | + | ; _agentgroup_ : It will be replaced by the group name, reported by the agent. |
− | ; _agentos_ : will be replaced by the agent's OS | + | ; _agentos_ : It will be replaced by the agent's OS. |
− | ; _agentid_ : will be replaced by the agent's ID | + | ; _agentid_ : It will be replaced by the agent's ID. |
== UNIX / Linux Agents == | == UNIX / Linux Agents == | ||
Line 1,437: | Line 1,568: | ||
=== Pandora FMS UNIX Agents Configuration === | === Pandora FMS UNIX Agents Configuration === | ||
− | The fundamental | + | The fundamental paths and directories to consider are: |
− | * | + | * <code>/usr/share/pandora_agent</code>: Where Pandora FMS agent is installed. In systems where this is not possible for reasons like a strict system policy, we recommend creating a link to this path from the real installation path, e.g. <code>/opt/pandora</code> -> <code>/usr/share/pandora_agent</code>. |
− | * | + | * <code>/etc/pandora/pandora_agent.conf</code>: Main agent configuration file. Local execution modules ans agent plugins are configured here. |
− | * | + | * * <code>/usr/local/bin/pandora_agent</code>: Agent executable binary. It usually has a link to <code>/usr/bin/pandora_agent</code>. |
− | * | + | * <code>/usr/local/bin/tentacle_client</code>: Tentacle executable binary, for file transfer to the server. It ususlly has a link to <code>/usr/bin/tentacle_client</code>. |
− | * | + | * <code>/etc/init.d/pandora_agent_daemon</code>: Start/stop/restar script. '''In AIX systems, the daemon is''' <code>/etc/rc.pandora_agent_daemon</code>. |
− | * | + | * <code>/var/log/pandora/pandora_agent.log</code>: Text file where the activity of Pandora FMS agent is kept if the agent is executed in depuration mode. |
− | * | + | * <code>/etc/pandora/plugins</code>: Directory that keeps the agent's plugins. It is linked to <code>/usr/share/pandora_agent/plugins</code>. |
− | * | + | * <code>/etc/pandora/collections</code>: Directory containing the collections of the agent. It is linked to the directory <code>/usr/share/pandora_agent/collections</code>. |
=== Initial Execution of a UNIX Agent === | === Initial Execution of a UNIX Agent === | ||
Line 1,469: | Line 1,600: | ||
=== Altering the way UNIX Agents obtain system information === | === 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: | + | As we saw in the configuration section, there are some modules that obtain the [[Pandora:Documentation_en:Configuration_Agents#Specific_guidelines_to_obtain_information|information in a predefined way]] without having to specify a command with <code>module_exec</code>. These modules are: |
* module_procmem | * module_procmem | ||
Line 1,481: | Line 1,612: | ||
* module_freepercentmemory | * module_freepercentmemory | ||
− | It is possible to modify the operation of these modules by directly editing the agent executable ( | + | It is possible to modify the operation of these modules by directly editing the agent executable (<code>/usr/bin/pandora_agent</code> by default). Pandora FMS agent is generally located in <code>/usr/bin/pandora_agent</code>. |
+ | |||
+ | Search for the <code>Commands to retrieve</code> string that contains the code with the internal commands. You may make the modifications you need to adapt them to your system. | ||
# Commands to retrieve total memory information in kB | # Commands to retrieve total memory information in kB | ||
Line 1,501: | Line 1,634: | ||
To change any of the predefined values to get the information, just edit the command but be careful with the following: | To change any of the predefined values to get the information, just edit the command but be careful with the following: | ||
− | # Check that | + | # Check that blocks <code>{ };</code> always end in semi-colon. |
− | # Check that commands are between ' ' symbols. | + | # Check that commands are between <code>' '</code> symbols. |
− | # Check that any | + | # In turn, within said simple quotation marks, you may need additional ones, like <code>` `</code> (see the previous example). |
+ | # Check that any simple quotation mark that you may want to use in the command is preceded by <code>\</code>, that means <code>\'</code>. For instance, this command that usually would be: | ||
df -P | awk 'NR > 1 {print $2, $4, $6}' | df -P | awk 'NR > 1 {print $2, $4, $6}' | ||
Line 1,515: | Line 1,649: | ||
=== Configuration of Pandora FMS Windows Agent === | === 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 | + | The fundamental paths and directories in the Windows agent installation will be found in the directory where the agent is installed, by default <code>%ProgramFiles%</code>. |
+ | |||
+ | [[Image:ProgramFiles-pandora_agent.PNG|center|500px]] | ||
+ | |||
+ | The most important ones to keep in mind are: | ||
+ | |||
+ | ;<code>%ProgramFiles%\pandora_agent</code>: Where Pandora FMS agent, its executable and its directories are installed. | ||
− | + | ;<code>%ProgramFiles%\pandora_agent\pandora_agent.conf</code>: Agent configuration main file. Local execution modules and agent plugins are configured here. | |
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | |||
− | + | ;<code>%ProgramFiles%\pandora_agent\PandoraAgent.exe</code>: Executable agent binary. | |
− | |||
− | {{Tip| | + | ;<code>%ProgramFiles%\pandora_agent\util\tentacle_client.exe</code>: Tentacle executable binary for transferring files to the server. |
+ | |||
+ | ;<code>%ProgramFiles%\pandora_agent\scripts</code>: Pandora FMS agent start/stop/restart scripts. | ||
+ | |||
+ | ;<code>%ProgramFiles%\pandora_agent\pandora_agent.log</code>: Text file where Pandora FMS agent activity is saved, when the agent is executed in debug mode. | ||
+ | |||
+ | ;<code>%ProgramFiles%\pandora_agent\util</code>: Directory containing the agent plugins. | ||
+ | |||
+ | ;<code>%ProgramFiles%\pandora_agent\collections</code>: Directory containing the agent's collections. | ||
+ | |||
+ | == Software agent automatic deployment == | ||
+ | |||
+ | You may deploy software agents by using the '''deployment central''' through the Discovery system, more information in [https://pandorafms.com/docs/index.php?title=Pandora:Documentation_en:Discovery#Automatic_agent_deployment this link].<br><br><br> | ||
+ | |||
+ | == Auto-updating Software Agents == | ||
+ | |||
+ | Using file collections and <code>pandora_update</code> tool you may provide a way to "auto-update" software agents. | ||
+ | |||
+ | {{Tip|<code>pandora_update</code> tool requires Perl's <code>Digest::MD5</code> module to work. It is included by default from Perl 5.14, but for earlier versions it has to be manually installed.}} | ||
It works the following way: | It works the following way: | ||
− | 1. Agents receive new binaries | + | 1. Agents receive new binaries in the file collection's incoming directory. |
− | + | Windows® example: | |
c:\program files\pandora_agent\collections\fc_1\PandoraAgent.exe | c:\program files\pandora_agent\collections\fc_1\PandoraAgent.exe | ||
− | + | Linux® example: | |
/etc/pandora/collections/fc_1/pandora_agent | /etc/pandora/collections/fc_1/pandora_agent | ||
− | 2. The agent runs | + | 2. The agent runs <code>pandora_update</code> plugin. This plugin receives a single parameter: the short name of the collection (in this example, <code>fc_1</code>). 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, <code>pandora_update</code> 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 | + | 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 <code>PandoraAgent.exe</code> binary in each one of them. |
− | 3. Pandora_update also writes the updated event | + | 3. <code>Pandora_update</code> also writes the updated event into a small log, to be able to recover in the next execution and warn the user (by using an <code>async_string</code>) about the agent update process. |
This means that the used modules could be configured to have a high interval to perform the update process. | This means that the used modules could be configured to have a high interval to perform the update process. | ||
Line 1,571: | Line 1,721: | ||
module_end | module_end | ||
− | + | {{Tip|The <code>pandora_update</code> supports as second parameter Pandora FMS installation directory path, you do not need to specify it if installation was performed in the default path.}} | |
− | ''' | + | '''Windows®''' |
module_begin | module_begin | ||
Line 1,630: | Line 1,780: | ||
The data entered in the module the first time an XML is received is as follows: | The data entered in the module the first time an XML is received is as follows: | ||
− | |||
− | |||
* Name. | * Name. |
Latest revision as of 12:13, 30 March 2021
Go back to Pandora FMS documentation index
Contents
- 1 Pandora FMS Software Agents
- 1.1 What is a software Agent?
- 1.2 Introduction to the Agent Configuration
- 1.3 General Agent Parameters
- 1.3.1 server_ip
- 1.3.2 server_path
- 1.3.3 temporal
- 1.3.4 description
- 1.3.5 group
- 1.3.6 temporal_min_size
- 1.3.7 logfile
- 1.3.8 interval
- 1.3.9 disable_logfile
- 1.3.10 debug
- 1.3.11 agent_name
- 1.3.12 agent_name_cmd
- 1.3.13 agent_alias_cmd
- 1.3.14 address
- 1.3.15 encoding
- 1.3.16 server_port
- 1.3.17 transfer_mode
- 1.3.18 transfer_timeout
- 1.3.19 server_pwd
- 1.3.20 server_ssl
- 1.3.21 server_opts
- 1.3.22 delayed_startup
- 1.3.23 startup_delay
- 1.3.24 pandora_nice
- 1.3.25 autotime
- 1.3.26 cron_mode
- 1.3.27 remote_config
- 1.3.28 xml_buffer
- 1.3.29 timezone_offset
- 1.3.30 parent_agent_name
- 1.3.31 agent_threads
- 1.3.32 include
- 1.3.33 broker_agent
- 1.3.34 pandora_user
- 1.3.35 custom_id
- 1.3.36 url_address
- 1.3.37 custom_fieldX_name
- 1.3.38 custom_fieldX_value
- 1.3.39 macro
- 1.3.40 group_password <password>
- 1.3.41 ehorus_conf
- 1.3.42 transfer_mode_user
- 1.3.43 secondary_groups
- 1.3.44 standby
- 1.4 Secondary Server
- 1.5 UDP Server
- 1.6 Modules definition
- 1.6.1 Common elements of all modules
- 1.6.1.1 module_begin
- 1.6.1.2 module_name
- 1.6.1.3 module_type
- 1.6.1.4 module_min <value>
- 1.6.1.5 module_max <value>
- 1.6.1.6 module_min_warning
- 1.6.1.7 module_max_warning
- 1.6.1.8 module_min_critical
- 1.6.1.9 module_max_critical
- 1.6.1.10 module_disabled
- 1.6.1.11 module_min_ff_event
- 1.6.1.12 module_each_ff
- 1.6.1.13 module_min_ff_event_normal
- 1.6.1.14 module_min_ff_event_warning
- 1.6.1.15 module_min_ff_event_critical
- 1.6.1.16 module_ff_timeout
- 1.6.1.17 module_ff_type
- 1.6.1.18 module_description
- 1.6.1.19 module_interval
- 1.6.1.20 module_timeout
- 1.6.1.21 module_postprocess
- 1.6.1.22 module_save
- 1.6.1.23 module_crontab
- 1.6.1.24 module_condition
- 1.6.1.25 module_precondition
- 1.6.1.26 module_unit
- 1.6.1.27 module_group
- 1.6.1.28 module_custom_id
- 1.6.1.29 module_str_warning
- 1.6.1.30 module_str_critical
- 1.6.1.31 module_warning_instructions
- 1.6.1.32 module_critical_instructions
- 1.6.1.33 module_unknown_instructions
- 1.6.1.34 module_tags
- 1.6.1.35 module_warning_inverse
- 1.6.1.36 module_critical_inverse
- 1.6.1.37 module_native_encoding
- 1.6.1.38 module_quiet
- 1.6.1.39 module_ff_interval
- 1.6.1.40 module_macro
- 1.6.1.41 module_alert_template
- 1.6.1.42 module_end
- 1.6.2 Specific guidelines to obtain information
- 1.6.2.1 module_exec
- 1.6.2.2 module_service
- 1.6.2.3 module_proc
- 1.6.2.4 module_cpuproc
- 1.6.2.5 module_memproc
- 1.6.2.6 module_freedisk
- 1.6.2.7 module_freepercentdisk
- 1.6.2.8 module_occupiedpercentdisk
- 1.6.2.9 module_cpuusage
- 1.6.2.10 module_freememory
- 1.6.2.11 module_freepercentmemory
- 1.6.2.12 module_tcpcheck
- 1.6.2.13 module_regexp
- 1.6.2.14 module_wmiquery
- 1.6.2.15 module_perfcounter
- 1.6.2.16 module_inventory DEPRECATED
- 1.6.2.17 module_logevent
- 1.6.2.18 module_logchannel
- 1.6.2.19 module_plugin
- 1.6.2.20 module_ping
- 1.6.2.21 module_snmpget
- 1.6.1 Common elements of all modules
- 1.7 Automatic agent configuration
- 1.8 UNIX / Linux Agents
- 1.9 Pandora FMS Windows Agents
- 1.10 Software agent automatic deployment
- 1.11 Auto-updating Software Agents
- 1.12 Agent / Module Autocreation from XML File / Learning Mode
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 (default value) %ProgramFiles%\pandora_agent
on Windows systems, and /etc
on GNU/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 MS Windows® y GNU/Linux® systems.
The agent configuration file encoding is UTF-8 on both GNU/Linux® and MS Windows® systems. If you edit this file manually, check 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. |
|
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: |
|
You may find more information about Pandora FMS XML file format here. You may also access test data generation (capacity analysis tools).
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 log 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 MS 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 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 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
Port where Pandora FMS Tentacle server listens to receive data files,41121
by default.
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 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
Server password for authentication: specific for Windows® FTP and for the Tentacle transfer mode, although the password for the latter is optional.
1.3.20 server_ssl
It specifies the Tentacle transfer mode. Allows to enable (1
) or disable (1
) SSL network encryption. Learn more about Tentacle safe communication in this section.
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 send data through a proxy located at 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
Get more information about safe Tentacle communication in this section.
1.3.22 delayed_startup
Disabled by default. Waiting time (seconds or minutes) until the agent starts running once started. For all Software Agents except for MS Windows®.
1.3.23 startup_delay
Disabled by default. Waiting time, in seconds, until the agent starts running once started. For MS Windows® only.
1.3.24 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.25 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, ignoring 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.26 cron_mode
With this parameter, it is 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 is deactivated (0
) by default.
1.3.27 remote_config
It enables (1
) or disables (0
) remote agent configuration. Operation is only allowed with Tentacle transfer mode.
1.3.28 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.29 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.30 parent_agent_name
Indicates the parent of the software agent. It must be the name of an existing agent in Pandora FMS.
1.3.31 agent_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.32 include
include <file>
It allows to include an additional configuration file. This file can contain additional modules and collections alongside the ones found in the main configuration file. This token is optional. The file can be uploaded by those users with (AW
) Agent writing permissions.
1.3.33 broker_agent
broker_agent <broker_name>
It enables broker agent feature. To activate it, you only need to uncomment the parameter and indicate the name (<broker_name>
) that will be assigned to the broker agent.
1.3.34 pandora_user
pandora_user <user>
This parameter is optional and allows the agent to be executed with a specified system user(<user>
. This user must have permissions to execute the agent and all associated resources.
1.3.35 custom_id
Custom ID of the agent for external applications.
1.3.36 url_address
Custom URL to open it from the agent in the console.
1.3.37 custom_fieldX_name
Name of an agent custom field which already exists on the system. If does not exist, it will be ignored. Example:
custom_field1_name Model
1.3.38 custom_fieldX_value
Value for the custom_fieldX_name in the previous parameter. Example:
custom_field1_value C1700
1.3.39 macro
macro<macro> <value>
It defines a local execution macro that can be used in the definition of a module. These macros are used in the Metaconsole 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.
Local execution macros start by _fieldx_
.
Example:
module_begin module_name Particion_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.40 group_password <password>
Password for the agent group. Leave it commented if the group is not password-protected.
1.3.41 ehorus_conf
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.42 transfer_mode_user
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.43 secondary_groups
secondary_groups <group name1>, <group name2>, ... <group nameN>
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.44 standby
standby <1|0>
If an agent is in 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 feature 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
Bear in mind that UDP is unsafe by nature (but efficient to send messages without compromising a true response). |
|
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 following options in its configuration file pandora_agent.conf
:
- udp_server: To activate the UDP server, set it to
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.
Although it can be set to 0.0.0.0 for accepting from all sources, said practice is not recommended. If you have several Pandora FMS servers and/or use IPv6, you may add different IP adresses separated by commas. For instance, if you have in IPv6: |
|
- 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 <service name>
- Starting or stopping a service (service name).
<START|STOP> PROCESS <process name>
- Starting or stopping a process (process name).
REFRESH AGENT <agent name>
- Forces one execution of the agent (agent name) and refreshes data.
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
. The general syntax is the following:
module_begin module_name <Module Name> module_type generic_data module_exec <local command to execute> module_end
Where module name is the name of the module and local command the command to be executed. There are multiple additional options for modules, in this example only common and mandatory lines have been used for most of the cases.
Learn more in our video tutorials:
The following sections explain each one of them in detail.
1.6.1 Common elements of all modules
Module fields (except for 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
Tag at the beginning of the module. It is mandatory.
1.6.1.2 module_name
module_name <name>
Name of the module (mandatory). This name must be unique within the agent.
1.6.1.3 module_type
module_type <type>
Type of data the module will return. It is mandatory 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
): It 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>
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>
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
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
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
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
module_max_critical <value>
This is the maximum value of the critical
status threshold.
1.6.1.10 module_disabled
module_disabled <0|1>
It indicates whether the module is enabled (0
) or disabled (1
).
1.6.1.11 module_min_ff_event
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 module_each_ff
module_each_ff <0|1>
If enabled (1
), flip flop thresholds per status will be used instead of module_min_ff_event
:
-
module_min_ff_event_normal
. -
module_min_ff_event_warning
. -
module_min_ff_event_critical
.
1.6.1.13 module_min_ff_event_normal
module_min_ff_event_normal <value>
Flip flop protection value for switching to normal
status.
1.6.1.14 module_min_ff_event_warning
module_min_ff_event_warning <value>
Flip flop protection value for switching to warning
status.
1.6.1.15 module_min_ff_event_critical
module_min_ff_event_critical <value>
Flip flop protection value for switching to critical
status.
1.6.1.16 module_ff_timeout
module_ff_timeout <seconds>
It resets the flip flop threshold counter after the given number of seconds. This implies that the number of status changes set in module_min_ff_event
must take place at an interval of module_ff_timeout
seconds before the state changes in the console's visual level.
1.6.1.17 module_ff_type
module_ff_type <value>
This is a Flip Flop advanced option 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 Keep counters
is enabled (1
) or disabled (0
).
1.6.1.18 module_description
module_description <text>
Free text with information about the module.
1.6.1.19 module_interval
module_interval <factor>
This interval is calculated as a multiplier for the agent interval. If the agent has e.g. the agent's interval is 300 (5 minutes) but you wish for a module to be processed only every 15 minutes, add this line:
module_interval 3
That way the module will be processed every 300 seconds x 3 = 900 seconds (15 minutes).
In order for the |
|
1.6.1.20 module_timeout
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
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
module_save <var name>
It stores the value returned by the module in a variable with the name indicated in this parameter (<var name>
). This value can be used later in other modules.
Example in Unix/Linux::
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
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 is 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, the following configuration should be used:
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
module_condition <operation> <command>
It is possible to define actions that will be executed by the agent according to the value returned by the module. Only available for numerical values. The syntax is the following:
- > [value]: It executes the command if the module value is higher than the given one.
- < [valor]: It executes the command if the module value is lower than the given one.
- = [valor]: It executes the command if the module value is equal to the given one.
- != [valor]: It executes the command if the module value is different to the given one.
- =~ [regular expression]: It executes the command if the module value coincides with the given regular expression.
- (valor, valor): It 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 Service_Spooler module_type generic_proc module_service Spooler module_condition = 0 net start Spooler module_end
- NOTE: On Windows platforms, it is 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
module_precondition <operation> <command>
It allows to determin whether a module is executed or not depending on the result of a given execution. Syntax:
- > [value]: It executes the command if the module value is higher than the given one.
- < [value]: It executes the command if the module value is lower than the given one.
- = [value]: It executes the command if the module value is equal to the given one.
- != [value]: It executes the command if the module value is different to the given one.
- =~ [regular expression]: It executes the command if the module value coincides with the given regular expression.
- (value, value): It 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 will only 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 is 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 module_unit
module_unit <string>
Units shown as a text string next to the value obtained by the module. Example:
module_unit %
1.6.1.27 module_group
module_group <value>
It allows to indicate the module group (value) the module will be assigned to. Example:
module_group Networking
1.6.1.28 module_custom_id
module_custom_id <value>
This is a custom identifier for the module. Example:
module_custom_id host101
1.6.1.29 module_str_warning
module_str_warning <value>
This is a regular expression to define the warning
threshold in alphanumeric modules (string). Example:
module_str_warning .*NOTICE.*
1.6.1.30 module_str_critical
module_str_critical <value>
This is a regular expression to define the critical
status threshold in the string modules. Example:
module_str_critical .*ERROR.*
1.6.1.31 module_warning_instructions
module_warning_instructions <value>
These are the instructions shown in the module-generated event when going into warning
status.
Example to show the message indicating an issue getting higher priority:
module_warning_instructions Raise advocacy priority
1.6.1.32 module_critical_instructions
module_critical_instructions <value>
These are the instructions shown in de module-generated event when going into critical
status.
Example of a message to alert the system department:
module_critical_instructions Call to sys department
1.6.1.33 module_unknown_instructions
module_unknown_instructions <value>
These are the instructions shown in the module-generated event when going into unknown
status.
Example of message to open issue:
module_unknown_instructions Open incident
1.6.1.34 module_tags
module_tags <value>
Tags to be assigned to the module separated by commas.
Example:
module_tags tag1,tag2,tag3
1.6.1.35 module_warning_inverse
module_warning_inverse <value>
It allows activating (1
) the inverse interval for the warning
threshold.
Example:
module_warning_inverse 1
1.6.1.36 module_critical_inverse
module_critical_inverse <value>
It allows activating (1
) the inverse interval for the critical
threshold.
Example:
module_critical_inverse 1
1.6.1.37 module_native_encoding
module_native_encoding <value>
This configuration token only affects executed modules by command line, that is, there is a module_exec
in the module configuration.
MS 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 accents. With this token, the Pandora FMS agent transforms the output to the encoding specified in the configuration file.
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 module_quiet
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 module_ff_interval
module_ff_interval <value>
This is the Flip Flop execution threshold of the module (in seconds). For instance:
module_ff_interval 2
1.6.1.40 module_macro
module_macro<macro> <value>
It only applies to local components from the console. It is not useful in the configuration file.
1.6.1.41 module_alert_template
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. It is mandatory.
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 as such. Only one type can be used in each module.
1.6.2.1 module_exec
module_exec <command>
General command execution line. The desired run must be specified to obtain the information in a single line.
On GNU/Linux, the command will be executed using the default command prompt. The default interpreter will be determined by the symbolic link /bin/sh
. Usually the link points to bash, but in systems like Ubuntu this is not the case (in this case it points to dash). Therefore, it could happen that a command is tested in the terminal and then there is an error when the agent executes it. A solution that will work in most cases will be forcing 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
module_service <service>
It checks whther a specific service is being executed on the machine.
1.6.2.2.1 In MS Windows
Remember to use the " "
characters if the name of the service contains blank spaces.
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
), as it appears in the Windows services manager.
Asynchronous Mode
Pandora FMS usually executes a test battery (each of them defined by a module) every N seconds (300 sec. = 5 min. by default). If a service is down just after a Pandora FMS execution, it will take 300 additional seconds to find out the service that went down. The difference on asynchronous mode is that modules notify Pandora FMS right away about the fail or shutdown of this service. This is called asynchronous operation mode. It would be enough 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®, this asynchronous feature is not supported and, only in those versions, Pandora FMS agent makes a periodic query to find out whether 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 does not 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
1.6.2.2.2 In Unix
In Unix, it works the same as in MS Windows®, the only difference is that for Unix, process and service are the same concepts, 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
module_proc <process>
It checks whether a specific process name is working in this machine.
1.6.2.3.1 In MS Windows
Quotation marks are not needed for the process name. Bear in mind that the name of the process must have the |
|
This is an example of the monitoring of the cmd.exe
process:
module_begin module_name CMDProcess module_type generic_proc module_proc cmd.exe module_description Process Command line module_end
Asynchronous mode
In a similar way to the services, monitoring processes can be critical in some cases. The Windows® software agent supports asynchronous checking for the module_proc
parameter. 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. That way, you may get informed about failed of critical processes right away. This is an example of process asynchronous monitoring:
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 module_async yes
configuration token. 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 activating the process that went down. Pandora FMS Windows® Agent could work 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 activate 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 will 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 controls in which session you want the process to be launched. If set to
no
, the process will start in the service session and therefore remain in the background (default setting). Otherwise, if set toyes
, 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 (Allow service to interact with desktop):
|
|
Pandora FMS is executed under the |
|
1.6.2.3.2 In Unix
Under UNIX, this module works just like module_service. It does not support asynchronous and/or watchdog mode.
1.6.2.4 module_cpuproc
module_cpuproc <process>
It returns the CPU usage of a specific process. Example:
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
module_memproc <process>
Only for Unix. It 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
module_freedisk <disk_letter:>|<vol>
It checks for the free space in the disk unit.
- In Windows
- Place
:
after the<disk_letter:>
.
module_begin module_name freedisk module_type generic_data module_freedisk C: module_end
- In Unix
- The volume to test, such as
/var
.
module_begin module_name disk_var module_type generic_data module_freedisk /var module_end
1.6.2.7 module_freepercentdisk
module_freepercentdisk <disk_letter:>|<vol>
This module returns the free disk percentage under a logic unit.
- In Windows
- Type
:
after<disk_letter:>
.
module_begin module_name freepercentdisk module_type generic_data module_freepercentdisk C: module_end
- In Unix
- The volume to check, such as
/var
.
module_begin module_name disk_var module_type generic_data module_freepercentdisk /var module_end
1.6.2.8 module_occupiedpercentdisk
module_occupiedpercentdisk <vol>
Only for Unix. This module returns the occupied disk percentage, for instance:
module_begin module_name disk_var module_type generic_data module_occupiedpercentdisk /var module_end
1.6.2.9 module_cpuusage
module_cpuusage [<cpu id>|all]
It returns the CPU usage in a CPU number. If there is only one CPU, please leave it blank or use all
. For Windows® and Unix.
It is also possible to obtain the average use of all CPUs in multiprocessor systems this way:
module_begin module_name CPU_use module_type generic_data module_cpuusage all module_description CPU average use module_end
To check the CPU usage in CPU #1:
module_begin module_name CPU_1 module_type generic_data module_cpuusage 1 module_description CPU #1 average use 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
Only MS Windows®. This module tries to connect with the specified IP and port. It returns 1
if successful and 0
if not. It is also recommended to specify an expiration time with module_timeout
. Example:
module_begin module_name tcpcheck module_type generic_proc module_tcpcheck www.pandorafms.com module_port 80 module_timeout 5 module_end
1.6.2.13 module_regexp
Only for MS Windows®. This module monitors a record file (log) looking for matches 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: It returns all the lines matching the regular expression.
- generic_data: It returns the number of lines matching the regular expression.
- generic_proc: It returns 1 if there is a match and 0 if not.
- module_noseekeof: By default disabled
0
. With this configuration token active1
, in each module execution and regardless of any target file modification, the module will restart its check process without searching for the file'sEOF
flag. It will always retrieve from the XML all lines that correspond to your search pattern. Example:
module_begin module_name regexp module_type generic_data_string module_regexp %SystemRoot%\my.log module_pattern ^\[error\].* module_noseekeof 1 module_end
1.6.2.14 module_wmiquery
Only Windows®. The WMI modules allow to locally execute any WMI query without the use of an external tool. It is 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 will be used as a data source.
For example, for 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
It obtains data from the performance counter (performance counter) through the PDH interface. The library pdh.dll
should be installed in the system. PDH.DLL is a Windows library. If you have not installed it yet, you have to install the Windows® performance analysis tool, 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 seen 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)\% of processor time 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 divided by secs. module_end
Most of the returned data are just counters, so you should use generic_data_inc as data type. It is 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 feature has been replaced by inventory from agent plugins on both Windows and Linux/Unix® systems. |
|
1.6.2.17 module_logevent
Only for MS Windows®. It 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 duplicated 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 mandatory.
- module_eventtype: Event type (failure, information...). This is an optional field.
- module_pattern: Pattern to search (substring). It is an optional field.
- module_eventcode: It is a numeric event ID, e.g. 5112. It is an optional field.
- module_application: Application source of the event registered on the log. Be careful not to mistake it by
module_source
which shows the source name or log file where the events are looked for.
For example, to show all events of an error type system,:
module_begin module_name log_events module_type generic_data_string module_description System errors module_logevent module_source System module_eventtype error module_end
To show all events that 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
Example for filtering the following event:
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
Type of module that allows you to obtain information about Windows® log channels. Although module_logevent
only has access to Windows® Logs, this type of module allows you to retrieve data from other log files that are configured as channels. That way, it is possible to obtain the logs included in service 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 took place 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
orverbose
). Optional field. - module_pattern: Pattern to search (substring). Optional field.
- module_eventcode: Numeric ID of the event. Optional field.
- module_application: Application source of the event. Be careful not to mistake it with
module_source
which shows the source name or log file where events are looked for.
For example, the following module shows all information events of the channel Microsoft-Windows-TaskScheduler/Operational, 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, Pandora FMS agent would collect the following log:
To get the name of the event channel, right click on it, choose Properties and copy the parameter Full name, which is the one needed in |
|
1.6.2.19 module_plugin
For agent plugin execution. It is a special case, since it does not require any other tag like module_begin
or module_end
, nor will it need the module type.
Syntax with its corresponding parameters:
module_plugin plugin_filename parameter_1 parameter_2 (...) parameter_X
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
Only for Windows®.
module_ping <host>
This module pings the preset host and returns 1
if it is online.
Configuration parameters:
- module_ping_count x: Number of ECHO_REQUEST packages 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
Only for MS Windows®.
module_snmpget
This module performs an SNMP get
query and returns the requested value. The configuration parameters must be specified in the following lines like this:
- 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
In the agent configuration process, you may set a series of rules for your agents to be configured automatically. It works like this:
- Prepare automatic configurations in your Pandora FMS Console o Pandora FMS Metaconsole.
- Install the agents reporting towards your Pandora FMS (if you have a Metaconsole with the automatic provisioning system configured, set the Metaconsole itself as server).
- Pandora FMS Server will receive an XML (
.data
) with the agent's data for the first time.
- Rules will be evaluated for determining the automatic configuration to be applied.
- The agent will retrieve the new configuration and report in the next cycle with the updated configuration.
1.7.2 Creation of an automatic agent configuration
- Console
- Access automatic configuration management through Configuration -> Manage agent autoconfiguration:
- Metaconsole
- Go to Advanced -> Agent management -> agent automatic configuration icon:
Once you access the management page, you may create new automatic configurations by clicking "Add new configuration definition". You will need to choose a name and description for its automatic configuration.
Once the new automatic configuration is created, you may see 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, first add rules to identify them.
Deploy the rules section within your automatic configuration, and select Add new rule. You may choose a series of options in the rule 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)
- Conceived to execute a script, whose result will be evaluated as valid as long as the standard output is higher than 0.
- Call to the rule script
- It supports the following macros in the 'arguments' field (you may choose between operators
AND
andOR
to modify rule logic):
- _agent_ : It will be replaced by the agent name.
- _agentalias_ : It will be replaced by the agent's alias.
- _address_ : It will be replaced by the main IP address, reported by the agent.
- _agentgroup_ : It will be replaced by the group's nname, reported by the agent.
- _agentos_ : It will be replaced by the agent's OS .
If you do not add any rules, the automatic configuration will not be applied. If you need a single configuration for all agents, you may 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
- You may 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
- You may select policies to be applied automatically when the agent reaches the server.
- Configuration block
- It 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 may associate other actions to the auto-configuration, for example:
- Launch custom event
- Launch alert alert action
- Launch script
The system supports the following macros:
- _agent_
- It will be replaced by the agent name.
- _agentalias_
- It will be replaced by the agent alias.
- _address_
- It will be replaced by the main IP address, reported by the agent.
- _agentgroup_
- It will be replaced by the group name, reported by the agent.
- _agentos_
- It will be replaced by the agent's OS.
- _agentid_
- It will be replaced by the agent's ID.
1.8 UNIX / Linux Agents
1.8.1 Pandora FMS UNIX Agents Configuration
The fundamental paths and directories to consider are:
-
/usr/share/pandora_agent
: Where Pandora FMS agent is installed. In systems where this is not 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 file. Local execution modules ans agent plugins are configured here.
- *
/usr/local/bin/pandora_agent
: Agent executable binary. It usually has a link to/usr/bin/pandora_agent
.
-
/usr/local/bin/tentacle_client
: Tentacle executable binary, for file transfer to the server. It ususlly has a link to/usr/bin/tentacle_client
.
-
/etc/init.d/pandora_agent_daemon
: Start/stop/restar script. In AIX systems, the daemon is/etc/rc.pandora_agent_daemon
.
-
/var/log/pandora/pandora_agent.log
: Text file where the activity of Pandora FMS agent is kept if the agent is executed in depuration mode.
-
/etc/pandora/plugins
: Directory that keeps the agent's plugins. It is linked 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). Pandora FMS agent is generally located in /usr/bin/pandora_agent
.
Search for the Commands to retrieve
string that contains the code with the internal commands. You may make the modifications you need to adapt them to your 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:
- Check that blocks
{ };
always end in semi-colon. - Check that commands are between
' '
symbols. - In turn, within said simple quotation marks, you may need additional ones, like
` `
(see the previous example). - Check that any simple quotation mark that you may want to use in the command is preceded by
\
, that means\'
. For instance, this command that usually would be:
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 %ProgramFiles%
.
The most important ones to keep in mind are:
%ProgramFiles%\pandora_agent
- Where Pandora FMS agent, its executable and its directories are installed.
%ProgramFiles%\pandora_agent\pandora_agent.conf
- Agent configuration main file. Local execution modules and agent plugins are configured here.
%ProgramFiles%\pandora_agent\PandoraAgent.exe
- Executable agent binary.
%ProgramFiles%\pandora_agent\util\tentacle_client.exe
- Tentacle executable binary for transferring files to the server.
%ProgramFiles%\pandora_agent\scripts
- Pandora FMS agent start/stop/restart scripts.
%ProgramFiles%\pandora_agent\pandora_agent.log
- Text file where Pandora FMS agent activity is saved, when the agent is executed in debug mode.
%ProgramFiles%\pandora_agent\util
- Directory containing the agent plugins.
%ProgramFiles%\pandora_agent\collections
- Directory containing the agent's collections.
1.10 Software agent automatic deployment
You may deploy software agents by using the deployment central through the Discovery system, more information in this link.
1.11 Auto-updating Software Agents
Using file collections and pandora_update
tool you may provide a way to "auto-update" software agents.
|
|
It works the following way:
1. Agents receive new binaries 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 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 into a small log, to be able to recover in the next execution and warn the user (by using an async_string
) 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
The |
|
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.12 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.12.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.12.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.12.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:
- 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.12.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.