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

From Pandora FMS Wiki
Jump to: navigation, search
(Monitoring inaccessible networks remotely: Typo.)
 
(159 intermediate revisions by 12 users not shown)
Line 1: Line 1:
[[Pandora:Documentation_en|Go back Pandora FMS 3.0 documentation index]]
+
[[Pandora:Documentation_en|Go back to Pandora FMS documentation index]]
 +
 
  
 
= Monitoring with Software Agents =
 
= Monitoring with Software Agents =
  
== Agent Configuration ==
+
==Monitoring with software agents==
  
Pandora FMS agents have a local configuration by default, so their maintenance is managed from the monitored machine which edits their configuration file.
+
[[Image:Agent-monitoring.png|400px|center]]
  
=== Remote Configuration ===
+
Software agents are in execution in OS where they get information from. '''Each of the checks''' performed on the system, such as CPU usage, free memory or disk space correspond to a '''module'''. So for each module a single data is collected in each execution.
  
On the Enterprise version, there is a remote Agent Configuration feature which allows centralized configuration and file management from the server console.
+
the software agent's own ''directives'' are useful to retrieve certain data directly from the operating system (e.g. CPU usage, memory, events, etc.), executing the '''operating system's own commands''' following instructions from predefined ''scripts''. It is also possible to execute those commands directly as well as any other software as long as data are returned in a standard way.
  
The configuration consists of two files. Their file names are <md5>.conf and <md5>.md5, where <md5> is the agent's name hash code. Those files are stored in '/var/spool/pandora/data_in/conf' and '/var/spool/pandora/data_in/md5' folders.
+
Pandora FMS Dataserver processes and stores in the database all the information generated by software agents, whcih send their data through and XML file.
  
Those files are composed of plain text and can be edited from the console, which regenerates them if there is any change. Communication is always in the direction from agent to server, which means the functionality is controlled by the agent.
+
[[Image:Esquema-3.png|center|650px]]
 +
<center>Logical outline of an agent/physical agent.</center><br>
  
<center><br><br>
+
{{Tip|If versions prior to 7 NG are executed, check software agent naming at the end of this article.}}
[[Image:Xml_transfer.png|550px|center|Xml file transfer]]
 
</center><br><br>
 
  
In order to enable the remote configuration, edit the 'remote_config' parameter from the 'pandora_agent.conf' file, setting it to '1'. Once changed, the agent's configuration file will be ignored, because it's detecting a change in the configuration. It's going to download the new version from the server. This is a good way to force the server to get the agent's local configuration to delete both configuration files from the server.
+
=== Agent Configuration ===
  
== Common Configuration Parameters ==
+
All the configuration and monitoring parameters of the software agents can be found in their configuration file ''pandora_agent.conf''. This is stored locally in the machine where the software agent is installed, so any modification to be made in the agent must be reflected in this file. You have a detailed description of all agent configuration tokens in the chapter "PandoraFMS Agent Configuration" [https://wiki.pandorafms.com/index.php?title=Pandora:Documentation_en:Configuration_Agents] while here we will only focus on the advanced uses of some of them.
  
In the [[Pandora:Documentation en:Configuration#Pandora_FMS_software_agents|Pandora FMS Software Agents]] section you can find a complete explanation on Agent Configuration. In this section, the common parameters used to configure the Software Agents are going to be explained.
+
==== Local configuration ====
  
The most common parameters are:
+
In the software agent's configuration file, modules are defined with the following text basic structure:
  
*'''server_ip''': IP direction of Pandora FMS Server.
+
module_begin
*'''server_path''': Path of the 'incoming' folder for the Pandora FMS server (it's '/var/spool/pandora/data_in' by default).
+
module_name ''your module name''
*'''temporal''': Software agent's temporal folder (it's '/var/spool/pandora/data_out' by default).
+
module_type ''generic_data''
*'''logfile''': Software agent's log file (it's '/var/log/pandora/pandora_agent.log' by default).
+
module_exec ''your command''  
*'''interval''': Agent's execution interval (it's '300' by default).
+
module_description ''your description''
*'''intensive_interval''': Intensive module execution interval (it's '300' by default).
+
module_end
*'''debug''': Debug mode enable ('0' - it's disabled by default).
+
 
*'''agent_name''': Agent name (hostname is taken by default).
+
===== Example 1 =====
*'''server_port''': Tentacle server port (it's '41121' by default).
 
*'''transfer_mode''': File-transfer mode (it's 'tentacle' by default).
 
*'''remote_config''': Activation of remote configuration ('0' - it's disabled by default).
 
  
An example of the general parameters for a '''UNIX configuration''' would be:
+
module_begin
 +
module_name Files in var spool
 +
module_type generic_data
 +
module_exec ls /var/spool | wc -l
 +
module_description Number of files incoming dir
 +
module_end
  
server_ip      192.168.1.1
+
In *nix environment, the command '''ls''' lists directory files and is executed with the line ''module_exec'' to deliver the value to the '''wc''' command, which will count the amount of words received for the same number of files. The value returned by this last execution will be the data that the module will obtain and will be displayed in the monitoring.  
server_path    /var/spool/pandora/data_in
 
temporal        /var/spool/pandora/data_out
 
logfile        /var/log/pandora/pandora_agent.log
 
interval        300
 
debug          0
 
agent_name      box01
 
server_port    41121
 
transfer_mode  tentacle
 
remote_config  1
 
  
An example of the general parameters for a '''Windows configuration''' would be:
+
===== Example 2 =====
  
  server_ip      192.168.1.1
+
  module_exec vmstat 1 2 | tail -1 | awk '{ print $13 }'
server_path    /var/spool/pandora/data_in
 
temporal        c:\program files\pandora_agent\temp
 
logfile        c:\program files\pandora_agent\pandora_agent.log
 
interval        300
 
debug          0
 
agent_name      box01
 
server_port    41121
 
transfer_mode  tentacle
 
remote_config  1
 
  
==Custom Fields==
+
The '''vmstat''' command reports virtual memory statistics. In this examples there are two additional commands to "refine" the desired information. It is recommended to first launch the command manually and analyze the output.
  
Custom fields are an easy way to personalize agent information. Create custom fields by clicking on 'Resources' -> 'Custom fields'.
+
$> vmstat 1 2 | tail -1 | awk '{ print $13 }'
  
<br><br>
+
If the result satifies the requirement, it will be possible to add it to the configuration file. Later on the value returned by the execution through the software agent will be stored in the XML as module data.
<center>
 
[[image:Custom_fields1.png|center|800px]]
 
</center><br><br>
 
  
If you want to create a custom field, click on the 'Create field' button and fill in the fields as described below:
+
===== Example 3 =====
  
<br><br>
+
Any command or software can be executed through ''module_exec'' while the output supports the values accepted by Pandora FMS (numeric, alphanumeric or ''boolean''), so it is possible to indicate custom scripts:
<center>
 
[[image:Custom_fields2.png|center|800px]]
 
</center><br><br>
 
  
* '''Name''': Name of the custom field.
+
module_exec myScript.pl --h 127.0.0.1 -v cpu
* '''Display on front''': With this field checked, the custom field will be displayed in front of the agent like on the screenshot below:
 
  
<center><br><br>
+
Again, the agent will execute the shell and will retrieve the result, as if it was executed by an operator:
[[image:Custom_fields3.png|center|800px]]
 
</center><br><br>
 
  
== Monitoring with the Software Agent ==
+
$> myScript.pl --h 127.0.0.1 -v cpu
  
The data collected by the software agents is kept in small information pieces called 'modules'. Each module only keeps one kind of data. Each module's value is the value of a supervised variable. Once the agent starts sending information, the data will start to consolidate in the database where you're able to access it.
+
==== Remote Configuration ====
  
 +
On the Enterprise version, there is a remote Agent Configuration feature which allows centralized configuration and file management from the server console. This allows centralized management of all our software agents without the need to physically access the systems where they are installed.
  
Please check the Software Agents Installation Section to obtain more information about them.
+
The configuration consists of two files. Their file names are <md5>.conf and <md5>.md5, where <md5> is the agent's name hash code. Those files are stored in '/var/spool/pandora/data_in/conf' and '/var/spool/pandora/data_in/md5' folders respectively. The console is in charge of keeping said files synchronized in Pandora FMS server and the local ones accordingly, where each software agent is installed.  
  
 
<br>
 
<br>
[[File:Agent-monitoring.png|500px|center]]
 
<br>
 
 
The Pandora FMS Software Agents use the operating system's specific commands to obtain information. The Pandora FMS Data Server keeps and processes data generated by these commands which are sent to the server in form of an XML file. The information which gets returned by these commands is contained in what we call 'Modules'.
 
 
 
<center>
 
<center>
 +
[[image:Sw-agent.png|center|550px]]
 +
</center>
 
<br>
 
<br>
[[Image:PandoraAgent_logical_schema.png|center|650px]]
 
<br>
 
</center>
 
  
In the agent configuration file, the modules are defined by the following structure:
+
To enable remote configuration, enable the corresponding parameter in the agent's local configuration file first. From this moment on, all the changes must be made from Pandora FMS console:
  
  module_begin
+
  remote_config 1
module_name cpu_user
 
module_type generic_data
 
module_exec vmstat 1 2 | tail -1 | awk '{ print $13 }'
 
module_description User CPU Usage (%)
 
module_end
 
  
The parameter which indicates how to get the module information is called ''' 'module_exec' '''. This parameter specifies the command which the agent should execute in order to get the information from the system. Example:
+
{{Tip|Once the agent's remote configuration is enabled, any changes made locally in the configuration file will be overwritten by the configuration stored in the console. If you want to prevent this from happening, stop the agent, modify the configuration file, disable the remote configuration and launch the agent again.}}
  
module_exec vmstat 1 2 | tail -1 | awk '{ print $13 }'
+
=====Custom Fields=====
  
The agent will execute the command as an operator to collect the information:
+
[[Image:RK0b6ZaqBm.png|center|550px|Custom field manager for agents]]
  
$> vmstat 1 2 | tail -1 | awk '{ print $13 }'
+
Custom fields are an easy way to add additional agent information. Create custom fields by clicking on '''Resources''' -> '''Custom fields'''.
  
Then the agent gets the returned value by the command and attaches it to the XML file as module data. Of course the agent can execute any program or script which returns the monitoring value. The field 'module_exec' could be for example:
+
{{Tip|<nowiki>You can include links in custom fields using the [url]link[/url] or [url=link]webname[/url] tags.</nowiki>}}
  
module_exec myScript.pl --h 127.0.0.1 -v cpu
+
'''Display up front''' and '''Enabled combo''' fields are disabled by default:
  
Again the agent is going to execute the command and collects the returned value in the same way as an operator would type in the shell:
+
[[Image:customfields2.JPG|center|500px|"Display up front" and "Enabled combo" disabled]]
  
$> myScript.pl --h 127.0.0.1 -v cpu
+
* By activating the field '''Display up front''', custom field information will be displayed in the agent's general view as shown below. In addition, enable this token to send ''Custom Fields'' information to the Metaconsole and be able to see it in the [https://pandorafms.com/docs/index.php?title=Pandora:Metaconsole:Documentation_en:Visualization#Agents agent] view and work in [https://pandorafms.com/docs/index.php?title=Pandora:Metaconsole:Documentation_en:Visualization#Custom_Fields_View Custom Field View] with this data.  
  
 +
[[Image:vW9D9s2l9u.png|center|550px|"Display up front" activado]]
  
When the software agent is executed for the first time, it sends an XML to the Pandora FMS data server which is received in the server's incoming directory through Tentacle, SSH or FTP. The data server checks this directory every X time and when it finds a file, it gets processed. On opening this data file (XML), it identifies the agent by its specific name. This is because each agent is required to have a distinct, case-sensitive name. The server creates all agents automatically from which it receives data and which aren't already logged in on the DB by default. In the same way, if the agent has been added in 'learning mode', the modules which haven't been previously defined in the agent will be created automatically by the Server.
 
  
 +
[[Image:eqyIkxu4qJ.png|center|800px]]
  
{{warning|Configuration file encoding. It's very important to have exactly the same value as the one set in the '''encoding''' configuration parameter. If the encoding is properly set, you're going to avoid the reception of data, bearing wrong encoding characters.}}
+
[[Image:x1fYvcHCZt.png|center|500px]]
  
=== Kinds of Modules ===
+
* '''Enabled combo''': This parameter allows you to activate the configuration of selectable parameters from a drop-down list. Once activated, a new field will appear in the configuration window of the corresponding custom field to enter the combo values separated by commas.
  
There are several kinds of modules, but they're mainly classified in two categories: Data which originated on software agents and data which originated on network modules, executed by a network server. The modules identified as 'generic' are the ones which originate on software agents and those identified as 'remote' are network modules.
+
{{Warning|If the "Enabled combo" parameter is enabled, "Password type" will be disabled.}}
  
'''generic_data'''
+
Custom fields can also be retrieved from the agent configuration file, using the following configuration token:
  
A kind of numerical data. It's pretty useful to keep numerical data (in whole numbers and floating point) obtained through a Pandora FMS agent module.
+
custom_field1_name Model
 +
custom_field1_value i386
  
'''generic_data_inc'''
+
==== Common Configuration Parameters ====
  
A kind of increasing numerical data. It keeps data which results in the difference between the last agent data and the current data. The Pandora FMS server calculates and keeps the rate by second automatically. All of the modules which end on 'inc' are of the incremental kind. This kind of data is used to count the 'number of times' of something per second, e.g. the entries in a log, bytes/sec, connections/sec, etc.
+
Most important parameters for basic agent configuration (more details in [[Pandora:Documentation en:Configuration#Pandora_FMS_software_agents|Pandora FMS Software Agents]]):
  
'''generic_data_inc_abs'''
+
*'''server_ip''': IP address of Pandora FMS Server.
 +
*'''server_path''': Path of the 'incoming' folder for the Pandora FMS server (it's '/var/spool/pandora/data_in' by default).
 +
*'''temporal''': Software agent's temporal folder (it is '/var/spool/pandora/data_out' by default).
 +
*'''logfile''': Software agent's log file (it is '/var/log/pandora/pandora_agent.log' by default).
 +
*'''interval''': Agent's execution interval (it is '300' by default).
 +
*'''intensive_interval''': Intensive module execution interval (it is '300' by default).
 +
*'''debug''': Enables (1) the debug mode, to save XML data files and analyze them. When it is activated, it does not send XML to the server and for execution, to be able to analyze the XML generated.
 +
*'''agent_name''': Agent name (hostname is taken by default).
 +
*'''remote_config''': Activation of remote configuration. It is disabled (0) by default. Only for Enterprise version.
  
A kind of increasing numerical data. It collects data as a result of the difference between the previous module data and the current data, without making the division by seconds, obtaining total increment and not increment per second. All of the modules that end on 'inc_abs' are of incremental absolute type. This kind of data is used to count the 'number of times' of something, e.g. the entries in a log, total traffic of bytes, connections to a host, etc.
+
An example in a '''*nix''' environment:
  
'''generic_proc'''
+
server_ip      192.168.1.1
 +
server_path    /var/spool/pandora/data_in
 +
temporal        /var/spool/pandora/data_out
 +
logfile        /var/log/pandora/pandora_agent.log
 +
interval        300
 +
debug          0
 +
agent_name      box01
 +
server_port    41121
 +
transfer_mode  tentacle
 +
remote_config  1
  
They are generally called "monitors", too. They belong to the boolean kind of data where a value of '0' means 'false' or 'bad value', and values higher than '0' mean 'right' or 'right value'. The 'generic proc' kind is also called 'monitor', because they can show if something is right or wrong without the need of interpreting or establishing alerts on it. They are displayed in the agent view as small lights. Red if it's '0', green if it's higher than'0'. All of modules which end on 'proc' are monitors.
+
An example in a '''MS Windows®''' environment:
  
'''generic_data_string'''
+
server_ip      192.168.1.1
 +
server_path    /var/spool/pandora/data_in
 +
temporal        c:\program files\pandora_agent\temp
 +
logfile        c:\program files\pandora_agent\pandora_agent.log
 +
interval        300
 +
debug          0
 +
agent_name      box01
 +
server_port    41121
 +
transfer_mode  tentacle
 +
remote_config  1
  
Kinds of alphanumeric data (text).
+
==== Password protected groups ====
  
''Image module''
+
By default, when an agent sends data for the first time to the Pandora FMS server, it is automatically added to the group that has been defined in the agent configuration file. This means that, in practice, anyone can add an agent to a group if they know the group name. This could be a problem if several clients share their Pandora FMS instance or if you want to control what is in each group.
  
If the data in the module is a base64 image, in other words, part of the string contains "data:image", it will be identified as an image and, on the views where it appears, it will enable a link to open a window to display the image. Also on its historical data the strings that build/generate the images will be saved and displayed.
+
We can optionally configure a password for a group from the Pandora FMS Console. An agent will not be added to a group unless the correct password has been specified in the agent configuration file.
  
'''async_data'''
+
===== Example =====
  
It's a kind of asynchronous numeric data. It's the same as 'generic_data' but for asynchronous data which is only updated if there is a change. The asynchronous kind of data don't have a defined periodicity when we can obtain data.
+
To set a password for a group, navigate to the ''group editor'' and click on ''edit'', enter the group password and save your changes:
  
'''async_string'''
+
<center>
 +
[[File:Passgr1.JPG|center]]
 +
</center>
  
This is a kind of asynchronous alphanumeric data. It's the same as 'generic_string' but for asynchronous data which are only updated if there is a change. It's the kind of data that you're recommended to use if you want to monitor searches in logs or event viewers. We could have new data by any second or not having one at all in many days.
+
To add a new agent to this group, edit your configuration file and add the following configuration option:
  
''Image module''
+
  group_password <password>
 
 
If the data in the module is a base64 image, in other words, part of the string contains "data:image", it will be identified as an image and, on the views that it appears, it will enable a link to open a window to display the image. Also on its historical data the strings that build/generate the images will be saved and displayed.
 
 
 
'''async_proc'''
 
 
 
It's a kind of asynchronous boolean data. It's the same as 'generic _proc' but for asynchronous data which are only updated if there is a change.
 
 
 
The software agent already comes preconfigured to send certain data from the system on which it's installed. These usually are (depending on the version):
 
 
 
* System CPU
 
* Available space on the hard-drive
 
* Free memory
 
* Monitor of the programs and services states
 
 
 
Depending on the software agent, they are also going to look for one operating system or another. They also might have more modules or different things to check.
 
 
 
All this information is located in the file 'pandora_agent.conf'. This file is in the directory '/etc/pandora/' under GNU/Linux and, under the default Windows installation, the directory is 'C:\Archivos de Programa\pandora_agent\' or 'C:\Program Files\pandora_agent\' or similar.
 
  
We are now going to explain the kind of data for some of the modules:
+
{{Tip|Do not forget to restart the agent to make the changes effective. The agent should be created correctly in the Pandora FMS console.}}
  
Percentage of CPU usage under GNU/Linux
 
  
<pre>
 
# CPU usage percentage (GNU/Linux)
 
module_begin
 
module_name cpu_user
 
module_type generic_data
 
module_interval 1
 
module_exec vmstat 1 2 | tail -1 | awk '{ print $13 }'
 
module_max 100
 
module_min 0
 
module_description User CPU Usage (%)
 
module_end
 
</pre>
 
  
It's obvious the kind of module is from the 'generic_data' kind which executes a GNU/Linux console command to obtain the result ('module_exec'). The maximum is set to '100' and the minimum to '0'. The interval ('module_interval') represents the number of iterations between the execution of each module. If it's different from '1', the module will only start the execution of the agent the number of times which is set there. If e.g. the agent execution time is set on '300' and the module interval is '3', the module is going to be executed every 900 seconds.
 
  
Percentage of the CPU usage under Windows:
+
=== Modules in agents and software agents ===
  
<pre>
+
==== Types of Modules ====
# CPU usage percentage (Windows)
+
The following are the possible types of modules in software agents depending on the type of data returned:
module_begin
 
module_name CPUUse
 
module_type generic_data
 
module_cpuusage all
 
module_description CPU#0 usage
 
module_end
 
</pre>
 
  
As you can easily see, the module is completely different from GNU/Linux under Windows. Under Windows it's an internal agent command where '''module_cpuusage all''' represents the CPU usage for all CPUs. Using 'module_cpuusage' is only going to calculate the CPU usage for CPU #0. The rest of the fields are optional.
+
*'''generic_data''': Numerical and floating point data.
 +
*'''generic_data_inc''': A kind of increasing numerical data. Stores the difference between the previous and current data divided by the elapsed time in seconds, showing the rate per second. This type of data is used to count "number of times per second" of something, such as log entries/sec, receivedbytes/sec , incoming connections/sec , etc.
 +
*'''generic_data_inc_abs''': Type of absolute increasing numerical data. It stores the difference between the previous and current data, without dividing it between the elapsed seconds, so the value will correspond to the total increase between the two executions, and not to the increase per second. This type of data is used to count the number of times something happens, such as log entries, total received bytes, number of incoming connections, and so on.
 +
*'''generic_proc''': Boolean type of data, where a value of 0 means False or incorrect, and values above zero mean True or correct. The ''generic_proc'' types have the critical (0) and correct (1 or higher) states preconfigured.
 +
*'''generic_data_string''': Kinds of alphanumeric data (text).
 +
*'''async_data''': It is a kind of asynchronous numeric data. It is the same as 'generic_data' but for asynchronous data which is only updated if there is a change. The asynchronous kind of data do not have a defined periodicity when data can be obtained.
 +
*'''async_string''': This is a kind of asynchronous alphanumeric data. It is the same as 'generic_string' but for asynchronous data which are only updated if there is a change. It is the kind of data that you are recommended to use if you want to monitor searches in logs or event viewers. New data can be obtained at any moment or not for several days.
 +
*'''async_proc''': It is a kind of asynchronous boolean data. It is the same as 'generic _proc' but for asynchronous data which are only updated if there is a change.
  
To add one more module, please check the agent configuration and create a valid module block. Once you have done this, keep the agent configuration file and restart the agent, no matter if it's the UNIX daemon or the Windows service.
 
  
=== Module Creation Interface ===
+
*'''Image module''': They are based on a text string type module (generic_data_string or async_string). If the data in the module is a base64 image, in other words, part of the string contains "data:image", it will be identified as an image and, on the views that it appears, it will enable a link to open a window to display the image. Also on its historical data the strings that build/generate the images will be saved and displayed.
  
The creation of local modules from the console is done using a text box form. This is the location to specify the configuration data, which will be placed into the configuration file of the software agent (besides the common configuration with the remote modules like thresholds, type and group).
+
====Intervals in local modules====
 +
The local modules (or software agent modules) all have the interval of their agent as a "base". However, they can take values that are multiple from that base if the module_interval parameter is modifies by multiplying with an integer higher than zero; for example:
  
''Creation of a module with the remote config enabled on the agent:''
+
module_interval 2
  
<center>
+
If an agent has an interval of 300. The interval's module will be 300x2 (600).
<br><br>
 
[[Image:local_module_editor.png|center|750px]]
 
<br><br>
 
</center>
 
  
In this text box there are '''two buttons''': One to '''create a basic configuration structure''' and the other to '''check that the data is correct'''. This check is intended for basic parameters, e.g. checking if it begins with 'module_begin', ends with 'module_end' and if it has a valid type and name. Other parameters may be wrong, but that won't be detected here.
+
==== Module Creation Interface ====
<center>
 
<br><br>
 
[[Image:local_module_editor_basic.png|center|750px]]
 
<br><br>
 
</center>
 
  
<center>
+
{{Tip|Feature exclusive for the '''Enterprise version'''; the according Software agent's remote configuration must be enabled.}}
<br><br>
 
[[Image:local_module_editor_check_wrong.png|center|750px]]
 
<br><br>
 
</center>
 
  
<center>
+
Console local module creation is done through a form where, inn addition to the common configuration of any module (thresholds, type, group, etc. it has a text box where to specify the configuration data to be set in the Software agent configuration file.  
<br><br>
 
[[Image:local_module_editor_check_right.png|center|750px]]
 
<br><br>
 
</center>
 
  
'''The field name and the type combo are linked to the parameters 'module_name' and 'module_type' of the data configuration'''. If you change the module name on the name field, the configuration data name will be changed automatically and vice versa. If you select a type in the combo, the data configuration type will be changed and if a correct type was written in the configuration data, this type will be selected automatically in the combo.
+
[[Image:local_module_editor.png|center|800px]]
  
When a module from a local component is changed, it might have macros. If it has macros, the configuration data will be hidden and a field for each macro is going to appear instead. You can find a detailed explanation of this feature in the following section:
+
* By clicking on '''Load basic (template)''', the content of ''Data configuration'' will be deleted with a basic template that you must modify according to your monitoring needs.
 +
* Once modified, by clicking on '''Check (syntax)''' it will verify that the template's syntax stays correct, however the rest of the commands will not be checked.
  
 +
When a module is loaded from a local component, it may have macros. If it has macros, the configuration box will stay hidden and a field will appear for each macro, see more information in
 
[[Pandora:Documentation_en:Templates_and_components#Macros|Templates and components]]
 
[[Pandora:Documentation_en:Templates_and_components#Macros|Templates and components]]
  
 
=== Conditional Monitoring ===
 
=== Conditional Monitoring ===
 +
==== Post-Conditions ====
  
The Pandora FMS Software Agent supports the execution of a script as a postcondition, depending on the module value. Also the software agent has a feature to evaluate a precondition before module execution. We're going to explain both features and provide examples in this section for them.
+
Pandora FMS software agent supports the execution of commands and scripts as post-conditions. This means that '''actions could be performed depending on the value obtained in the execution of the module'''.
  
==== Post-Conditions ====
+
=====Example 1=====
  
The parameter '''module_condition''' defines a postcondition in the moment of module execution. It means this parameter defines the command which will be executed depending on the value returned by the module. The structure in the configuration file is:
+
With the ''module_condition'' parameter, a value or range of values and the execution to be carried out must be indicated in case the obtained data meets the terms (CPU usage under 200%):
  
 
  module_begin
 
  module_begin
Line 280: Line 230:
 
  module_end
 
  module_end
  
You can define multiple postconditions for the same module, e.g.:
+
=====Example 2=====
 +
 
 +
You can specify multiple conditions for the same module, in a range and with a minimum threshold (mathematically, one or none of both options is carried out):
  
 
  module_begin
 
  module_begin
Line 290: Line 242:
 
  module_end
 
  module_end
  
Some examples:
+
=====Example 3=====
  
''Execution if the module data is less than '20' '':
+
Similar to the previous example, but both conditions can be executed or one or none (try with selected values: if it is 5, 15 or 30):
  
 
  module_begin
 
  module_begin
Line 301: Line 253:
 
  module_end
 
  module_end
  
If the script named 'get_cpu_usage.pl' returns '18', the software agent is going to execute the script 'add_processes.sh', otherwise it won't.
+
==== Pre-Conditions ====
 
 
''Execution with two preconditions'':
 
  
module_begin
+
The '''module_precondition''' parameter defines a precondition to evaluate before a module execution. Depending on the result of this precondition, the software agent will execute the module or not.
module_name CPU_Usage_Condition
 
module_type generic_data
 
module_exec get_cpu_usage.pl
 
module_condition < 10 start_new_server.sh
 
module_condition < 20 add_processes.sh
 
module_end
 
  
If the module returns '15', the software agent is going to only execute the script named 'add_processes.sh' - but if the value is '6', the script is going to execute both scripts named 'start_new_server.sh' and 'add_processes.sh'.
+
{{Tip|You must mentally abstract to assign the value to module_precondition and then compare with the condition.}}
  
==== Pre-Conditions ====
+
===== Example 1 =====
  
The parameter ''' 'module_precondition' ''' defines a precondition to evaluate before a module execution. Depending on the result of this precondition, the software agent will execute the module or not. The structure of the configuration file is:
+
According to CPU usage, if the active processes are more than ten, obtaining the CPU usage percentage and reporting to Pandora FMS server:
  
 
  module_begin
 
  module_begin
 
  module_name CPU_Usage
 
  module_name CPU_Usage
 
  module_type generic_data
 
  module_type generic_data
module_exec get_cpu_usage.pl
 
 
  module_precondition > 10 number_active_processes.sh
 
  module_precondition > 10 number_active_processes.sh
module_end
 
 
You can define multiple preconditions for the same module:
 
 
module_begin
 
module_name CPU_Usage
 
module_type generic_data
 
 
  module_exec get_cpu_usage.pl
 
  module_exec get_cpu_usage.pl
module_precondition > 10 number_active_processes.sh
 
module_precondition = 1 important_service_enabled.sh
 
 
  module_end
 
  module_end
  
Some examples:
+
===== Example 2 =====
  
''Module execution if the precondition is above '10' only:''
+
You can define multiple preconditions for the same module and all of them must be met:
  
 
  module_begin
 
  module_begin
 
  module_name CPU_Usage
 
  module_name CPU_Usage
 
  module_type generic_data
 
  module_type generic_data
 +
module_precondition > 10 number_active_processes.sh
 +
module_precondition > 1 important_service_enabled.sh
 
  module_exec get_cpu_usage.pl
 
  module_exec get_cpu_usage.pl
module_precondition > 10 number_active_processes.sh
 
 
  module_end
 
  module_end
  
The software agent executes the script 'number_active_processes.sh', if the returned value is greater than '10'. If the returned value is lower than '10', the module will never be executed.
+
In this case, the module is executed only if there are more than ten active processes and if at least one of them is an important process.
  
''Module execution if only two of the preconditions are met:'':
+
=== Intensive Monitoring ===
  
module_begin
+
There are certain specially important modules, such as critical running processes or services. Intensive monitoring enables more controlled monitoring of these particular cases.
module_name CPU_Usage
 
module_type generic_data
 
module_exec get_cpu_usage.pl
 
module_precondition > 10 number_active_processes.sh
 
module_precondition = 1 important_service_enabled.sh
 
module_end
 
  
We have two preconditions in this example. To execute the module (both of them in this case), all preconditions must be met. The module will only be executed if the script 'number_active_processes.sh' returns a value greater than '10' and when the script 'important_service_enabled.sh' returns a value of '1'.
+
It consists of warning in a shorter interval that a problem has arisen without reducing the agent's general interval.
  
=== Intensive Monitoring ===
+
Software agent configuration:
 +
*'''Interval''': agent sampling time in seconds. This is the general range for all local modules. Required parameter.
 +
*'''Intensive_interval''': time in which you will be notified of a problem on the especially critical modules. Optional parameter.
  
(Only available in versions 5.0 or above)
+
Module configuration:
  
Certain values are very important for some modules, while others are not. If when you are monitoring a system service, you want to be notified as soon as possible if the service goes down - but you don't need to be reminded the service is up every ten seconds.
+
* '''module_intensive_condition = 0''': if the module obtains as a result the value indicated in this parameter (in this case 0), it will be notified in the intensive interval defined in the agent.
  
This is where intensive modules come in. Intensive modules run with an interval of ''intensive_interval'' in seconds. When intensive conditions are met, they run the rest of the time with an interval of ''interval'' seconds like the rest of the modules.
+
====Example====
  
If you want to check whether the SSHD system service is running every 10 seconds, but want to be notified every 10 minutes if the service is fine, you may configure the agent in the following way:
+
The '''sshd''' service is very important since it is used to connect by shell remotely, we need to monitor its working:
  
 
  intensive_interval 10
 
  intensive_interval 10
  interval 600
+
  interval 300
  
 
  module_begin
 
  module_begin
Line 381: Line 312:
 
  module_end
 
  module_end
  
If the service goes down, you will be notified in the next 10 seconds. If the service is up, you will be notified in the next 10 minutes.
+
If the service fails, you will be notified in the next 10 seconds. If the service is up, you will be notified in the next 5 minutes, like normally (normal interval, 300 seconds).
 
 
This can save a lot of space in the Pandora FMS Database.
 
  
 
=== Programmed Monitoring ===
 
=== Programmed Monitoring ===
  
The software agent supports the definition of programmed modules which are executed in the defined instances. The syntax is the same as crontab. For a detailed explanation, see http://en.wikipedia.org/wiki/Cron#Predefined_scheduling_definitions
+
The software agent supports the definition of programmed modules which are executed in the defined instances. The syntax used is the same as crontab. An example of module definition to execute it all Mondays from 12 to 15 hours:
 
 
The module structure is the following:
 
  
 
  module_begin
 
  module_begin
Line 398: Line 325:
 
  module_end
 
  module_end
  
In this example the module '''is executed once''', every Monday from 1200 to 1500 hours.
+
To execute it in minute 10 of each hour:
 
 
If you want a module which is executed '''during all the interval''', we have to set the option 'module_cron_interval' to '0' in this way:
 
  
 
  module_begin
 
  module_begin
Line 406: Line 331:
 
  module_type generic_data
 
  module_type generic_data
 
  module_exec script.sh
 
  module_exec script.sh
  module_crontab * 12-15 * * 1
+
  module_crontab 10 * * * *
module_cron_interval 0
 
 
  module_end
 
  module_end
  
If we're required to execute the module every hour past ten minutes we can use this module definition:
+
{{Tip|Note that if you use an interval that causes the module not to report data, this module will go into "unknown" status. Use asynchronous modules for these cases.}}
  
module_begin
+
== Remote Checks with Software Agents ==
module_name crontab
 
module_type generic_data
 
module_exec script.sh
 
module_crontab 10 * * * *
 
module_cron_interval 0
 
module_end
 
  
=== Specific Monitoring for Windows ===
+
When Pandora FMS main server does not have access to carry out remote checks (generally for security reasons), a software agent is able to take its place for such reasons and can even be distributed in broker agents.
 
 
The software agent for Windows has specific features to make monitoring a lot easier. These features are explained with some examples:
 
 
 
==== Monitoring Processes and Watchdog Process ====
 
 
 
===== Monitoring of Processes =====
 
 
 
The parameter '''module_proc''' verifies if a process with a preset name is running on this machine. The module definition is:
 
 
 
module_begin
 
module_name CMDProcess
 
module_type generic_proc
 
module_proc cmd.exe
 
module_description Process Command line
 
module_end
 
  
If the process name has blanks, '''don't use «" "»'''. The process name is the same as shown in Windows Task Manager (taskmngr) including the .exe extension. It's very important to '''use the same upper and lower-case letters'''.
+
=== ICMP Checks ===
  
If you want the software agent to immediately notify you if a process is not working add the parameter '''module_async yes'''. In this case, the module definition would be:
+
ICMP or ping checks are very useful to know whether a machine is connected to a network or not. In this way, a single software agent could easily monitor the status of all machines.
 
 
module_begin
 
module_name CMDProcess
 
module_type generic_proc
 
module_proc cmd.exe
 
module_async yes
 
module_description Process Command line
 
module_end
 
 
 
===== Watchdog Process =====
 
 
 
The watchdog feature on the Pandora Agent for Windows allows immediate response to the crash of a process and restarts it. It's important to keep in mind that the watchdog only works if the module is of the asynchronous type.
 
 
 
The definition of a module with watchdog enabled would be as follows:
 
 
 
module_begin
 
module_name Notepad
 
module_type generic_data
 
module_proc notepad.exe
 
module_description Notepad
 
module_async yes
 
module_watchdog yes
 
module_start_command c:\windows\notepad.exe
 
module_startdelay 3000
 
module_retrydelay 2000
 
module_retries 5
 
module_end
 
 
 
In the previous example, the watchdog is only going to activate the 'notepad.exe' if the process is not running. It's going to execute the command
 
''c:\windows\notepad.exe'' each time. Other preconfigured parameters for the watchdog execution are to try 5 times with a warm-up time (delay before trying) of 3 seconds and a time of 2 seconds between retries.
 
 
 
==== Service Monitoring and Watchdog Service ====
 
 
 
===== Service Monitoring =====
 
 
 
The parameter '''module_service''' verifies if a specified service is running on the machine. The definition of this module is as follows:
 
 
 
module_begin
 
module_name Service_Dhcp
 
module_type generic_proc
 
module_service Dhcp
 
module_description Service DHCP Client
 
module_end
 
 
 
If the service name has blanks, don't use «" "». To find the service name, you can look at the Service Name field under the Windows Service Manager. It's important to keep in mind that all names are case sensitive.
 
 
 
If you want the software agent to warn you immediately when a service is down, add the parameter '''module_async yes'''. The module definition would be as follows:
 
 
 
module_begin
 
module_name Service_Dhcp
 
module_type generic_proc
 
module_service Dhcp
 
module_description Service DHCP Client
 
module_async yes
 
module_end
 
 
 
===== Watchdog Service =====
 
 
 
There is a watchdog mode for services which allow you to detect and restart a downed service almost in real time. A module definition example using watchdog would be the following:
 
 
 
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
 
 
 
The watchdog definition for services which have no need for any extra parameters because they are incorporated in the service definition.
 
 
 
==== Monitoring Basic Resources ====
 
 
 
This section describes how to monitor the basic variables of a Windows-based machine.
 
 
 
===== Monitoring the CPU =====
 
 
 
To monitor the CPU, you may use the parameter '''module_cpuusage''' which returns the CPU usage percentage.
 
 
 
Its possible to monitor the CPU based on its ID with a module definition like the following:
 
 
 
module_begin
 
module_name CPU_1
 
module_type generic_data
 
module_cpuusage 1
 
module_description CPU usage for CPU 1
 
module_end
 
 
 
You're also able to monitor the average CPU usage from all systems with the following module:
 
 
 
module_begin
 
module_name CPU Usage
 
module_type generic_data
 
module_cpuusage all
 
module_description CPU Usage for all system
 
module_end
 
 
 
===== Memory Monitoring =====
 
 
 
To monitor the memory, you can use two parameters: '''module_freememory''' which returns the amount of free memory in the system and '''module_freepercentmemory'''
 
which returns the percentage of free memory.
 
 
 
An example for a module using the '''module_freememory''' parameter would be:
 
 
 
module_begin
 
module_name FreeMemory
 
module_type generic_data
 
module_freememory
 
module_description Non-used memory on system
 
module_end
 
 
 
An example for a module using the '''module_freepercentmemory''' parameter would be:
 
 
 
module_begin
 
module_name FreePercentMemory
 
module_type generic_data
 
module_freepercentmemory
 
module_end
 
 
 
===== Monitoring Hard drives =====
 
 
 
To monitor the hard drive space, you may use two parameters: '''module_freedisk''' which returns the amount of available space and '''module_freepercentdisk''' which returns the percentage of available space. Both parameters require the monitored unit as an input. '''Please don't forget the «":"» characters.'''
 
 
 
A module which utilizes the '''module_freedisk''' parameter is defined in this way:
 
 
 
module_begin
 
module_name FreeDisk
 
module_type generic_data
 
module_freedisk C:
 
module_end
 
 
 
An module which utilizes the '''module_freepercentdisk''' parameter is defined in this way:
 
 
 
module_begin
 
module_name FreePercentDisk
 
module_type generic_data
 
module_freepercentdisk C:
 
module_end
 
 
 
==== WMI Queries ====
 
 
 
The Pandora FMS Software Agent allows you to extract information by using WMI queries and ODBC connections - very common technologies used to store external or system-related information.
 
 
 
===== WMI Queries =====
 
 
 
The software agent allows you to execute any local WMI query you want using the '''module_wmiquery''' parameter. To perform the query, set the parameter '''module_wmiquery''' by the query which is going to be performed and to set the parameter '''module_wmicolumn''' by the column which has the information to monitor.
 
 
 
We're able to get a list with 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
 
 
 
We're also able to get the CPU load using WMI:
 
 
 
module_begin
 
module_name CPU_Load
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
 
module_wmicolumn LoadPercentage
 
module_end
 
 
 
=== Remote Checks with Software Agents ===
 
 
 
A remote check performed by the agent makes it easy to monitor complex networks that have special, security-related requirements. This section explains how to use this feature of the software agent:
 
 
 
==== ICMP Checks ====
 
 
 
ICMP or ping checks come in handy if the machine is connected to a network. Only one software agent is easily able to monitor the status of the whole network in this way.
 
  
 
'''UNIX'''
 
'''UNIX'''
  
By using the UNIX software agent, you're able to utilize the system commands to create a module which performs the ping check. An example module definition would be:
+
Using the system commands (all parameters in the "command line" module_exec):
  
 
  module_begin
 
  module_begin
 
  module_name Ping
 
  module_name Ping
 
  module_type generic_proc
 
  module_type generic_proc
  module_exec ping -c 1 192.168.100.54 >/dev/null 2>&1; if [ $? == 0 ]; then echo 1; else echo 0; fi
+
  module_exec ping -c 1 192.168.100.54 >/dev/null 2>&1; if [ $? -eq 0 ]; then echo 1; else echo 0; fi
 
  module_end
 
  module_end
  
In this example module, we're going to perform a ping check on the host '192.168.100.54'. If you want to check a different host, all you have to do is to change the IP.
+
Note: Replace "192.168.100.54" by the IP address to be monitored.
  
'''Windows'''
+
'''MS Windows®'''
  
The software agent for Windows platforms has the following parameters to configure the ping checks:
+
The parameters must be specified in module_ping_count (number of packets, 1 by default) and module-ping_timeout (time limit in seconds, 1 by default); example:
 
 
* module_ping_count x: Number of ECHO_REQUEST packages to send (Default value is '1').
 
* module_ping_timeout x: Timeout in seconds (Default value is '1').
 
* module_advanced_options: Advanced options for 'ping.exe'.
 
 
 
A module configuration example could be:
 
  
 
  module_begin
 
  module_begin
Line 643: Line 368:
 
  module_end
 
  module_end
  
In this example, we're going to perform the same check as in the previous one, but now we're going to use the Software Agent for Windows platforms.
+
Note: module_advanced_options allows advanced options for ping.exe.
  
==== TCP Checks ====  
+
=== TCP Checks ===  
  
TCP checks are useful to verify if a port of a host happens to be open or not. Interesting in case you want to know if an application is connected to the network or not.
+
TCP checks are useful to verify whether a port of a host stay open and allow to find out whether an application connects or not to the network.
  
 
'''UNIX'''
 
'''UNIX'''
  
We're able to perform the TCP checks by the following module by utilizing the software agent for UNIX platforms:
+
With the '''nmap''' command and its configuration parameters in the command line, to an IP address check whether port 80 is open (response waiting time of 5 seconds):
  
 
  module_begin
 
  module_begin
Line 659: Line 384:
 
  module_timeout 5
 
  module_timeout 5
 
  module_end
 
  module_end
 
With this module, we're going to check if port 80 of the host '192.168.100.54' is open or not.
 
  
  
'''Windows'''
+
'''MS Windows®'''
  
If we want to use the software agent for Windows, we have some parameters to configure for the TCP check. The parameters are:
+
Parameters must be specified in:
  
 
* module_tcpcheck: Host to be checked
 
* module_tcpcheck: Host to be checked
Line 671: Line 394:
 
* module_timeout: Timeout for the check
 
* module_timeout: Timeout for the check
  
A module definition example is this:
+
Example:
  
 
  module_begin
 
  module_begin
Line 681: Line 404:
 
  module_end
 
  module_end
  
This module is the equivalent for the Windows software agent to perform the check on port 80 of the host '192.168.100.54'.
 
  
==== SNMP Checks ====
+
=== SNMP Checks ===
  
 
SNMP checks are commonly used to monitor network devices to check the interface status, inbound/outbound bytes, etc.
 
SNMP checks are commonly used to monitor network devices to check the interface status, inbound/outbound bytes, etc.
Line 689: Line 411:
 
'''UNIX'''
 
'''UNIX'''
  
If you are using the software agent for UNIX platforms, you may create the module using the command 'snmpget' like this:
+
If you are using the software agent for UNIX platforms, you may create the module using the '''snmpget''' command like this:
  
 
  module_begin
 
  module_begin
Line 697: Line 419:
 
  module_end
 
  module_end
  
This module returns the value for OID .1.3.6.1.2.1.2.2.1.1.148 on the host '192.168.100.54'.
+
This module returns the value for OID .1.3.6.1.2.1.2.2.1.1.148 on the '192.168.100.54' host.
  
'''Windows'''
+
'''MS Windows®'''
  
For the Windows software agent, we have the following configuration parameters for the module:
+
Parameter coniguration:
  
 
* module_snmpversion [1,2c,3]: SNMP version (Default value is '1').
 
* module_snmpversion [1,2c,3]: SNMP version (Default value is '1').
Line 709: Line 431:
 
* module_advanced_options: Advanced options for 'snmpget.exe'.  
 
* module_advanced_options: Advanced options for 'snmpget.exe'.  
  
A module example could be:
+
Example that does the same as the previous example:
  
 
  module_begin
 
  module_begin
Line 721: Line 443:
 
  module_end
 
  module_end
  
Using the UNIX software agents, this module is the Windows platform equivalent to do the last performed check.
+
== Proxy Mode ==
  
=== Proxy Mode ===
+
{{Warning|To use Pandora FMS agent's proxy mode on Linux or UNIX systems, '''the agent must -not- be executed by a root user !''' You are required to perform a custom installation of the Pandora FMS agent to do so. You may look up all the details about custom installations in the section [[Pandora:Documentation_en:Installing#Custom_agent_installation|Custom Agent Installation.]]}}
  
{{Warning|To use the agent's proxy mode on Linux or UNIX systems, '''the agent must -not- be executed by a root user !''' You're required to perform a custom installation of the Pandora FMS agent to do so. You may look up all the details about custom installations in the section [[Pandora:Documentation_en:Installing#Custom_agent_installation|Custom Agent Installation.]]}}
+
Pandora FMS Software Agents have a Proxy Mode which allows them to act other software agent proxies, redirecting the communication of several agents to the Pandora FMS Server. The software agent with an enabled proxy mode is able to perform monitoring tasks too.
 
 
Pandora FMS Software Agents have a Proxy Mode which allows them to act as proxies, redirecting the communication of several agents to the Pandora FMS Server. The software agent with an enabled proxy mode is able to perform monitoring tasks, too.
 
  
 
<br>
 
<br>
Line 733: Line 453:
 
<br>
 
<br>
  
The Proxy Mode is very useful if you're dealing with a network in which only one machine can communicate with the Pandora FMS Server. In this situation, all software agents installed on machines without access to the Pandora FMS Server are going to send the XML files to the agent currently working as a proxy - which is going to redirect all files to Pandora FMS Server.
+
The Proxy Mode was created for local area network where a single computer is exposed to the Internet, where Pandora FMS server is. It is necessary to monitor with software agents the rest of computers of that network; other computers will communicate with the proxy instead of with the server. The proxy mode also supports the Remote configuration and File collection features.
  
In addition to XML file redirection, the proxy mode supports ''Remote Configuration'' and ''File Collection'' features.
+
Parameter configuration:
  
To enable the Proxy Mode in a software agent, you're required to configure the following parameters:
+
* '''server_ip''': IP of the Pandora FMS Server.
 +
* '''proxy_mode''': Enabled (1) or diabled (0).
 +
* '''proxy_max_connection''': Maximum number of simultaneous connections for the proxy. The default value is '10'.
 +
* '''proxy_timeout''': Proxy timemout. The default value is '1' (in seconds).
 +
* '''proxy_address''': Address in which the proxy listens.
 +
* '''proxy_port''': Port in which the proxy listens.
  
* server_ip: IP of the Pandora FMS Server. If the proxy mode is enabled, '''the IP is not allowed to take the following values: '127.0.0.1', 'localhost' or '0.0.0.0'.'''
+
Example:
* proxy_mode: If it's set to '1', the proxy mode is enabled. The default value is '0' (disabled).
 
* proxy_max_connection: Maximum number of connections for the proxy. The default value is '10'.
 
* proxy_timeout: Proxy timemout. The default value is '1' (in seconds).
 
 
 
A configuration example:
 
  
 
  server_ip 192.168.100.230
 
  server_ip 192.168.100.230
Line 751: Line 471:
 
  proxy_timeout 3
 
  proxy_timeout 3
  
To redirect a software agent's connection, you're only required to set the IP address of the proxy mode enabled software agent to the IP address of the Pandora FMS Server on agents with limited access, e.g.:
+
To redirect the connection of a software agent, enter as Pandora FMS server address that of the agent with the Proxy Mode activated.
 
 
Our proxy mode enabled agent has the IP of '192.168.100.24'.
 
  
In the software agent which can't directly connect to the Pandora FMS Server, we configure the parameter '''server_ip''' in the following way:
+
For example, the software agent in proxy mode has the IP address 192.168.100.24, the rest of the software agents must be configured with:
  
 
  server_ip 192.168.100.24
 
  server_ip 192.168.100.24
  
 
+
== Broker Mode ==
This configuration allows the access-limited software agent to use the other software agent with enabled proxy mode to communicate with the Pandora FMS Server.
 
 
 
=== Broker Mode ===
 
  
 
The software agent has a Broker Mode which allows one agent to monitor and manage the configuration as if there were several software agents installed:
 
The software agent has a Broker Mode which allows one agent to monitor and manage the configuration as if there were several software agents installed:
Line 770: Line 485:
 
<br>
 
<br>
  
The software agent with enabled Broker Mode has an auxiliary configuration file (defined for each broker) which is similar to a software agent's main configuration file. In this way the software agent's behavior is the same as if several software agents were installed in the same machine, it means, each broker works in the same way a software agent does. This feature is very useful to remotely manage several devices by installing only one software agent. It's also possible to monitor several devices with different configuration files but only one software agent in this way.
+
When the broker mode is activated in a software agent, a new configuration file is created. From that moment on, the original software agent and the new broker will be managed separately with their independent configuration files, as if they were two completely separate software agents on the same machine.
  
 
The main features of the Broker Mode are:
 
The main features of the Broker Mode are:
  
* To send local data as another agent. Very useful to monitor different software instances as different agents.
+
* Sending local data as another agent. Very useful to monitor different software instances as different agents.
* To send the collected data from the remote checks to other machines as if a software agent had been installed on them.
+
* Sending the collected data from the remote checks to other machines as if a software agent had been installed on them.
  
To create a broker, you're only required to add a line with the parameter '''broker_agent <broker_name>'''  
+
To create a broker, add a line with the '''broker_agent <broker_name>''' parameter. It is possible to create as many broker agents as you wish, just by adding the corresponding ''broker_agent'' lines, as follows:
  
 
  broker_agent dev_1
 
  broker_agent dev_1
 
  broker_agent dev_2
 
  broker_agent dev_2
  
Once the brokers are created, the configuration files 'dev_1.conf' and 'dev_2.conf' are going to be created with the same content as in the original software agent, but with a different agent name. By adding or deleting modules from configuration files 'dev_1.conf' and 'dev_2.conf', we can customize the checks performed by the brokers.
+
Once the brokers are created, the 'dev_1.conf' and 'dev_2.conf' configuration files will be created with the same content as in the original software agent, but with their corresponding name. By adding or deleting modules from 'dev_1.conf' and 'dev_2.conf' configuration files, you can customize the checks performed by the brokers.
 
 
Inside Pandora FMS web console '''the brokers appear and will be managed as the other agents''', which means that if we have a software agent installed with two brokers, we're going to see three different agents with their modules, configurations, etc. in the web console.
 
 
 
'''NOTE''': broker agent instances cannot use file collections. If you want to use collections, you can "execute" files from collections from a instance, but it must be distributed by the "main" agent, not in an instance.
 
 
 
'''NOTE''': modules that keep data in memory between executions (module_logevent and module_regexp on Windows) will not work when broker agents are enabled.
 
  
==== Examples of Use ====
+
On the Pandora FMS web console '''the brokers appear and will be managed independent agents''', which means that if you have a software agent installed with two brokers, you will see three different agents with their modules, configurations, etc. on the web console.
  
===== Monitor a local Database as a different Agent =====
+
'''NOTE''': Broker agent instances cannot use file collections. If you want to use collections, distribute them and/or use them in the "real" agent that is used as a basis for the broker agent, not in one of its instances.
  
We want to monitor the basic parameters of a machine (CPU, memory and harddrive) and an installed database which that we want to monitor separately.
+
{{Warning|Modules that save data in memory between executions (module_logevent and module_regexp in MS Windows®) do not work when there are broker agents configured.}}
  
To perform this monitoring, we are going to use the following structure:
+
=== Broker mode use Examples ===
  
* Installed Software Agent: monitoring CPU, memory and disk.
+
==== Monitoring a local Database as a different Agent ====
* Broker for the Database: monitoring internal status of the database.
 
  
We're going to install the software agent on the machine to monitor the CPU, memory and hard drive. We're also adding the following line in the software agent configuration:
+
As an example, there is a software agent installed that monitors the CPU, memory and disk of a computer that in addition executes a database. For independent monitoring, add the line:  
  
 
  broker_agent DBApp
 
  broker_agent DBApp
  
We're going to create a broker agent called 'DBApp' by adding this line. Because of it's creation, a configuration file named 'dbapp.conf' will appear. We're adding the modules to perform the checks for the database in this configuration file:
+
With that you create a broker agent with name DBApp that generates the configuration file dbapp.conf. There add, to monitor the database (number of connected users and number of slow connections):
  
 
  module_begin
 
  module_begin
Line 819: Line 527:
 
  module_end
 
  module_end
  
By doing this, you're going to see two agents in the Pandora web console: One bearing the name of the machine with the modules 'CPU', 'Memory' and hard drive and another one called 'DBApp' with the modules 'Num Users' and 'Num slows queries'.
+
Pandora FMS console will show one with the name of the machine and CPU, memory and disk modules, and in addition another called DBApp with the modules Num Users and Num slows queries.
  
===== Remotely Monitor Devices using Brokers =====
+
==== Monitoring Devices Remotely Using Brokers ====
  
For this example, we've installed a software agent on a Windows machine, monitoring CPU, memory and hard drive. We're also required to monitor a router with the IP '192.168.100.54' without being allowed to install an agent on it. To solve the problem, we can use brokers.
+
As an example, there is a software agent installed in a machine with MS Windows®, that monitors CPU, memory and disk. You need to monitor a router with IP 192.168.100.54 without installing an agent on it. For that create a broker using the following parameter:
 
 
We're going to create a broker using the following parameter:
 
  
 
  broker_agent routerFloor5
 
  broker_agent routerFloor5
  
By adding this line, we're going to create a broker agent by the name of 'routerFloor5'. The software agent was installed on a Windows machine, so we're able to monitor the router by using the ping and SNMP modules available for Windows software agents. To do that, modify the file 'routerFloor5.conf' by adding the following lines:
+
With that you create the broker agent named as routerFloor5'. Then in the file routerFloor5.conf, modify the lines to store the ping and snmp modules available:
  
 
  module_begin
 
  module_begin
Line 859: Line 565:
 
  module_end
 
  module_end
  
In this example, the web console of Pandora FMS shows two agents: One is the Windows machine with the modules 'CPU', 'Memory' and 'hard drive' and the other one is 'routerFloor5' bearing the modules named 'Ping', 'Eth 1 up' and 'Eth 2 up'.
+
The web console will show two agents: one is the Windows machine with the CPU, Memory and hard drive modules and the other one is routerFloor5 with the modules named "Ping", "Eth 1 up" and "Eth 2 up".
  
===== Remote Monitoring of a Network with limited Communication Options =====  
+
==== Monitoring inaccessible networks remotely ====  
  
In some cases, it's required to monitor devices remotely where the Pandora FMS Remote Server can't access them directly.
+
In some cases, you need to monitor devices remotely where the Pandora FMS Remote Server cannot access them directly.
  
<center><br><br>
+
<br>
[[Image:Broker_example_no_access.png|790px]]
+
<center>
</center><br><br>
+
[[Image:Broker_example_no_access.png|center|790px]]
 +
</center>
 +
<br>
  
In this example, we have to monitor some devices from one of the company sites from the headquarters remotely. The Pandora FMS Server is connected to the other company sites in the headquarters using a VPN. Due to some restrictions, the Pandora Remote Server can't access the machines directly. To monitor the company sites, we're going to use the Broker Mode which allows a software agent to send XML files to the Pandora Server as if there would be several different devices.
+
The software agent in broker mode allows sending XMLs to Pandora FMS server as if they were different devices. For that you may add as many brokers as devices to be monitored, for example:
 
 
We add as many brokers as there are devices to be monitored. In the configuration file of the software agent, an example configuration could be:
 
  
 
  broker_agent device_1
 
  broker_agent device_1
Line 879: Line 585:
 
  ...
 
  ...
  
Once the brokers are created, we're able to customize the monitoring for each devices by modifying the configuration file of each broker. The configuration e.g. for the Windows machine called 'device_1' is:
+
Once the brokers are created, the monitoring for each device can be customized by modifying the configuration file of each broker as explained for each agent in remote check mode.
 
 
module_begin
 
module_name Ping
 
module_type generic_proc
 
module_ping 192.168.100.54
 
module_ping_count 2
 
module_ping_timeout 500
 
module_end
 
 
module_begin
 
module_name CPU_Load
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
 
module_wmicolumn LoadPercentage
 
module_end
 
 
module_begin
 
module_name Mem_Free
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Memory
 
module_wmicolumn FreeMemory
 
module_end
 
 
module_begin
 
module_name Disk_Free
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Disk
 
module_wmicolumn FreeSpace
 
module_end
 
 
 
We're able to use the remote configuration feature by a configuration like this. We're also able to send monitoring information to the Pandora FMS Server, despite the restrictions in the communication between the different company sites.
 
  
===== Shared Monitoring Load by Brokers =====
+
==== Shared Monitoring Load through Brokers ====
  
The broker mode is very useful to share and distribute the monitoring load within several network points.
+
[[Image:Broker_scalation_example.png|center|800px]]
  
<center><br><br>
+
The capacity of Pandora FMS remote server is around 2000 agents. Working with Broker agents you may raise it to 3000 and free the main server from most of the work. In the graph, each of the networks has a software agent with broker mode enabled, there you may create as many brokers as devices you have to monitor. For example, configuration for ''Broker_Agent_Net_A'' agent would be:
[[Image:Broker_scalation_example.png|800px]]
 
</center><br><br>
 
 
 
In this example, our architecture has several networks named from A to Z with a 1000 devices each. The capacity of the Pandora FMS Remote Server is about 2000 agents, because we've decided to use broker mode enabled software agents to share and distribute the load. These broker mode enabled software agents are going to remotely monitor all devices from the network and send the data in XML format to the Pandora FMS Central Server.
 
 
 
For each network, we have a broker mode enabled agent. On it, we're going to create as many brokers as the number of devices to be monitored. An example configuration for the software agent 'Broker_Agent_Net_A' could be the following:
 
  
 
  broker_agent device_1
 
  broker_agent device_1
Line 930: Line 599:
 
  ...
 
  ...
  
In addition for each broker, we're going to add the modules to monitor the devices. Example: The broker 'device_1' (which is a router) could have this configuration:
+
In addition, for each of the brokers, you would need to add the corresponding modules to monitor the devices as explained before.
  
module_begin
+
== Inventory using Software Agents ==
module_name Ping
 
module_type generic_proc
 
module_ping 192.168.100.54
 
module_ping_count 2
 
module_ping_timeout 500
 
module_end
 
 
module_begin
 
module_name Eth 1 up
 
module_type generic_data
 
module_snmpget
 
module_snmpversion 1
 
module_snmp_community public
 
module_snmp_agent 192.168.100.54
 
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.1
 
module_end
 
 
module_begin
 
module_name Eth 2 up
 
module_type generic_data
 
module_snmpget
 
module_snmpversion 1
 
module_snmp_community public
 
module_snmp_agent 192.168.100.54
 
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.2
 
module_end
 
  
Another example configuration for the broker 'device_2' which monitors a Windows machine with the following modules:
+
Pandora FMS Software Agents support inventory features for both hardware and software. The inventory system allows to keep a history of CPU, cards, RAM memory, patches, software, etc, used in the company servers. Furthermore, it is possible to generate alerts if there is a change in the inventory, e.g. if a disk was replaced or an application was uninstalled.
  
module_begin
+
For further information on the subject, please have a look at the section [[Pandora:Documentation_en:Inventory#Local_Inventory_through_Software_Agents| Local Inventory through Software Agents]].
module_name Ping
 
module_type generic_proc
 
module_ping 192.168.100.54
 
module_ping_count 2
 
module_ping_timeout 500
 
module_end
 
 
module_begin
 
module_name CPU_Load
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
 
module_wmicolumn LoadPercentage
 
module_end
 
 
module_begin
 
module_name Mem_Free
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Memory
 
module_wmicolumn FreeMemory
 
module_end
 
 
module_begin
 
module_name Disk_Free
 
module_type generic_data
 
module_wmiquery SELECT LoadPercentage FROM Win32_Disk
 
module_wmicolumn FreeSpace
 
module_end
 
  
Using broker mode enabled software agents, we're easily able to share the load to collect the data from thousands of devices.
+
==UDP remote commands==
  
=== Inventory using Software Agents ===
+
A software agent is capable of receiving remote requests and executing orders.
  
Pandora FMS Software Agents support inventory features for both hardware and software. The inventory system allows you to get a history of CPU, cards, memory, patches, software, etc, used in the company servers. Furthermore, it's possible to generate alerts if a change occurs in the inventory, e.g. if a disk was replaced or an application was deleted.
+
{{Warning|Bear in mind that UDP is unsafe by nature (but efficient to send messages without compromising a true response).}}
  
For further information on the subject, please have a look at the section [[Pandora:Documentation_en:Inventory#Local_Inventory_through_Software_Agents| Local Inventory by Software Agents]].
+
To allow Pandora FMS server to send order to Software agents in charge of it, configure:  
  
===UDP remote commands===
+
*'''udp_server''': it enables (1) or disables (0) this feature.
==== How to ask an Agent for On-Demand Information ====
+
*'''udp_server_port''': listening port of the UDP server in the software agent.
 +
*'''udp_server_auth_address''': IP address of Pandora FMS server.
  
Before the publication of version 3.2, there wasn't any way for asking the remote software agent for information. You were compelled had to wait for the agent to reach its interval limit to send its information. The Windows Agent 3.0 has a not very well known feature called "UDP Server" which allows to receive communication data from outside to ask for information and to force the agent to refresh its cycle which forces it to send the information to the Server.
+
Restart the software agent to apply changes.
  
In 3.2 version, we now have implemented the same feature called 'REFRESH AGENT' which is available under the UNIX agent as well. We also have included a 'default' alert template and commands, designed for easy handling. You now can setup your agents (for Windows and UNIX) to receive orders from the console to report the data immediately, without having to wait for it's interval any more.
+
{{Warning|Although it may be set to ''0.0.0.0'' for it to accept from all sources, said practice is not recommended. If you have serveral Pandora FMS servers and/or
 +
use IPv6, you may set different IPs separated by commas. For example, if you have in IPv6 <code>2001:0db8:0000:130F:0000:0000:087C:140B</code>, its abbreviation is <code>2001:0db8:0:130F::87C:140B</code> use both separated by commas.}}.
  
This feature is pretty simple. First, you're required to setup your agent (Windows or Linux) to accept outside connections on a specific UDP port, from a specific IP address (or 0.0.0.0 for anyone). Under Windows, you can also define other possible things the agent can execute as a result of a remote command. Under UNIX, the only supported operation (at this time) is "REFRESH AGENT". Klicking on it is going to result on an immediate agent execution which skips its interval.
+
===How to request software agent service restart ===
  
This is an example of the UDP server settings under the 3.2 Unix software agent:
+
Use the '''udp_client. pl''' script, present in the Pandora FMS server, and normally located in /usr/share/pandora_server/util. It can be run from the command line or used in an alert, making use of the command that is [[Pandora:Documentation_en:Alerts#Predefined_Commands|pre-configured]] in the '''"Remote agent control"''' console.
  
udp_server 1
+
There is also a default alert action called ''Restart agent'', on this script, using the action ''REFRESH AGENT''.
udp_server_port 41122
 
udp_server_auth_address 0.0.0.0
 
  
You may enable the server by setting the value of '1' and disable it with '0' under the 'udp_server' option. Please set '0.0.0.0' as source IP address to enable any IP.
+
[[Image:agent_restart_action.png|center|700px]]
  
This is an example of the UDP server settings under the 3.x Windows software agent:
+
Then force the alert's execution or force an incorrect status of the module for the alert to fire and thus check configuration.
  
udp_server 1
+
===Custom remote actions===
udp_server_port 41122
 
udp_server_auth_address 192.168.1.23
 
  
As you can see, it's exactly the same. In this case, we're going to use the IP address '192.168.1.23' as the only authorized one to refresh this agent.
+
Apart from the Refresh agent command, you can specify new and custom actions. For that, add a line for each command to execute, like the following:
  
The Pandora FMS Server has a small script which sends the order to the agent. In our default command, its fully operational and ready to be used. This script is written in Perl which acts as a small client to communicate with the simple UDP server, embedded in the agent and sends commands passed to the command line.
+
process_<nameoftheorder>_start comando
  
 +
For example, if you want a remote order to start the sshd service:
  
<center><br><br>
+
process_sshd_start /etc/init.d/sshd start
[[Image:Remote_agent_command.png|850px]]
 
</center><br><br>
 
  
To limit the possible values on a field, is possible to define a list of value/tag. If this list is defined, the field will be a selection combination.
+
Then create a new alert action at Pandora FMS Console for each remote command you made. You can copy the "Remote agent control" action, which is already prepared to send UDP commands. Set "START PROCESS sshdproc" on Field 1, as seen on the screenchot.
  
The format will be the following:
+
[[Image:Udp process.JPG|center|700px]]
  
value1,tag1;value2,tag2;value3,tag3
+
Now, you only need to set a new manual alert with the new alert action on the agent whose '''sshd''' service you wish to start. When the alert is forced, the order will be launched and the agent will start the service.
  
 +
{{tip|Custom orders can also be created to execute scripts. This allows a huge variety of remote actions to be performed on a remote agent just by clicking a button.}}
  
<center><br>
+
== Plugins in software agents ==
[[Image:fields.png|center|850px]]
 
</center><br><br>
 
  
We also provide a default alert template to assign "manual" alerts to an agent which means an alert will never be fired automatically. You're required to use the 'manual alerts' to force a manual alert execution by using the circle-shaped button on the agent's main view.
+
They are characterized by performing complex advanced checks from the software agents, '''being able to return several modules as a result''' instead of a single value. Unlike the server plugins, which are executed by Pandora FMS server, agent plugins return their data in an XML, reporting one or several modules at the same time.
  
 +
=== Execution on Windows systems ===
  
<center><br><br>
+
In Windows, all the default plugins are programmed in '''VBScript'''. To run them, it is vital to use the appropriate interpreter indicating the full path.  
[[Image:Alert_template_manual.png|850px]]
 
</center><br><br>
 
  
We have created a default alert action called "Restart Agent", which is going to call up the remote agent's command. This action attaches the REFRESH AGENT command to the command, and utilizes the main IP address of the agent to reach, using the default port for the UDP server (41122):
+
Here are some examples of how to use the default plugins included in the Windows agent:
  
 +
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\logevent_log4x.vbs" Application System 300
 +
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df.vbs"
 +
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" iexplore.exe myapp.exe
  
<center><br><br>
+
The Windows agent includes several ready-to-use plugins.
[[Image:agent_restart_action.png|850px]]
 
</center><br><br>
 
 
 
Please follow these steps to enable the Software Agent's remote refresh option:
 
 
 
1. In the configuration file, set up the options for the software agent (UNIX or Windows). Please be mindful on the authorized IP address (is the Pandora FMS server behind a NAT ?), or just put '0.0.0.0' in the field to allow any IP address to force a refresh of the agent.
 
 
 
2. Restart the software agent.
 
 
 
3. You need to setup the IP address on your agent item in the Pandora FMS console. The alert action will utilize the IP address to connect to the running software agent on the remote system.
 
 
 
4. Set an alert to any of the modules of that agent (no matter which), using this screenshot as a example guide:
 
 
 
 
 
<center><br><br>
 
[[Image:alert_restart_combinationsettings.png|800px]]
 
</center><br><br>
 
 
 
5. You're now ready to force a refresh for that agent using the main view, clicking on the green circle-shaped button on the left of the alert you've just defined:
 
 
 
<br>
 
<center><br>
 
[[Image:agent_refresh_button.png|800px]]
 
</center><br><br>
 
 
 
If you want to instantly get the agent's information without having to wait for the agent interval, just click in the button and wait a few seconds. The agent will be contacted and forced to execute, the XML file are going to be transferred to your Pandora FMS server and processed, depending on your system load. It will be processed in approx. 1-5 seconds and displayed on the console.
 
 
 
 
 
====Custom remote commands====
 
Apart from the Refresh agent command, you can specify new and custom actions to perform by the agents under the Pandora server's orders.
 
 
 
If you're interested, you need to make a slight modification in pandora_server.conf, apart from enabling udp server, as shown before:
 
 
 
udp_server 1
 
udp_server_port 41122
 
udp_server_auth_address <server IP>
 
 
 
Then you have to add a line for each custom command you want to perform, following this syntax:
 
process_nameofthecommand_start <command>
 
 
 
For example, if you wanted to create a custom command to start sshd service, you would have to add a line such as this:
 
process_sshdproc_start /etc/init.d/sshd start
 
  
Then you have to create a new alert action at Pandora Console for each remote command you made. You can copy the "Remote agent control" action, which is already prepared to send udp commands. Set "START PROCESS sshdproc" on Field 1.
+
=== Execution on Unix systems ===
Now you only need to set a new Manual alert with the new alert action on the agent whose sshd service you wanted to start. This way, you'll be able to send the start command just through manually forcing the alert.
 
  
 +
Unix plugins are by default in the directory "/etc/pandora/plugins" of the agent directory, so they are invoked and then the necessary parameters are sent:
  
{{tip|You can also create custom orders to execute scripts. This allows to perform a huge variety of remote actions on a remote agent just by clicking on "Force alert".}}
+
  module_plugin grep_log /var/log/syslog Syslog .
 +
  module_plugin pandora_df tmpfs /dev/sda1
  
=== Using Software Agent Plugins ===
+
The Unix software agent comes with several plugins by default ready to work.
  
Agent plugins are executed by the software agent and are able to report several information (modules) at once. Each plugin works in a different way and you should test how it works before using it. Default installation of Pandora FMS comes with a bunch of plugins. Of course, UNIX and Windows agents come with different plugins and some of them work very similar.
+
=== Software agent plugin management from the Console ===
  
==== On Windows Systems ====
+
In '''Enterprise''' version, it is possible to manage without directly editing the configuration file. When having remote configuration enabled, a software agent in its administration view will have the plugin editor tab.
  
Under the 3.2 version, the windows agents come with the following plugins:
+
[[Image:plugin_editor_tab.png|center|33px]]
  
* df.vbs: Reports the available harddrive space in bytes. It reports different modules for each harddisk that is found on the system. If you want to report the data of specific units only, just use the parameters after the 'module_plugin' call.
+
This section shows the list of plugins enabled within the agent, and allows deleting, adding and disabling them. Regarding policy plugins, it may be useful to deactivate them because when applying the policy again they will stay disabled.<br>
  
* df_percent.vbs: Very similar to previous the one, but it's going to report the available space in percent. It's going to generate modules with names like 'DiskFree_C'.
 
  
* logevent_log4x.vbs: Reads event-log entries and generates 'log4x' data.
+
[[Image:Plugin_editor_simple.png|700px|center]]
  
* ps.vbs: It requires process names and check if these processes are running. If you e.g. execute it with "iexplorer.exe mucommand.exe other.exe" it's going to check for three processes, returns different modules for each of them and reports if the proccesses are down or not.
+
Plugins managed by this editor may be, in turn, edited from the agent's configuration file.
  
Under Windows, all default plugins are coded in VBScript. You're going to need to use the correct interpreter for the VBScript Console (sometimes referred to as 'Windows Scripting Host') to run it.
+
[[Image:plugin_editor_conf.png|500px|center]]
  
These are some examples for the usage of the previous plugins:
+
=== Example 1 ===
  
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\logevent_log4x.vbs" Aplicacion System 300
+
Plugins for the software agent can return a piece of data or a group of data. An example of a plugin that returns a piece of data can be ''ps. vbs'' in a Windows environment, which simply checks whether a process is running.
 
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df.vbs"
 
 
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" iexplore.exe myapp.exe
 
 
 
==== On Unix Systems ====
 
 
 
Under version 3.2, the generic UNIX agent comes with following plugins:
 
 
 
* files_indir: This plugin receives a target directory, e.g. '/tmp' and returns two modules: One called 'FS_/tmp/' (boolean) which returns a value of '1' if it contains the same number of files as in the previous execution. The other module called 'NumFiles_FS_/tmp/' returns the number of files in that particular directory.
 
 
 
* grep_log: It's a generic log parser and it takes tree arguments: <file_to_process>, <module_name> and <reg_exp>. It will generate information inside an 'async_string' module type called <module_name>, using all data which match the <reg_exp> regular expression. For more information on this plugin, please look at the example below.
 
 
 
* pandora_df: It's very similar to the Windows plugin. It's going to report available space on all mounted partitions on the system. It also takes information from the NFS mounts. The information for all filesystems is returned, but one or more filesystems may be specified as plugin parameters by default.
 
 
 
These plugins are very similar to the Windows plugins. We're not required to use the full path to the plugins, because the 'module_plugin' directive looks for the plugin directory under the agent's home directory. We use the following syntax to execute them:
 
 
 
module_plugin grep_log /var/log/syslog Syslog .
 
 
module_plugin pandora_df tmpfs /dev/sda1
 
 
 
And some special plugins working under UNIX:
 
 
 
* nagios_plugin_wrapper: This is not really a plugin, it's just a wrapper, used to execute a Nagios plugin and to process the output to generate a Pandora module. It grabs the standard output, puts the results into the module description and gets the errorlevel to process a 'module_proc' (boolean) module by its results. Just call up the nagios plugin as a parameter to 'nagios_plugin_wrapper' with all its needed parameters and it's going to generate a Pandora FMS module.
 
 
 
* inventory: This is used in the inventory system. It will create an inventory XML with information about the system. It could be modified to gather different information, but by default, it only works under Linux and gets packages and services in the default runlevel and some other options. Please check out the inventory documentation for more information.
 
 
 
* pandora_update: This is used to utilize the autoupdate feature on the software agents. Please check out the agent configuration section for more information.
 
 
 
==== Examples using Plugins ====
 
 
 
The plugins for software agents are able to return one type of data or a group of them. An example of a plugin which only returns one data type could be the plugin 'ps.vbs' for Windows. We're going to execute the plugin by the following line:
 
  
 
  module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" IEXPLORE.EXE
 
  module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" IEXPLORE.EXE
  
The result will be a module which returns a value of '0' if the process is down and '1' if the process is running, e.g.:
+
The result will be a module that returns 0 if the process is not active and 1 if it is active:
  
 
  <module>
 
  <module>
 
     <name><![CDATA[IEXPLORE.EXE]]></name>
 
     <name><![CDATA[IEXPLORE.EXE]]></name>
 
     <description><![CDATA[Process IEXPLORE.EXE status]]></description>
 
     <description><![CDATA[Process IEXPLORE.EXE status]]></description>
     <data><![CDATA[1]]></data>
+
     <nowiki><data><![CDATA[1]]></data></nowiki>
 
  </module>
 
  </module>
  
An example of a plugin which returns several data could be the plugin 'df.vbs' for Windows. The line to execute the plugin could e.g. be:
+
===Example 2===
 +
 
 +
The plugin ''df. vbs'' in a Windows environments returns the free space in each storing device with the following order:
  
 
  module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df.vbs"
 
  module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df.vbs"
  
The plugin returns a module per found harrdrive. The result would be something like this:
+
Result:
  
 
  <module>
 
  <module>
 
     <name><![CDATA[C:]]></name>
 
     <name><![CDATA[C:]]></name>
 
     <description><![CDATA[Drive C: free space in MB]]></description>
 
     <description><![CDATA[Drive C: free space in MB]]></description>
     <data><![CDATA[8050]]></data>
+
     <nowiki><data><![CDATA[8050]]></data></nowiki>
 
  </module>
 
  </module>
 
   
 
   
Line 1,181: Line 723:
 
     <name><![CDATA[D:]]></name>
 
     <name><![CDATA[D:]]></name>
 
     <description><![CDATA[Drive D: free space in MB]]></description>
 
     <description><![CDATA[Drive D: free space in MB]]></description>
     <data><![CDATA[900]]></data>
+
     <nowiki><data><![CDATA[900]]></data></nowiki>
 
  </module>
 
  </module>
  
=== Local Plugins Editor ===
+
=== Advanced agent Plugin Management from the Console ===
  
Since version 5 of Pandora FMS, it's possible to manage the software agent's plugins from the console without the requirement of editing the configuration file directly.
+
{{Tip|Version NG 750 or higher.}}
  
If an agent has an enabled remote configuration, it's going to have the plugins editor tab in the 'Manage' view, as you can see in the screenshot below:
+
It is possible to add a token in the configuration of the plugin agent that when enabled allows the option of encapsulating the plugin definitions within the tags <code>module_begin</code> and <code>module_end</code>.
  
<center>
+
This enabled token allows inserting configuration clocks such as <code>module_interval</code> or <code>module_crontab</code>, among others.
<br><br>
 
[[image:plugin_editor_tab.png]]
 
<br><br>
 
</center>
 
  
The editor shows the plugins list and allows to delete, to add and to disable it. Disabling it under the plugins policy can be useful, because the plugins are still disabled if the policy is going to be applied again.
+
To enable this token, just go within agent management to agent plugin item and at the top of the configuration, you will find it under the name "Advanced".
  
<center>
+
[[Image:Plugin_editor_advanced2.png|800px|center]]
<br><br>
 
[[image:plugin_editor.png|750px]]
 
<br><br>
 
</center>
 
  
The managed plugins from this editor can be edited from the agent configuration file, too:
+
=== How to create custom software agent plugins ===
  
<center>
+
Plugins can be created in any programming language. Just bear in mind the [[Pandora:Documentation_en:Anexo_Plugins_Considerations|general rules]] and the specific rules for its development.
<br><br>
 
[[image:plugin_editor_conf.png|750px]]
 
<br><br>
 
</center>
 
  
=== How to Create your own Agent Plugins ===
+
Just respect the rules:
  
The plugins can be developed in any programming language, but they have to respect the following two restrictions:
+
* Regardless of what you want to do, it must be automatic (without user interaction), and it must be done from the shell. You can use any type of scripting language or compiled language, but in that case you must also distribute, in addition to the executable, all libraries (or DLL) that are necessary for the plugin to run.
  
* Whatever you want to do: It has to be completely automated (no interactive processing from the user) and must be done from the command line (shell). You're allowed to use any kind of scripting or compiled language, but you have to provide a stand-alone executable with all it's dependencies (libraries, dll, etc.) in this case.
+
* The plugin must return the information through the standard output (simply using echo, printf or the equivalent in the language that will be used for the plugin), and must use the XML format of Pandora FMS agents to return the information.  
  
* Plugin has to report the information to the standard output (just using 'echo', 'printf' or the equivalent in your language) and to use the XML syntax for the Pandora FMS agent information. This is an example of 'generic_data' (numerical information) in XML:
+
This is an example of a numerical module in XML:
  
 
  <module>
 
  <module>
 
  <name><![CDATA[Sample_Module]]></name>
 
  <name><![CDATA[Sample_Module]]></name>
 
  <type><![CDATA[generic_data]]></type>
 
  <type><![CDATA[generic_data]]></type>
  <data><![CDATA[47]]></data>
+
  <nowiki><data><![CDATA[47]]></data></nowiki>
 
  <description><![CDATA[47]]></description>
 
  <description><![CDATA[47]]></description>
 
  </module>
 
  </module>
  
The <![CDATA[xxx]]> is used to 'encapsulate' data and to protect the XML files from non-valid characters like ',', '&' or '%'.
+
The data contained in the <!CDATA[xxx]]> are used to protect XML from certain information that may contain "difficut" characters for XML, such as <, >, & or %.  
 
 
Please take a look at our Pandora FMS plugin library at http://pandorafms.org before trying to create your own plugin. If you want to create your own, please upload it to the Pandora FMS public library to allow others use your plugin when it's done.
 
  
 +
Before trying to create a plugin, visit the Pandora FMS plugin library at https://library.pandorafms.com, and if you decide to create your own plugin, send it to the public library, so that others can use it.
  
 +
{{warning|Make sure you finish the output of your plugin (if it is a script) with an error level 0, or the agent will think that the plugin has had an error and was not able to be run.}}
  
{{warning|Be sure to finish your custom plugin with an errorcode of 0, in other case, Pandora FMS agent will assume your plugin has an error and output will be discarded }}
+
==== Shellscript (Linux/Unix) plugin example ====
 
 
==== Sample plugin ====
 
  
 
<pre>
 
<pre>
Line 1,267: Line 795:
 
</pre>
 
</pre>
  
=== Using Nagios Plugins from the Agent ===
+
====  VBScript (Windows) plugin example ====
  
Nagios has a lot of amazing plugins you're free to use in conjunction with Pandora FMS. One way is to use remote plugins with the Plugin Server, using the Nagios compatibility, but they only receive it's status. They're not going to use the descriptive output that some Nagios plugins have.
+
<pre>
 +
' df.vbs
 +
' Returns free space for available drives.
 +
' --------------------------------------
  
Using the wrapper to utilize Nagios plugins in the software agent will solve this problem. The wrapper comes with 3.2 Unix agent by default. An equivalent plugin for Pandora FMS Windows agents can be downloaded from our website at http://pandorafms.org resource library at [http://pandorafms.com/index.php?sec=Library&sec2=repository&lng=en&action=view_PUI&id_PUI=178]).
+
Option Explicit
 +
On Error Resume Next
  
What does the plugin wrapper for nagios plugins do ?
+
' Variables
 +
Dim objWMIService, objItem, colItems, argc, argv, i
  
It executes the nagios plugin, utilizes it's native parameters and converts the output into useful values for Pandora FMS. It has two kinds of information:
+
' Parse command line parameters
 +
argc = Wscript.Arguments.Count
 +
Set argv = CreateObject("Scripting.Dictionary")
 +
For i = 0 To argc - 1
 +
    argv.Add Wscript.Arguments(i), i
 +
Next
  
* Status information: 'NORMAL' ('1'), 'CRITICAL' ('0'), 'WARNING' ('2'), 'UNKNOWN' ('3') and 'OTHER' ('4'). It's going to use a 'proc' module by default, so the values 'NORMAL' and 'CRITICAL' are working by default. If you want to have information on 'WARNING' and 'OTHER' values, you're required to setup the module thresholds manually.
+
' Get drive information
 +
Set objWMIService = GetObject ("winmgmts:\\.\root\cimv2")
 +
Set colItems = objWMIService.ExecQuery ("Select * from Win32_LogicalDisk")
  
* Descriptive information: Usually string information. It's going to be put on the description field on the module. This is usually something like "OK: successfully logged in" or similar.
+
For Each objItem in colItems
 +
If argc = 0 Or argv.Exists(objItem.Name) Then
 +
If objItem.FreeSpace <> "" Then
 +
Wscript.StdOut.WriteLine "<module>"
 +
Wscript.StdOut.WriteLine "    <name><![CDATA[" & objItem.Name & "]]></name>"
 +
Wscript.StdOut.WriteLine "    <description><![CDATA[Drive " & objItem.Name & " free space in MB]]></description>"
 +
Wscript.StdOut.WriteLine "    <data><![CDATA[" & Int(objItem.FreeSpace /1048576) & "]]></data>"
 +
Wscript.StdOut.WriteLine "</module>"
 +
            Wscript.StdOut.flush
 +
End If
 +
End If
 +
Next
 +
</pre>
  
==== Example ====
+
=== Using Nagios plugins from the agent ===
  
You have a pop3 plugin (in '/tmp/check_pop3_login') with execution permissions, which checks if the pop3 account is working. By connecting to a remote host, send a user and password and see if everything is ok. This is a command line example:
+
Nagios has a large number of plugins that can be used with Pandora FMS. One way to do this is using remote plugins with the Plugin Server, using Nagios compatibility. But in this way, you will only get the statuses, since it does not use the descriptive output that some plugins for Nagios have.
  
/tmp/check_pop3_login  mail.artica.es [email protected].es mypass
+
Using the wrapper to use Nagios plugins in the software agent will solve this problem. The wrapper comes by default with the Unix 3.2 agent. An equivalent plugin for Pandora FMS Windows agents can be downloaded from [https://library.pandorafms.com/index.php?sec=Library&sec2=repository&lng=es&action=view_PUI&id_PUI=178 Pandora FMS resource library].
  
It's going to return something like this:
+
;General performance
  
OK: successfully logged in.
+
The wrapper executes the Nagios plugin, using its original parameters and turning the output into useful data for Pandora FMS. It has two types of information:
+
 
If it's -not- ok, will return something like this:
+
*Status information: taking into account [https://pandorafms.com/library/files_repository/1287139046.slerena.nagios_plugin_wrapper Nagios error levels]: NORMAL (1), CRITICAL (0), WARNING (2), UNKNOWN () and others (4). By default, they will use a proc module, so the NORMAL and CRITICAL values are working "by default". If you wish to have information about WARNING and other values, you must configure the module thresholds manually.
 +
 
 +
*Descriptive information: generally string information. It will be placed in the module description field. Usually something like:
 +
 
 +
<![CDATA["OK: successfully logged in"]]>
 +
 
 +
 
 +
== Monitoring with KeepAlive ==
  
Critical: unable to log in.
+
There is a special module in Pandora FMS called <code>keep_alive</code> used to alert about a software agent not sending information anymore (see previously [[#Remote_actions_through_UDP|Remote actions through UDP]]). Said alert takes place when it has not updated its last contact date in twice of its interval, firing and checking the monitor in critical status.
  
Using the wrapper is simple. Before the call up, you're just required to put in the wrapper and the module name you want:
+
{{Tip|The KeepAlive module can be created by itself from the console (although you may not have remote configuration enabled) and does not leave any trace in the pandora_agent.conf file.}}
  
/etc/pandora/plugins/nagios_plugin_wrapper sancho_test /tmp/check_pop3_login  mail.artica.es [email protected] mypass
+
Creation of a new "KeepAlive" module:
  
It's going to generate a full XML for the agent plugin:
+
[[Image:Keepalive.JPG|center|700px]]
  
<module>
+
performance in "NORMAL" status (verde):
<name>sancho_test</name>
 
<type>generic_proc</type>
 
<data>0</data>
 
<description><![CDATA[Critical: unable to log on]]></description>
 
</module>
 
  
Or:
+
[[Image:Keepalive1.png|center|700px]]
  
<module>
+
If the agent stops sending data (for this example you had a 1-minute interval), then it will automatically get triggered and change to CRITICAL status (red):
<name>sancho_test</name>
 
<type>generic_proc</type>
 
<data>1</data>
 
<description><![CDATA[OK: successfully logged in.]]></description>
 
</module>
 
  
The full entry in the 'pandora_agent.conf' will be something like this:
+
[[Image:Keepalive2.png|center|700px]]
  
module_plugin nagios_plugin_wrapper POP3_artica.es /tmp/check_pop3_login mail.artica.es [email protected] mypass
+
It is worth highlighting that if you have a remote module, for example, a Ping, in addition of the data reported by the agent, the KeepAlive would never fire, since we are updating the agent constantly through Ping. Apart from that it behaves like any other module: it can have an alert associated and it may be used for any other element such as reports, maps, etc.
  
In the module, this will be seen like this on a 'fail' event:
+
== Command screenshot monitoring ==
  
 +
<br>
 
<center>
 
<center>
 +
[[File:Snapshot 1.png|center|650px]]
 +
</center>
 
<br>
 
<br>
[[file:Sample_plugin_wrapper.png]]
+
 
 +
 
 +
Commands that have extensive outputs, such as ''top'' or ''netstat'' can be captured completely by a module and fully reproduced. The module must be configured as a text type.
 +
 
 +
{{Warning|In order for it to work like this, it is necessary to configure properly both Pandora FMS console (setup) and the agent that collects this information, making sure that it is untreated text.}}
 +
 
 +
In the console, activate the option:
 +
 
 +
<center>
 +
[[File:command_line_snapshot_setup.png|center]]
 
</center>
 
</center>
  
=== Monitoring with KeepAlive ===
+
== Image monitoring and visualization ==
 +
 
 +
This method allows you to define string type modules (<code>generic_data_string</code> or <code>async_string</code>) that contains images in text format with [https://docs.python.org/3/library/base64.html base64 encoding], being able to display that image instead of a specific result. This is stored as text information, and displayed in a different way, not as simple data, but by means of reconstructing an image when clicking in the special icon for screenshots:
 +
 
 +
[[Image:Snapshot_text 1.png|center|650px]]
 +
 
 +
To capture these images, just type a plugin that sends all the data, generating the necessary XML tags, and running the plugin as such, with the ''module_plugin'' directive. Example:
 +
 
 +
<pre>
 +
#!/bin/bash
 +
echo "<module>"
 +
echo "<name>Last football championship winner</name>"
 +
echo "<type>async_string</type>"
 +
echo "<data><![CDATA[data:image/jpeg;base64,/9j/4AAQSkZ....]]></data>"
 +
 
 +
// The previous data would be generated by a device/application rendering images in base64.
 +
 
 +
echo "</module>"
 +
</pre>
 +
 
 +
Save that content in a file in the agent (or distribute it with file collections) and run it as follows:
 +
 
 +
module_plugin <complete path to the file>
  
There is a special module. It has a unique kind called 'keep_alive' and is very useful to receive any information if there is no contact to the agent. It comes in handy if an agent has stopped to send its information and notifies us.
+
== Specific Monitoring for Windows ==
 +
 
 +
The software agent for Windows has specific features to make monitoring a lot easier. These features are explained with some examples. Common rules:
 +
 
 +
{{Tip|If the name of the process contains blank spaces, '''do not use <code>" "</code>'''. The name of the process must be the same shown in the Windows task administrator ( ''taskmngr'' ), including the extension .exe; it is important to '''respect uppercase and lowercase'''.}}
 +
 
 +
{{Tip|The Watchdog '''only works if the module is asynchronous'''.}}
 +
 
 +
=== Processes monitoring and process watchdog ===
 +
 
 +
==== Process monitoring ====
 +
 
 +
The parameter '''module_proc''' verifies whether a process with a preset name is running on this machine. The module definition is:
 +
 
 +
module_begin
 +
module_name CMDProcess
 +
module_type generic_proc
 +
module_proc cmd.exe
 +
module_description Process Command line
 +
module_end
  
If there is a module (local or remote) which gets information from the agent, the date of the last 'contact' is updated in a way there is always data. The agent is going to have its date of last contact updated. This can come in handy if the agent 'doesn't answer'. Any agent is considered 'dead' if it hasn't managed to get its data updated in the double of time of its interval, to be precise. If it has e.g. a 5 minutes interval and more than 10 minutes have been past since his last update, the agent is considered 'dead'.
+
If you want the software agent to immediately notify you if a process is not working, add the parameter '''module_async yes'''. In this case, the module definition would be:
  
In this moment, the KeepAlive module would appear. It would get fired and appears as a 'Critical' state on the monitor.
+
module_begin
 +
module_name CMDProcess
 +
module_type generic_proc
 +
module_proc cmd.exe
 +
module_async yes
 +
module_description Process Command line
 +
module_end
  
The configuration of this kind of modules is very easy. You're just required to create a new module kind called 'dataserver' e.g. in the following way:
+
==== Watchdog Process ====
  
<center><br><br>
+
The watchdog feature on Pandora FMS Agent for MS Windows® allows immediate response to the failure of a process and restarts it.
[[File:Keepalive create.png|center|650px]]
 
</center><br><br>
 
  
Once created (if the agent has data in its interval) it will always be in 'NORMAL' (green) status.
+
Example:
  
<center><br><br>
+
module_begin
[[File:Keepalive1.png|center|650px]]
+
module_name Notepad
</center><br><br>
+
module_type generic_data
 +
module_proc notepad.exe
 +
module_description Notepad
 +
module_async yes
 +
module_watchdog yes
 +
module_user_session yes
 +
module_start_command c:\windows\notepad.exe
 +
module_startdelay 3000
 +
module_retrydelay 2000
 +
module_retries 5
 +
module_end
  
If the agent stops sending data (in this example it has interval of 1 minute), it will pop up automatically and on 'CRITICAL' status (red):
+
Each time the notepad.exe process is deactivated and the command c:\windows\notepad.exe will be executed (see common rules at the beginning of the Windows section). The process reactivation will be attempted 5 times with an initial waiting time of 3 seconds and a waiting time between retries of 2 seconds in the user's active session.
  
<center><br><br>
+
=== Service monitoring and service watchdog  ===
[[File:Keepalive2.png|center|650px]]
 
</center><br><br>
 
  
Important: If we have a remote module, e.g. one ping apart from the data reported by the agent, the KeepAlive module will never pop up. We're continually updating the agent by the ping.
+
==== Service monitoring ====
  
Furthermore, the KeepAlive module works the same as any other. It could be associated to an alert and used for lots of other elements (reports, maps, etc.).
+
The '''module_service''' parameter verifies whether a specified service is running on the machine. The definition of this module is as follows:
  
=== Monitoring Command Snapshots ===
+
module_begin
 +
module_name Service_Dhcp
 +
module_type generic_proc
 +
module_service Dhcp
 +
module_description Service DHCP Client
 +
module_end
  
From the 4.0.3 version and above, this way to monitor allows administrators to use a special way to capture the output from commands which differs from the parsing of a single value or string. This module stores the information as text, but with the purpose of getting the exact output of the command, not as single data. It's going to show the same output format and contents like the one returned by the command.
+
If you want the software agent to warn you immediately when a service is down, add the parameter '''module_async yes''' (see common rules at the beginning of the Windows section):
  
An image always works better than words, so:
+
module_begin
 +
module_name Service_Dhcp
 +
module_type generic_proc
 +
module_service Dhcp
 +
module_description Service DHCP Client
 +
module_async yes
 +
module_end
  
<br>
+
==== Service watchdog ====
<center>
 
[[File:Snapshot 1.png|center|650px]]
 
</center><br>
 
  
This is the 'netstat -an' command output, captured by Pandora FMS after clicking on the special icon for the command snapshot. It's only available if we have a multiline text and a '''non-split''' output.
+
It works similarly to the process watchdog. Example:
  
<br>
+
module_begin
<center>
+
module_name ServiceSched
[[File:Snapshot 2.png|center|650px]]
+
module_type generic_proc
</center>
+
module_service Schedule
<br>
+
module_description Service Task scheduler
These are the different "snapshots" across a certain time. Pandora is only going to show information if the agent's information is different (data type continues to be of the 'generic_data_string' type here). It's -not- recommended, but if you want to store each single data string, you may use 'async_string'. The behaviour of showing information only when changes occur is perfect for reporting data on problems and to compare other events to the information contained in the command snapshot pertaining that period.
+
module_async yes
 +
module_watchdog yes
 +
module_end
  
To capture the command outputs in a snapshot, you're required to write a small plugin which sends all data with a 'module_plugin' syntax (including the XML tags) and executes the plugin as a standard plugin. This is an example which generates output for the 'netstat' command:
+
The watchdog definition for services has no need for any extra parameters because they are incorporated in the service definition.
  
<pre>
+
=== Basic Resource Monitoring ===
#!/bin/bash
 
echo "<module>"
 
echo "<name>netstat</name>"
 
echo "<type>generic_data_string</type>"
 
echo "<data><![CDATA["
 
netstat -an | grep LIST
 
echo "]]></data>"
 
echo "</module>"
 
</pre>
 
  
Please save this script contents in a file on the agent (or remotely distribute it along with file collections), execute it and use the syntax below:
+
This section describes how to monitor the basic variables of a Windows-based machine.
  
module_plugin <full path for file>
+
==== CPU Monitoring ====
  
The agent is going to generate a command snapshot for almost any command. Just replace 'netstat' with your command. Some useful suggestions for UNIX systems are e.g.:
+
The parameter '''module_cpuusage''' returns the CPU usage percentage. It is possible to monitor the CPU based on its ID with the following module definition:
  
  * top -b -n 1
+
  module_begin
  * ps aux
+
module_name CPU_1
  * vmstat 1 5
+
  module_type generic_data
  * who
+
  module_cpuusage 1
  * last -10
+
  module_description CPU usage for CPU 1
 +
  module_end
  
On Windows systems:
+
It is also possible to monitor the average CPU usage from all systems with the following module:
  
  * tasklist
+
  module_begin
  * netstat -an
+
  module_name CPU Usage
  * net start
+
  module_type generic_data
 +
module_cpuusage all
 +
module_description CPU Usage for all system
 +
module_end
  
{{tip|Remember that you're always required to do this within a script which is generating the XML file. If you do that by calling up a 'module_exec', each line reported by the command will be interpreted as a line with different 'data blocks' - and you cannot see it as a command snapshot anymore.}}
+
==== Memory Monitoring ====
  
 +
To monitor the memory, you can use two parameters: '''module_freememory''' which returns the amount of free memory in the system and '''module_freepercentmemory'''
 +
which returns the percentage of free memory.
  
=== Monitoring and visualization of images ===
+
Example module for '''module_freememory''':
  
This way of monitoring, available from v 6.0 SP4 onward, allows you to define modules which contain images in text format, coded in base64, displaying the image in place of a specific result. This is stored as text data, but it is visualized as a reconstructed image.
+
module_begin
 +
module_name FreeMemory
 +
module_type generic_data
 +
module_freememory
 +
module_description Non-used memory on system
 +
module_end
  
This is what a string output looks like with the content "data:image" (image in base64), captured by Pandora FMS, when you click on the 'capture image' icon:
+
An example module for '''module_freepercentmemory''':
  
<br>
+
module_begin
<center>
+
module_name FreePercentMemory
[[File:Snapshot_text 1.png|center|650px]]
+
module_type generic_data
</center><br>
+
module_freepercentmemory
 +
module_end
  
<br>
+
==== Hard drive monitoring ====
  
To capture images like this, you need to write a plugin which sends all the data and the required XML tags, and execute the plugin with the directive module plugin. The next example plugin generates an image output, as in previou example:
+
To monitor hard drive space, you may use two parameters: '''module_freedisk''' which returns the amount of available space and '''module_freepercentdisk''' which returns the percentage of available space. Both parameters require the monitored unit as an input. '''Do not forget the character <code>:</code>''', for example:
  
<pre>
+
module_begin
#!/bin/bash
+
module_name FreeDisk
echo "<module>"
+
module_type generic_data
echo "<name>Current league leader</name>"
+
module_freedisk C:
echo "<type>async_string</type>"
+
module_end
echo "<data><![CDATA[data:image/jpeg;base64,/9j/4AAQSkZ....]]></data>"
 
  
//the previous data would be generated by a device/application supplying images in base64.
+
Module example for '''module_freepercentdisk''':
  
echo "</module>"
+
module_begin
</pre>
+
module_name FreePercentDisk
 +
module_type generic_data
 +
module_freepercentdisk C:
 +
module_end
  
Save the content in a file on an agent (or distribute it with a file collection) and execute:
+
==== WMI queries ====
  
module_plugin <path completo al fichero>
+
Pandora FMS Software Agent allows you to retrieve information by using [[Pandora:Documentation_en:Architecture#The_WMI_Server|WMI]] queries, which is a source of data widely used to obtain external or system-related information.
  
=== Password protected groups ===
+
The software agent allows you to execute any local WMI query you want using the '''module_wmiquery''' parameter. To perform the query, WMI query is defined in the '''module_wmiquery''' parameter and the column that contains the information to be monitores with the '''module_wmicolumn''' parameter.
  
By default, when an agent sends data for the first time to the Pandora FMS Server it is automatically added to whatever group is defined in the agent's configuration file. This means that, in practice, anyone can add agents to any group as long as its name is known. This could be a problem if your Pandora FMS instance is shared by multiple clients or you need tight control over what is in each group.
+
For example, getting a list with the installed services:
  
Starting from version 6.0SP5, you can optionally configure a password for a group from the Pandora FMS Console. An agent will not be added to a group unless the right password is specified in the agent's configuration file. Bear in mind that if the agent already belongs to the group the password is not checked.
+
module_begin
 +
module_name Services
 +
module_type generic_data_string
 +
module_wmiquery Select Name from Win32_Service
 +
module_wmicolumn Name
 +
module_end
  
==== Example ====
+
Get the current CPU load using WMI:
  
To configure a password for a group, navigate to the group editor and click on ''edit'':
+
module_begin
 +
module_name CPU_Load
 +
module_type generic_data
 +
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
 +
module_wmicolumn LoadPercentage
 +
module_end
  
  <screenshot>
+
== Versions prior to 7 NG ==
  
Then enter the group password and save your changes:
+
=== Name of the agents ===
  
  <screenshot>
+
From Pandora FMS version 7, agents have an alias and a name or (single identifier). An agent configured by default will generate a name (or identifier) based on a pseudorandom hexadecimal string, and an alias (or visible name) based on the machine's hostname.
  
To add a new agent to this group, edit its configuration file (''pandora_agent.conf'') and append the following configuration option:
+
In previous versions, there was only the "name" of the machine, and the previous system fully supports Pandora FMS most modern versions, but if in the same Pandora FMS installation there are two agents with the same identifier (or names), the data from both data will get mixed or overwritten. That is why from version 7, the possibility of adding agents with different name but same alias was added.
  
  group_password <password>
+
To change this performance, use the following configuration tokens:
  
Finally, restart the agent. You should see the newly created agent in your Pandora FMS Console:
+
pandora_agent
 +
pandora_alias
  
  <screenshot>
+
by default, the configuration file does not use any of them, so it gets the machine's hostname as alias and a large random hexadecimal number as identifier or name. The agent's name is not visible (except for the agent's detailed view) and CANNOT be changed. The agent's alias cab ver changed at any time, without worrying about software agent configuration, since the one used for clearly identifying the agent is the agent's "name".
  
 
[[Pandora:Documentation_en|Go back to Pandora FMS documentation index]]
 
[[Pandora:Documentation_en|Go back to Pandora FMS documentation index]]

Latest revision as of 12:14, 9 March 2021

Go back to Pandora FMS documentation index


Contents

1 Monitoring with Software Agents

1.1 Monitoring with software agents

Agent-monitoring.png

Software agents are in execution in OS where they get information from. Each of the checks performed on the system, such as CPU usage, free memory or disk space correspond to a module. So for each module a single data is collected in each execution.

the software agent's own directives are useful to retrieve certain data directly from the operating system (e.g. CPU usage, memory, events, etc.), executing the operating system's own commands following instructions from predefined scripts. It is also possible to execute those commands directly as well as any other software as long as data are returned in a standard way.

Pandora FMS Dataserver processes and stores in the database all the information generated by software agents, whcih send their data through and XML file.

Esquema-3.png
Logical outline of an agent/physical agent.

Info.png

If versions prior to 7 NG are executed, check software agent naming at the end of this article.

 


1.1.1 Agent Configuration

All the configuration and monitoring parameters of the software agents can be found in their configuration file pandora_agent.conf. This is stored locally in the machine where the software agent is installed, so any modification to be made in the agent must be reflected in this file. You have a detailed description of all agent configuration tokens in the chapter "PandoraFMS Agent Configuration" [1] while here we will only focus on the advanced uses of some of them.

1.1.1.1 Local configuration

In the software agent's configuration file, modules are defined with the following text basic structure:

module_begin 
module_name your module name
module_type generic_data
module_exec your command 
module_description your description
module_end
1.1.1.1.1 Example 1
module_begin 
module_name Files in var spool
module_type generic_data
module_exec ls /var/spool | wc -l
module_description Number of files incoming dir
module_end

In *nix environment, the command ls lists directory files and is executed with the line module_exec to deliver the value to the wc command, which will count the amount of words received for the same number of files. The value returned by this last execution will be the data that the module will obtain and will be displayed in the monitoring.

1.1.1.1.2 Example 2
module_exec vmstat 1 2 | tail -1 | awk '{ print $13 }'

The vmstat command reports virtual memory statistics. In this examples there are two additional commands to "refine" the desired information. It is recommended to first launch the command manually and analyze the output.

$> vmstat 1 2 | tail -1 | awk '{ print $13 }'

If the result satifies the requirement, it will be possible to add it to the configuration file. Later on the value returned by the execution through the software agent will be stored in the XML as module data.

1.1.1.1.3 Example 3

Any command or software can be executed through module_exec while the output supports the values accepted by Pandora FMS (numeric, alphanumeric or boolean), so it is possible to indicate custom scripts:

module_exec myScript.pl --h 127.0.0.1 -v cpu

Again, the agent will execute the shell and will retrieve the result, as if it was executed by an operator:

$> myScript.pl --h 127.0.0.1 -v cpu

1.1.1.2 Remote Configuration

On the Enterprise version, there is a remote Agent Configuration feature which allows centralized configuration and file management from the server console. This allows centralized management of all our software agents without the need to physically access the systems where they are installed.

The configuration consists of two files. Their file names are <md5>.conf and <md5>.md5, where <md5> is the agent's name hash code. Those files are stored in '/var/spool/pandora/data_in/conf' and '/var/spool/pandora/data_in/md5' folders respectively. The console is in charge of keeping said files synchronized in Pandora FMS server and the local ones accordingly, where each software agent is installed.


Sw-agent.png


To enable remote configuration, enable the corresponding parameter in the agent's local configuration file first. From this moment on, all the changes must be made from Pandora FMS console:

remote_config 1

Info.png

Once the agent's remote configuration is enabled, any changes made locally in the configuration file will be overwritten by the configuration stored in the console. If you want to prevent this from happening, stop the agent, modify the configuration file, disable the remote configuration and launch the agent again.

 


1.1.1.2.1 Custom Fields
Custom field manager for agents

Custom fields are an easy way to add additional agent information. Create custom fields by clicking on Resources -> Custom fields.

Info.png

You can include links in custom fields using the [url]link[/url] or [url=link]webname[/url] tags.

 


Display up front and Enabled combo fields are disabled by default:

"Display up front" and "Enabled combo" disabled
  • By activating the field Display up front, custom field information will be displayed in the agent's general view as shown below. In addition, enable this token to send Custom Fields information to the Metaconsole and be able to see it in the agent view and work in Custom Field View with this data.
"Display up front" activado


EqyIkxu4qJ.png
X1fYvcHCZt.png
  • Enabled combo: This parameter allows you to activate the configuration of selectable parameters from a drop-down list. Once activated, a new field will appear in the configuration window of the corresponding custom field to enter the combo values separated by commas.

Template warning.png

If the "Enabled combo" parameter is enabled, "Password type" will be disabled.

 


Custom fields can also be retrieved from the agent configuration file, using the following configuration token:

custom_field1_name Model
custom_field1_value i386

1.1.1.3 Common Configuration Parameters

Most important parameters for basic agent configuration (more details in Pandora FMS Software Agents):

  • server_ip: IP address of Pandora FMS Server.
  • server_path: Path of the 'incoming' folder for the Pandora FMS server (it's '/var/spool/pandora/data_in' by default).
  • temporal: Software agent's temporal folder (it is '/var/spool/pandora/data_out' by default).
  • logfile: Software agent's log file (it is '/var/log/pandora/pandora_agent.log' by default).
  • interval: Agent's execution interval (it is '300' by default).
  • intensive_interval: Intensive module execution interval (it is '300' by default).
  • debug: Enables (1) the debug mode, to save XML data files and analyze them. When it is activated, it does not send XML to the server and for execution, to be able to analyze the XML generated.
  • agent_name: Agent name (hostname is taken by default).
  • remote_config: Activation of remote configuration. It is disabled (0) by default. Only for Enterprise version.

An example in a *nix environment:

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

An example in a MS Windows® environment:

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

1.1.1.4 Password protected groups

By default, when an agent sends data for the first time to the Pandora FMS server, it is automatically added to the group that has been defined in the agent configuration file. This means that, in practice, anyone can add an agent to a group if they know the group name. This could be a problem if several clients share their Pandora FMS instance or if you want to control what is in each group.

We can optionally configure a password for a group from the Pandora FMS Console. An agent will not be added to a group unless the correct password has been specified in the agent configuration file.

1.1.1.4.1 Example

To set a password for a group, navigate to the group editor and click on edit, enter the group password and save your changes:

Passgr1.JPG

To add a new agent to this group, edit your configuration file and add the following configuration option:

 group_password <password>

Info.png

Do not forget to restart the agent to make the changes effective. The agent should be created correctly in the Pandora FMS console.

 




1.1.2 Modules in agents and software agents

1.1.2.1 Types of Modules

The following are the possible types of modules in software agents depending on the type of data returned:

  • generic_data: Numerical and floating point data.
  • generic_data_inc: A kind of increasing numerical data. Stores the difference between the previous and current data divided by the elapsed time in seconds, showing the rate per second. This type of data is used to count "number of times per second" of something, such as log entries/sec, receivedbytes/sec , incoming connections/sec , etc.
  • generic_data_inc_abs: Type of absolute increasing numerical data. It stores the difference between the previous and current data, without dividing it between the elapsed seconds, so the value will correspond to the total increase between the two executions, and not to the increase per second. This type of data is used to count the number of times something happens, such as log entries, total received bytes, number of incoming connections, and so on.
  • generic_proc: Boolean type of data, where a value of 0 means False or incorrect, and values above zero mean True or correct. The generic_proc types have the critical (0) and correct (1 or higher) states preconfigured.
  • generic_data_string: Kinds of alphanumeric data (text).
  • async_data: It is a kind of asynchronous numeric data. It is the same as 'generic_data' but for asynchronous data which is only updated if there is a change. The asynchronous kind of data do not have a defined periodicity when data can be obtained.
  • async_string: This is a kind of asynchronous alphanumeric data. It is the same as 'generic_string' but for asynchronous data which are only updated if there is a change. It is the kind of data that you are recommended to use if you want to monitor searches in logs or event viewers. New data can be obtained at any moment or not for several days.
  • async_proc: It is a kind of asynchronous boolean data. It is the same as 'generic _proc' but for asynchronous data which are only updated if there is a change.


  • Image module: They are based on a text string type module (generic_data_string or async_string). If the data in the module is a base64 image, in other words, part of the string contains "data:image", it will be identified as an image and, on the views that it appears, it will enable a link to open a window to display the image. Also on its historical data the strings that build/generate the images will be saved and displayed.

1.1.2.2 Intervals in local modules

The local modules (or software agent modules) all have the interval of their agent as a "base". However, they can take values that are multiple from that base if the module_interval parameter is modifies by multiplying with an integer higher than zero; for example:

module_interval 2

If an agent has an interval of 300. The interval's module will be 300x2 (600).

1.1.2.3 Module Creation Interface

Info.png

Feature exclusive for the Enterprise version; the according Software agent's remote configuration must be enabled.

 


Console local module creation is done through a form where, inn addition to the common configuration of any module (thresholds, type, group, etc. it has a text box where to specify the configuration data to be set in the Software agent configuration file.

Local module editor.png
  • By clicking on Load basic (template), the content of Data configuration will be deleted with a basic template that you must modify according to your monitoring needs.
  • Once modified, by clicking on Check (syntax) it will verify that the template's syntax stays correct, however the rest of the commands will not be checked.

When a module is loaded from a local component, it may have macros. If it has macros, the configuration box will stay hidden and a field will appear for each macro, see more information in Templates and components

1.1.3 Conditional Monitoring

1.1.3.1 Post-Conditions

Pandora FMS software agent supports the execution of commands and scripts as post-conditions. This means that actions could be performed depending on the value obtained in the execution of the module.

1.1.3.1.1 Example 1

With the module_condition parameter, a value or range of values and the execution to be carried out must be indicated in case the obtained data meets the terms (CPU usage under 200%):

module_begin
module_name CPU_Usage_Condition
module_type generic_data
module_exec get_cpu_usage.pl
module_condition < 20 add_processes.sh
module_end
1.1.3.1.2 Example 2

You can specify multiple conditions for the same module, in a range and with a minimum threshold (mathematically, one or none of both options is carried out):

module_begin
module_name CPU_Usage_Condition
module_type generic_data
module_exec get_cpu_usage.pl
module_condition (90, 100) remove_processes.sh
module_condition < 20 add_processes.sh
module_end
1.1.3.1.3 Example 3

Similar to the previous example, but both conditions can be executed or one or none (try with selected values: if it is 5, 15 or 30):

module_begin
module_name CPU_Usage_Condition
module_type generic_data
module_exec get_cpu_usage.pl
module_condition < 20 add_processes.sh
module_end

1.1.3.2 Pre-Conditions

The module_precondition parameter defines a precondition to evaluate before a module execution. Depending on the result of this precondition, the software agent will execute the module or not.

Info.png

You must mentally abstract to assign the value to module_precondition and then compare with the condition.

 


1.1.3.2.1 Example 1

According to CPU usage, if the active processes are more than ten, obtaining the CPU usage percentage and reporting to Pandora FMS server:

module_begin
module_name CPU_Usage
module_type generic_data
module_precondition > 10 number_active_processes.sh
module_exec get_cpu_usage.pl
module_end
1.1.3.2.2 Example 2

You can define multiple preconditions for the same module and all of them must be met:

module_begin
module_name CPU_Usage
module_type generic_data
module_precondition > 10 number_active_processes.sh
module_precondition > 1 important_service_enabled.sh
module_exec get_cpu_usage.pl
module_end

In this case, the module is executed only if there are more than ten active processes and if at least one of them is an important process.

1.1.4 Intensive Monitoring

There are certain specially important modules, such as critical running processes or services. Intensive monitoring enables more controlled monitoring of these particular cases.

It consists of warning in a shorter interval that a problem has arisen without reducing the agent's general interval.

Software agent configuration:

  • Interval: agent sampling time in seconds. This is the general range for all local modules. Required parameter.
  • Intensive_interval: time in which you will be notified of a problem on the especially critical modules. Optional parameter.

Module configuration:

  • module_intensive_condition = 0: if the module obtains as a result the value indicated in this parameter (in this case 0), it will be notified in the intensive interval defined in the agent.

1.1.4.1 Example

The sshd service is very important since it is used to connect by shell remotely, we need to monitor its working:

intensive_interval 10
interval 300
module_begin
module_name SSH Daemon
module_type generic_data
module exec ps aux | grep sshd | grep -v grep | wc -l
module_intensive_condition = 0
module_end

If the service fails, you will be notified in the next 10 seconds. If the service is up, you will be notified in the next 5 minutes, like normally (normal interval, 300 seconds).

1.1.5 Programmed Monitoring

The software agent supports the definition of programmed modules which are executed in the defined instances. The syntax used is the same as crontab. An example of module definition to execute it all Mondays from 12 to 15 hours:

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

To execute it in minute 10 of each hour:

module_begin
module_name crontab
module_type generic_data
module_exec script.sh
module_crontab 10 * * * *
module_end

Info.png

Note that if you use an interval that causes the module not to report data, this module will go into "unknown" status. Use asynchronous modules for these cases.

 


1.2 Remote Checks with Software Agents

When Pandora FMS main server does not have access to carry out remote checks (generally for security reasons), a software agent is able to take its place for such reasons and can even be distributed in broker agents.

1.2.1 ICMP Checks

ICMP or ping checks are very useful to know whether a machine is connected to a network or not. In this way, a single software agent could easily monitor the status of all machines.

UNIX

Using the system commands (all parameters in the "command line" module_exec):

module_begin
module_name Ping
module_type generic_proc
module_exec ping -c 1 192.168.100.54 >/dev/null 2>&1; if [ $? -eq 0 ]; then echo 1; else echo 0; fi
module_end

Note: Replace "192.168.100.54" by the IP address to be monitored.

MS Windows®

The parameters must be specified in module_ping_count (number of packets, 1 by default) and module-ping_timeout (time limit in seconds, 1 by default); example:

module_begin
module_name Ping
module_type generic_proc
module_ping 192.168.100.54
module_ping_count 2
module_ping_timeout 5
module_end

Note: module_advanced_options allows advanced options for ping.exe.

1.2.2 TCP Checks

TCP checks are useful to verify whether a port of a host stay open and allow to find out whether an application connects or not to the network.

UNIX

With the nmap command and its configuration parameters in the command line, to an IP address check whether port 80 is open (response waiting time of 5 seconds):

module_begin
module_name PortOpen
module_type generic_proc
module_exec nmap 192.168.100.54 -p 80 | grep open > /dev/null 2>&1; echo $?; if [ $? == 0 ]; then echo 1; else echo 0; fi
module_timeout 5
module_end


MS Windows®

Parameters must be specified in:

  • module_tcpcheck: Host to be checked
  • module_port: Port to be checked
  • module_timeout: Timeout for the check

Example:

module_begin
module_name TcpCheck
module_type generic_proc
module_tcpcheck 192.168.100.54
module_port 80
module_timeout 5
module_end


1.2.3 SNMP Checks

SNMP checks are commonly used to monitor network devices to check the interface status, inbound/outbound bytes, etc.

UNIX

If you are using the software agent for UNIX platforms, you may create the module using the snmpget command like this:

module_begin
module_name SNMP get
module_type generic_data
module_exec snmpget 192.168.100.54 -v 1 -c public .1.3.6.1.2.1.2.2.1.1.148 | awk '{print $4}'
module_end

This module returns the value for OID .1.3.6.1.2.1.2.2.1.1.148 on the '192.168.100.54' host.

MS Windows®

Parameter coniguration:

  • module_snmpversion [1,2c,3]: SNMP version (Default value is '1').
  • module_snmp_community <community>: SNMP community (Default value is 'public').
  • module_snmp_agent <host>: The host to monitor.
  • module_snmp_oid <oid>: OID.
  • module_advanced_options: Advanced options for 'snmpget.exe'.

Example that does the same as the previous 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.100.54
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.148
module_end

1.3 Proxy Mode

Template warning.png

To use Pandora FMS agent's proxy mode on Linux or UNIX systems, the agent must -not- be executed by a root user ! You are required to perform a custom installation of the Pandora FMS agent to do so. You may look up all the details about custom installations in the section Custom Agent Installation.

 


Pandora FMS Software Agents have a Proxy Mode which allows them to act other software agent proxies, redirecting the communication of several agents to the Pandora FMS Server. The software agent with an enabled proxy mode is able to perform monitoring tasks too.


Proxy-mode.png


The Proxy Mode was created for local area network where a single computer is exposed to the Internet, where Pandora FMS server is. It is necessary to monitor with software agents the rest of computers of that network; other computers will communicate with the proxy instead of with the server. The proxy mode also supports the Remote configuration and File collection features.

Parameter configuration:

  • server_ip: IP of the Pandora FMS Server.
  • proxy_mode: Enabled (1) or diabled (0).
  • proxy_max_connection: Maximum number of simultaneous connections for the proxy. The default value is '10'.
  • proxy_timeout: Proxy timemout. The default value is '1' (in seconds).
  • proxy_address: Address in which the proxy listens.
  • proxy_port: Port in which the proxy listens.

Example:

server_ip 192.168.100.230
proxy_mode 1
proxy_max_connection 20
proxy_timeout 3

To redirect the connection of a software agent, enter as Pandora FMS server address that of the agent with the Proxy Mode activated.

For example, the software agent in proxy mode has the IP address 192.168.100.24, the rest of the software agents must be configured with:

server_ip 192.168.100.24

1.4 Broker Mode

The software agent has a Broker Mode which allows one agent to monitor and manage the configuration as if there were several software agents installed:


Modo-broker.png


When the broker mode is activated in a software agent, a new configuration file is created. From that moment on, the original software agent and the new broker will be managed separately with their independent configuration files, as if they were two completely separate software agents on the same machine.

The main features of the Broker Mode are:

  • Sending local data as another agent. Very useful to monitor different software instances as different agents.
  • Sending the collected data from the remote checks to other machines as if a software agent had been installed on them.

To create a broker, add a line with the broker_agent <broker_name> parameter. It is possible to create as many broker agents as you wish, just by adding the corresponding broker_agent lines, as follows:

broker_agent dev_1
broker_agent dev_2

Once the brokers are created, the 'dev_1.conf' and 'dev_2.conf' configuration files will be created with the same content as in the original software agent, but with their corresponding name. By adding or deleting modules from 'dev_1.conf' and 'dev_2.conf' configuration files, you can customize the checks performed by the brokers.

On the Pandora FMS web console the brokers appear and will be managed independent agents, which means that if you have a software agent installed with two brokers, you will see three different agents with their modules, configurations, etc. on the web console.

NOTE: Broker agent instances cannot use file collections. If you want to use collections, distribute them and/or use them in the "real" agent that is used as a basis for the broker agent, not in one of its instances.

Template warning.png

Modules that save data in memory between executions (module_logevent and module_regexp in MS Windows®) do not work when there are broker agents configured.

 


1.4.1 Broker mode use Examples

1.4.1.1 Monitoring a local Database as a different Agent

As an example, there is a software agent installed that monitors the CPU, memory and disk of a computer that in addition executes a database. For independent monitoring, add the line:

broker_agent DBApp

With that you create a broker agent with name DBApp that generates the configuration file dbapp.conf. There add, to monitor the database (number of connected users and number of slow connections):

module_begin
module_name Num Users
module_type generic_data
module_exec get_db_users.pl
module_end

module_begin
module_name Num slows queries
module_type generic_data
module_exec get_db_slows_queries.pl
module_end

Pandora FMS console will show one with the name of the machine and CPU, memory and disk modules, and in addition another called DBApp with the modules Num Users and Num slows queries.

1.4.1.2 Monitoring Devices Remotely Using Brokers

As an example, there is a software agent installed in a machine with MS Windows®, that monitors CPU, memory and disk. You need to monitor a router with IP 192.168.100.54 without installing an agent on it. For that create a broker using the following parameter:

broker_agent routerFloor5

With that you create the broker agent named as routerFloor5'. Then in the file routerFloor5.conf, modify the lines to store the ping and snmp modules available:

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

module_begin
module_name Eth 1 up
module_type generic_data
module_snmpget
module_snmpversion 1
module_snmp_community public
module_snmp_agent 192.168.100.54
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.1
module_end

module_begin
module_name Eth 2 up
module_type generic_data
module_snmpget
module_snmpversion 1
module_snmp_community public
module_snmp_agent 192.168.100.54
module_snmp_oid .1.3.6.1.2.1.2.2.1.1.2
module_end

The web console will show two agents: one is the Windows machine with the CPU, Memory and hard drive modules and the other one is routerFloor5 with the modules named "Ping", "Eth 1 up" and "Eth 2 up".

1.4.1.3 Monitoring inaccessible networks remotely

In some cases, you need to monitor devices remotely where the Pandora FMS Remote Server cannot access them directly.


Broker example no access.png


The software agent in broker mode allows sending XMLs to Pandora FMS server as if they were different devices. For that you may add as many brokers as devices to be monitored, for example:

broker_agent device_1
broker_agent device_2
broker_agent device_3
broker_agent device_4
...

Once the brokers are created, the monitoring for each device can be customized by modifying the configuration file of each broker as explained for each agent in remote check mode.

1.4.1.4 Shared Monitoring Load through Brokers

Broker scalation example.png

The capacity of Pandora FMS remote server is around 2000 agents. Working with Broker agents you may raise it to 3000 and free the main server from most of the work. In the graph, each of the networks has a software agent with broker mode enabled, there you may create as many brokers as devices you have to monitor. For example, configuration for Broker_Agent_Net_A agent would be:

broker_agent device_1
broker_agent device_2
broker_agent device_3
broker_agent device_4
...

In addition, for each of the brokers, you would need to add the corresponding modules to monitor the devices as explained before.

1.5 Inventory using Software Agents

Pandora FMS Software Agents support inventory features for both hardware and software. The inventory system allows to keep a history of CPU, cards, RAM memory, patches, software, etc, used in the company servers. Furthermore, it is possible to generate alerts if there is a change in the inventory, e.g. if a disk was replaced or an application was uninstalled.

For further information on the subject, please have a look at the section Local Inventory through Software Agents.

1.6 UDP remote commands

A software agent is capable of receiving remote requests and executing orders.

Template warning.png

Bear in mind that UDP is unsafe by nature (but efficient to send messages without compromising a true response).

 


To allow Pandora FMS server to send order to Software agents in charge of it, configure:

  • udp_server: it enables (1) or disables (0) this feature.
  • udp_server_port: listening port of the UDP server in the software agent.
  • udp_server_auth_address: IP address of Pandora FMS server.

Restart the software agent to apply changes.

Template warning.png

Although it may be set to 0.0.0.0 for it to accept from all sources, said practice is not recommended. If you have serveral Pandora FMS servers and/or use IPv6, you may set different IPs separated by commas. For example, if you have in IPv6 2001:0db8:0000:130F:0000:0000:087C:140B, its abbreviation is 2001:0db8:0:130F::87C:140B use both separated by commas.

 

.

1.6.1 How to request software agent service restart

Use the udp_client. pl script, present in the Pandora FMS server, and normally located in /usr/share/pandora_server/util. It can be run from the command line or used in an alert, making use of the command that is pre-configured in the "Remote agent control" console.

There is also a default alert action called Restart agent, on this script, using the action REFRESH AGENT.

Agent restart action.png

Then force the alert's execution or force an incorrect status of the module for the alert to fire and thus check configuration.

1.6.2 Custom remote actions

Apart from the Refresh agent command, you can specify new and custom actions. For that, add a line for each command to execute, like the following:

process_<nameoftheorder>_start comando

For example, if you want a remote order to start the sshd service:

process_sshd_start /etc/init.d/sshd start

Then create a new alert action at Pandora FMS Console for each remote command you made. You can copy the "Remote agent control" action, which is already prepared to send UDP commands. Set "START PROCESS sshdproc" on Field 1, as seen on the screenchot.

Udp process.JPG

Now, you only need to set a new manual alert with the new alert action on the agent whose sshd service you wish to start. When the alert is forced, the order will be launched and the agent will start the service.

Info.png

Custom orders can also be created to execute scripts. This allows a huge variety of remote actions to be performed on a remote agent just by clicking a button.

 


1.7 Plugins in software agents

They are characterized by performing complex advanced checks from the software agents, being able to return several modules as a result instead of a single value. Unlike the server plugins, which are executed by Pandora FMS server, agent plugins return their data in an XML, reporting one or several modules at the same time.

1.7.1 Execution on Windows systems

In Windows, all the default plugins are programmed in VBScript. To run them, it is vital to use the appropriate interpreter indicating the full path.

Here are some examples of how to use the default plugins included in the Windows agent:

module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\logevent_log4x.vbs" Application System 300
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df.vbs"
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" iexplore.exe myapp.exe

The Windows agent includes several ready-to-use plugins.

1.7.2 Execution on Unix systems

Unix plugins are by default in the directory "/etc/pandora/plugins" of the agent directory, so they are invoked and then the necessary parameters are sent:

 module_plugin grep_log /var/log/syslog Syslog .
 module_plugin pandora_df tmpfs /dev/sda1

The Unix software agent comes with several plugins by default ready to work.

1.7.3 Software agent plugin management from the Console

In Enterprise version, it is possible to manage without directly editing the configuration file. When having remote configuration enabled, a software agent in its administration view will have the plugin editor tab.

Plugin editor tab.png

This section shows the list of plugins enabled within the agent, and allows deleting, adding and disabling them. Regarding policy plugins, it may be useful to deactivate them because when applying the policy again they will stay disabled.


Plugin editor simple.png

Plugins managed by this editor may be, in turn, edited from the agent's configuration file.

Plugin editor conf.png

1.7.4 Example 1

Plugins for the software agent can return a piece of data or a group of data. An example of a plugin that returns a piece of data can be ps. vbs in a Windows environment, which simply checks whether a process is running.

module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\ps.vbs" IEXPLORE.EXE

The result will be a module that returns 0 if the process is not active and 1 if it is active:

<module>
    <name><![CDATA[IEXPLORE.EXE]]></name>
    <description><![CDATA[Process IEXPLORE.EXE status]]></description>
    <data><![CDATA[1]]></data>
</module>

1.7.5 Example 2

The plugin df. vbs in a Windows environments returns the free space in each storing device with the following order:

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

Result:

<module>
    <name><![CDATA[C:]]></name>
    <description><![CDATA[Drive C: free space in MB]]></description>
    <data><![CDATA[8050]]></data>
</module>

<module>
    <name><![CDATA[D:]]></name>
    <description><![CDATA[Drive D: free space in MB]]></description>
    <data><![CDATA[900]]></data>
</module>

1.7.6 Advanced agent Plugin Management from the Console

Info.png

Version NG 750 or higher.

 


It is possible to add a token in the configuration of the plugin agent that when enabled allows the option of encapsulating the plugin definitions within the tags module_begin and module_end.

This enabled token allows inserting configuration clocks such as module_interval or module_crontab, among others.

To enable this token, just go within agent management to agent plugin item and at the top of the configuration, you will find it under the name "Advanced".

Plugin editor advanced2.png

1.7.7 How to create custom software agent plugins

Plugins can be created in any programming language. Just bear in mind the general rules and the specific rules for its development.

Just respect the rules:

  • Regardless of what you want to do, it must be automatic (without user interaction), and it must be done from the shell. You can use any type of scripting language or compiled language, but in that case you must also distribute, in addition to the executable, all libraries (or DLL) that are necessary for the plugin to run.
  • The plugin must return the information through the standard output (simply using echo, printf or the equivalent in the language that will be used for the plugin), and must use the XML format of Pandora FMS agents to return the information.

This is an example of a numerical module in XML:

<module>
<name><![CDATA[Sample_Module]]></name>
<type><![CDATA[generic_data]]></type>
<data><![CDATA[47]]></data>
<description><![CDATA[47]]></description>
</module>

The data contained in the <!CDATA[xxx]]> are used to protect XML from certain information that may contain "difficut" characters for XML, such as <, >, & or %.

Before trying to create a plugin, visit the Pandora FMS plugin library at https://library.pandorafms.com, and if you decide to create your own plugin, send it to the public library, so that others can use it.

Template warning.png

Make sure you finish the output of your plugin (if it is a script) with an error level 0, or the agent will think that the plugin has had an error and was not able to be run.

 


1.7.7.1 Shellscript (Linux/Unix) plugin example

#!/bin/bash
# Detect if local Mysql is without password
# First, do we have a running MySQL?
CHECK_MYSQL=`netstat -an | grep LISTEN | grep ":3306 "`
if [ ! -z "$CHECK_MYSQL" ]
then

        CHECK_MYSQL_ROOT=`echo "select 1234" | mysql -u root 2> /dev/null | grep 1234`
        if [ -z "$CHECK_MYSQL_ROOT" ]
        then
        echo "<module>"
        echo "<type>generic_proc</type>"
        echo "<name>mysql_without_pass</name>"
        echo "<data>1</data>"
        echo "<description>MySQL have a password</description>"
        echo "</module>"
        else
        echo "<module>"
        echo "<type>generic_proc</type>"
        echo "<name>mysql_without_pass</name>"
        echo "<data>0</data>"
        echo "<description>MySQL do not have a password</description>"
        echo "</module>"
        fi
fi

exit 0

1.7.7.2 VBScript (Windows) plugin example

' df.vbs
' Returns free space for available drives.
' --------------------------------------

Option Explicit
On Error Resume Next

' Variables
Dim objWMIService, objItem, colItems, argc, argv, i

' Parse command line parameters
argc = Wscript.Arguments.Count
Set argv = CreateObject("Scripting.Dictionary")
For i = 0 To argc - 1
    argv.Add Wscript.Arguments(i), i
Next

' Get drive information
Set objWMIService = GetObject ("winmgmts:\\.\root\cimv2")
Set colItems = objWMIService.ExecQuery ("Select * from Win32_LogicalDisk")

For Each objItem in colItems
	If argc = 0 Or argv.Exists(objItem.Name) Then
		If objItem.FreeSpace <> "" Then
			Wscript.StdOut.WriteLine "<module>"
			Wscript.StdOut.WriteLine "    <name><![CDATA[" & objItem.Name & "]]></name>"
			Wscript.StdOut.WriteLine "    <description><![CDATA[Drive " & objItem.Name & " free space in MB]]></description>"
			Wscript.StdOut.WriteLine "    <data><![CDATA[" & Int(objItem.FreeSpace /1048576) & "]]></data>"
			Wscript.StdOut.WriteLine "</module>"
            Wscript.StdOut.flush
		End If
	End If
Next

1.7.8 Using Nagios plugins from the agent

Nagios has a large number of plugins that can be used with Pandora FMS. One way to do this is using remote plugins with the Plugin Server, using Nagios compatibility. But in this way, you will only get the statuses, since it does not use the descriptive output that some plugins for Nagios have.

Using the wrapper to use Nagios plugins in the software agent will solve this problem. The wrapper comes by default with the Unix 3.2 agent. An equivalent plugin for Pandora FMS Windows agents can be downloaded from Pandora FMS resource library.

General performance

The wrapper executes the Nagios plugin, using its original parameters and turning the output into useful data for Pandora FMS. It has two types of information:

  • Status information: taking into account Nagios error levels: NORMAL (1), CRITICAL (0), WARNING (2), UNKNOWN () and others (4). By default, they will use a proc module, so the NORMAL and CRITICAL values are working "by default". If you wish to have information about WARNING and other values, you must configure the module thresholds manually.
  • Descriptive information: generally string information. It will be placed in the module description field. Usually something like:
<![CDATA["OK: successfully logged in"]]>


1.8 Monitoring with KeepAlive

There is a special module in Pandora FMS called keep_alive used to alert about a software agent not sending information anymore (see previously Remote actions through UDP). Said alert takes place when it has not updated its last contact date in twice of its interval, firing and checking the monitor in critical status.

Info.png

The KeepAlive module can be created by itself from the console (although you may not have remote configuration enabled) and does not leave any trace in the pandora_agent.conf file.

 


Creation of a new "KeepAlive" module:

Keepalive.JPG

performance in "NORMAL" status (verde):

Keepalive1.png

If the agent stops sending data (for this example you had a 1-minute interval), then it will automatically get triggered and change to CRITICAL status (red):

Keepalive2.png

It is worth highlighting that if you have a remote module, for example, a Ping, in addition of the data reported by the agent, the KeepAlive would never fire, since we are updating the agent constantly through Ping. Apart from that it behaves like any other module: it can have an alert associated and it may be used for any other element such as reports, maps, etc.

1.9 Command screenshot monitoring


Snapshot 1.png



Commands that have extensive outputs, such as top or netstat can be captured completely by a module and fully reproduced. The module must be configured as a text type.

Template warning.png

In order for it to work like this, it is necessary to configure properly both Pandora FMS console (setup) and the agent that collects this information, making sure that it is untreated text.

 


In the console, activate the option:

Command line snapshot setup.png

1.10 Image monitoring and visualization

This method allows you to define string type modules (generic_data_string or async_string) that contains images in text format with base64 encoding, being able to display that image instead of a specific result. This is stored as text information, and displayed in a different way, not as simple data, but by means of reconstructing an image when clicking in the special icon for screenshots:

Snapshot text 1.png

To capture these images, just type a plugin that sends all the data, generating the necessary XML tags, and running the plugin as such, with the module_plugin directive. Example:

#!/bin/bash
echo "<module>"
echo "<name>Last football championship winner</name>"
echo "<type>async_string</type>"
echo "<data><![CDATA[data:image/jpeg;base64,/9j/4AAQSkZ....]]></data>"

// The previous data would be generated by a device/application rendering images in base64.

echo "</module>"

Save that content in a file in the agent (or distribute it with file collections) and run it as follows:

module_plugin <complete path to the file>

1.11 Specific Monitoring for Windows

The software agent for Windows has specific features to make monitoring a lot easier. These features are explained with some examples. Common rules:

Info.png

If the name of the process contains blank spaces, do not use " ". The name of the process must be the same shown in the Windows task administrator ( taskmngr ), including the extension .exe; it is important to respect uppercase and lowercase.

 


Info.png

The Watchdog only works if the module is asynchronous.

 


1.11.1 Processes monitoring and process watchdog

1.11.1.1 Process monitoring

The parameter module_proc verifies whether a process with a preset name is running on this machine. The module definition is:

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

If you want the software agent to immediately notify you if a process is not working, add the parameter module_async yes. In this case, the module definition would be:

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

1.11.1.2 Watchdog Process

The watchdog feature on Pandora FMS Agent for MS Windows® allows immediate response to the failure of a process and restarts it.

Example:

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

Each time the notepad.exe process is deactivated and the command c:\windows\notepad.exe will be executed (see common rules at the beginning of the Windows section). The process reactivation will be attempted 5 times with an initial waiting time of 3 seconds and a waiting time between retries of 2 seconds in the user's active session.

1.11.2 Service monitoring and service watchdog

1.11.2.1 Service monitoring

The module_service parameter verifies whether a specified service is running on the machine. The definition of this module is as follows:

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

If you want the software agent to warn you immediately when a service is down, add the parameter module_async yes (see common rules at the beginning of the Windows section):

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

1.11.2.2 Service watchdog

It works similarly to the process watchdog. Example:

module_begin
module_name ServiceSched
module_type generic_proc
module_service Schedule
module_description Service Task scheduler
module_async yes
module_watchdog yes
module_end

The watchdog definition for services has no need for any extra parameters because they are incorporated in the service definition.

1.11.3 Basic Resource Monitoring

This section describes how to monitor the basic variables of a Windows-based machine.

1.11.3.1 CPU Monitoring

The parameter module_cpuusage returns the CPU usage percentage. It is possible to monitor the CPU based on its ID with the following module definition:

module_begin
module_name CPU_1
module_type generic_data
module_cpuusage 1
module_description CPU usage for CPU 1
module_end

It is also possible to monitor the average CPU usage from all systems with the following module:

module_begin
module_name CPU Usage
module_type generic_data
module_cpuusage all
module_description CPU Usage for all system
module_end

1.11.3.2 Memory Monitoring

To monitor the memory, you can use two parameters: module_freememory which returns the amount of free memory in the system and module_freepercentmemory which returns the percentage of free memory.

Example module for module_freememory:

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

An example module for module_freepercentmemory:

module_begin
module_name FreePercentMemory
module_type generic_data
module_freepercentmemory
module_end

1.11.3.3 Hard drive monitoring

To monitor hard drive space, you may use two parameters: module_freedisk which returns the amount of available space and module_freepercentdisk which returns the percentage of available space. Both parameters require the monitored unit as an input. Do not forget the character :, for example:

module_begin
module_name FreeDisk
module_type generic_data
module_freedisk C:
module_end

Module example for module_freepercentdisk:

module_begin
module_name FreePercentDisk
module_type generic_data
module_freepercentdisk C:
module_end

1.11.3.4 WMI queries

Pandora FMS Software Agent allows you to retrieve information by using WMI queries, which is a source of data widely used to obtain external or system-related information.

The software agent allows you to execute any local WMI query you want using the module_wmiquery parameter. To perform the query, WMI query is defined in the module_wmiquery parameter and the column that contains the information to be monitores with the module_wmicolumn parameter.

For example, getting a list with 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

Get the current CPU load using WMI:

module_begin
module_name CPU_Load
module_type generic_data
module_wmiquery SELECT LoadPercentage FROM Win32_Processor
module_wmicolumn LoadPercentage
module_end

1.12 Versions prior to 7 NG

1.12.1 Name of the agents

From Pandora FMS version 7, agents have an alias and a name or (single identifier). An agent configured by default will generate a name (or identifier) based on a pseudorandom hexadecimal string, and an alias (or visible name) based on the machine's hostname.

In previous versions, there was only the "name" of the machine, and the previous system fully supports Pandora FMS most modern versions, but if in the same Pandora FMS installation there are two agents with the same identifier (or names), the data from both data will get mixed or overwritten. That is why from version 7, the possibility of adding agents with different name but same alias was added.

To change this performance, use the following configuration tokens:

pandora_agent
pandora_alias

by default, the configuration file does not use any of them, so it gets the machine's hostname as alias and a large random hexadecimal number as identifier or name. The agent's name is not visible (except for the agent's detailed view) and CANNOT be changed. The agent's alias cab ver changed at any time, without worrying about software agent configuration, since the one used for clearly identifying the agent is the agent's "name".

Go back to Pandora FMS documentation index