Difference between revisions of "Pandora: Documentation en: Configuration"
(→(>= 7.0OUM13) transfer_mode_user) |
|||
Line 1: | Line 1: | ||
[[Pandora:Documentation_en|Go back Pandora FMS documentation index]] | [[Pandora:Documentation_en|Go back Pandora FMS documentation index]] | ||
− | + | ||
Pandora FMS has three basic components which must be properly configured for correct operation. The first two are the server and the web console, which should interact between each other and the database to introduce, to process and to show the stored data. There are also the software agents which transmit the data to the Pandora FMS server. | Pandora FMS has three basic components which must be properly configured for correct operation. The first two are the server and the web console, which should interact between each other and the database to introduce, to process and to show the stored data. There are also the software agents which transmit the data to the Pandora FMS server. |
Revision as of 09:14, 21 September 2017
Go back Pandora FMS documentation index
Pandora FMS has three basic components which must be properly configured for correct operation. The first two are the server and the web console, which should interact between each other and the database to introduce, to process and to show the stored data. There are also the software agents which transmit the data to the Pandora FMS server.
In this chapter, we are going to explain the configuration files of the three elements and others which are important for a correct performance of the application components.
Contents
- 1 Server
- 1.1 Configuration File Elements
- 1.1.1 servername
- 1.1.2 incomingdir
- 1.1.3 log_file
- 1.1.4 snmp_logfile
- 1.1.5 errorlog_file
- 1.1.6 dbname
- 1.1.7 dbuser
- 1.1.8 dbengine
- 1.1.9 dbpass
- 1.1.10 dbhost
- 1.1.11 dbport
- 1.1.12 daemon
- 1.1.13 verbosity
- 1.1.14 master
- 1.1.15 snmpconsole
- 1.1.16 networkserver
- 1.1.17 dataserver
- 1.1.18 reconserver
- 1.1.19 pluginserver
- 1.1.20 predictionserver
- 1.1.21 wmiserver
- 1.1.22 inventoryserver
- 1.1.23 exportserver
- 1.1.24 webserver
- 1.1.25 eventserver
- 1.1.26 icmpserver
- 1.1.27 snmpserver
- 1.1.28 network_timeout
- 1.1.29 server_keepalive
- 1.1.30 server_threshold
- 1.1.31 network_threads
- 1.1.32 icmp_checks
- 1.1.33 (> 5.1SP2) icmp_packets
- 1.1.34 tcp_checks
- 1.1.35 tcp_timeout
- 1.1.36 snmp_checks
- 1.1.37 snmp_timeout
- 1.1.38 snmp_proc_deadresponse
- 1.1.39 plugin_threads
- 1.1.40 plugin_timeout
- 1.1.41 wmi_timeout
- 1.1.42 wmi_threads
- 1.1.43 prediction_threads
- 1.1.44 recon_threads
- 1.1.45 dataserver_threads
- 1.1.46 inventory_threads
- 1.1.47 export_threads
- 1.1.48 web_threads
- 1.1.49 web_timeout
- 1.1.50 web_engine
- 1.1.51 mta_address
- 1.1.52 mta_port
- 1.1.53 mta_user
- 1.1.54 mta_pass
- 1.1.55 mta_auth
- 1.1.56 mta_from
- 1.1.57 mail_in_separate
- 1.1.58 xprobe2
- 1.1.59 snmpget
- 1.1.60 nmap
- 1.1.61 (> 5.1) nmap_timing_template
- 1.1.62 (> 5.1) recon_timing_template
- 1.1.63 plugin_exec
- 1.1.64 autocreate_group
- 1.1.65 autocreate
- 1.1.66 max_log_size
- 1.1.67 max_queue_files
- 1.1.68 use_xml_timestamp
- 1.1.69 auto_restart
- 1.1.70 restart
- 1.1.71 restart_delay
- 1.1.72 self_monitoring
- 1.1.73 (>= 5.1SP1) self_monitoring_interval
- 1.1.74 update_parent
- 1.1.75 icmp_threads
- 1.1.76 snmp_threads
- 1.1.77 block_size
- 1.1.78 braa
- 1.1.79 braa_retries
- 1.1.80 event_window
- 1.1.81 wmi_client
- 1.1.82 activate_gis
- 1.1.83 location_error
- 1.1.84 recon_reverse_geolocation_mode
- 1.1.85 recon_reverse_geolocation_file
- 1.1.86 recon_location_scatter_radius
- 1.1.87 google_maps_description
- 1.1.88 openstreetmaps_description
- 1.1.89 event_file
- 1.1.90 snmp_storm_protection
- 1.1.91 snmp_storm_timeout
- 1.1.92 text_going_down_normal
- 1.1.93 text_going_up_critical
- 1.1.94 text_going_up_warning
- 1.1.95 text_going_down_warning
- 1.1.96 text_going_unknown
- 1.1.97 event_expiry_time
- 1.1.98 event_expiry_window
- 1.1.99 (>= 5.X) snmp_forward_trap
- 1.1.100 (>= 5.X) snmp_forward_ip
- 1.1.101 (>= 5.X) snmp_forward_version
- 1.1.102 (>= 5.X) snmp_forward_secName
- 1.1.103 (>= 5.X) snmp_forward_engineid
- 1.1.104 (>= 5.X) snmp_forward_authProtocol
- 1.1.105 (>= 5.X) snmp_forward_authPassword
- 1.1.106 (>= 5.X) snmp_forward_privProtocol
- 1.1.107 (>= 5.X) snmp_forward_privPassword
- 1.1.108 (>= 5.X) snmp_forward_secLevel
- 1.1.109 (>= 5.1) claim_back_snmp_modules
- 1.1.110 (> 5.1) snmpconsole_threads
- 1.1.111 (> 5.1) translate_enterprise_strings
- 1.1.112 (> 5.1) translate_variable_bindings
- 1.1.113 (> 5.1SP1) async_recovery
- 1.1.114 (>= 6.0) console_api_url
- 1.1.115 (>= 6.0) console_api_pass
- 1.1.116 (>= 6.0) console_user
- 1.1.117 (>= 6.0) console_pass
- 1.1.118 (>= 6.0) unknown_interval
- 1.1.119 (>= 6.0) global_alert_timeout
- 1.1.120 (>= 6.0) remote_config
- 1.1.121 (>= 6.0) remote_config_address
- 1.1.122 (>= 6.0) remote_config_port
- 1.1.123 (>= 6.0) remote_config_opts
- 1.1.124 (> 6.0) warmup_event_interval
- 1.1.125 (> 6.0) warmup_unknown_interval
- 1.1.126 (> 6.0SP4) enc_dir
- 1.1.127 (> 6.0SP4) unknown_events
- 1.1.128 (>= 7.0) dynamic_updates
- 1.1.129 (>= 7.0) dynamic_warning
- 1.1.130 (>= 7.0) dynamic_constant
- 1.2 Snmptrapd configuration
- 1.3 Tentacle Configuration
- 1.4 Tentacle secure configuration
- 1.1 Configuration File Elements
- 2 WEB Console
- 3 Pandora FMS Software Agents
- 3.1 What is an Agent?
- 3.2 Introduction to the Agent Configuration
- 3.3 General Agent Parameters
- 3.3.1 server_ip
- 3.3.2 server_path
- 3.3.3 temporal
- 3.3.4 description
- 3.3.5 group
- 3.3.6 temporal_min_size
- 3.3.7 logfile
- 3.3.8 interval
- 3.3.9 disable_logfile
- 3.3.10 debug
- 3.3.11 agent_name
- 3.3.12 (>=5.1SP2) agent_name_cmd
- 3.3.13 (>=7.0) agent_alias_cmd
- 3.3.14 address
- 3.3.15 encoding
- 3.3.16 server_port
- 3.3.17 transfer_mode
- 3.3.18 (>= 6.0) transfer_timeout
- 3.3.19 server_pwd
- 3.3.20 server_ssl
- 3.3.21 server_opts
- 3.3.22 delayed_startup
- 3.3.23 pandora_nice
- 3.3.24 autotime
- 3.3.25 cron_mode
- 3.3.26 remote_config
- 3.3.27 xml_buffer
- 3.3.28 timezone_offset
- 3.3.29 parent_agent_name
- 3.3.30 agent_threads <threads>
- 3.3.31 include <filename>
- 3.3.32 broker_agent <name>
- 3.3.33 pandora_user <user>
- 3.3.34 (>= 5.X) custom_id
- 3.3.35 (>= 5.X) url_address
- 3.3.36 (>= 5.X) custom_fieldX_name
- 3.3.37 (>= 5.X) custom_fieldX_value
- 3.3.38 (> 5.1 Unix agent only) macro<macro> <value>
- 3.3.39 (>= 6.0SP5) group_password <password>
- 3.3.40 (>= 7.0) ehorus_conf <path>
- 3.3.41 (>= 7.0OUM13) transfer_mode_user <usuario>
- 3.4 Secondary Server
- 3.5 UDP Server
- 3.6 Modules definition
- 3.6.1 Common elements of all modules
- 3.6.1.1 module_begin
- 3.6.1.2 module_name <name>
- 3.6.1.3 module_type
- 3.6.1.4 module_min <value>
- 3.6.1.5 module_max <value>
- 3.6.1.6 module_min_warning <value>
- 3.6.1.7 module_max_warning <value>
- 3.6.1.8 module_min_critical <value>
- 3.6.1.9 module_max_critical <value>
- 3.6.1.10 module_disabled <value>
- 3.6.1.11 module_min_ff_event <value>
- 3.6.1.12 (>= 6.0 SP4) module_each_ff <value>
- 3.6.1.13 (>= 6.0 SP4) module_min_ff_event_normal <value>
- 3.6.1.14 (>= 6.0 SP4) module_min_ff_event_warning <value>
- 3.6.1.15 (>= 6.0 SP4) module_min_ff_event_critical <value>
- 3.6.1.16 (>= 6.0 SP4) module_ff_timeout <seconds>
- 3.6.1.17 module_description <text>
- 3.6.1.18 module_interval <factor>
- 3.6.1.19 module_timeout <secs>
- 3.6.1.20 module_postprocess <factor>
- 3.6.1.21 module_save <variable name>
- 3.6.1.22 module_crontab <minute> <hour> <day> <month> <day of the week>
- 3.6.1.23 module_condition <operation> <command>
- 3.6.1.24 module_precondition <operation> <command>
- 3.6.1.25 (>= 5.x) module_unit <value>
- 3.6.1.26 (>= 5.x) module_group <value>
- 3.6.1.27 (>= 5.x) module_custom_id <value>
- 3.6.1.28 (>= 5.x) module_str_warning <value>
- 3.6.1.29 (>= 5.x) module_str_critical <value>
- 3.6.1.30 (>= 5.x) module_warning_instructions <value>
- 3.6.1.31 (>= 5.x) module_critical_instructions <value>
- 3.6.1.32 (>= 5.x) module_unknown_instructions <value>
- 3.6.1.33 (>= 5.x) module_tags <value>
- 3.6.1.34 (>= 5.x) module_warning_inverse <value>
- 3.6.1.35 (>= 5.x) module_critical_inverse <value>
- 3.6.1.36 (>= 5.x) module_native_encoding <value>
- 3.6.1.37 (>= 5.x) module_quiet <value>
- 3.6.1.38 (>= 5.x) module_ff_interval <value>
- 3.6.1.39 (>= 5.x) module_macro<macro> <value>
- 3.6.1.40 (>= 5.1 SP4) module_alert_template <template_name>
- 3.6.1.41 module_end
- 3.6.2 Specific guidelines to obtain information
- 3.6.2.1 module_exec <command>
- 3.6.2.2 module_service <service>
- 3.6.2.3 module_proc <process>
- 3.6.2.4 module_cpuproc <process>
- 3.6.2.5 module_memproc <process>
- 3.6.2.6 module_freedisk <unit_letter:>|<volume>
- 3.6.2.7 module_freepercentdisk <unit_letter:>|<volume>
- 3.6.2.8 module_occupiedpercentdisk <unit_letter:>|<volume>
- 3.6.2.9 module_cpuusage <cpu id>
- 3.6.2.10 module_freememory
- 3.6.2.11 module_freepercentmemory
- 3.6.2.12 module_tcpcheck
- 3.6.2.13 module_regexp
- 3.6.2.14 module_wmiquery
- 3.6.2.15 module_perfcounter
- 3.6.2.16 module_inventory
- 3.6.2.17 module_logevent
- 3.6.2.18 module_plugin
- 3.6.2.19 module_ping <host>
- 3.6.2.20 module_snmpget
- 3.6.1 Common elements of all modules
- 3.7 Examples
- 3.8 Specific Configuration by Technologies
- 3.9 Pandora FMS Drone Agents
- 3.10 Agent / Module Autocreation from XML File / Learning Mode
- 3.11 Extended Module Information
1 Server
Pandora FMS server has a configuration file that allows several application parameters to be adjusted to obtain excellent performance. The configuration file pandora_server.conf is located at /etc/pandora/ by default.
1.1 Configuration File Elements
Pandora FMS configuration file is a UNIX standard plain text where the variables that aren't used or the comments are preceded by a "#" character. The comments must start the line and as for the entire line, the .conf file must not have any line which shares code and comment.
Now we are going to explain all the configuration parameters.
1.1.1 servername
Pandora FMS server name. If it's commented we should use the name of the equipment or "host". Please do not change the name of the server after executing it the first time because all reference goes linked to the name (remote agent modules and other information). If you change it, you're required to re-assign the server to all your agents.
1.1.2 incomingdir
It's the incoming directory of XML data packages. It's located under '/var/spool/pandora/data_in/' by default. You can improve the performance by setting up a RAM disk or very fast hard drive here.
1.1.3 log_file
The Pandora FMS record file (log). It's located under /var/log/pandora/pandora_server.log by default. This is the main logfile and it's very important for debugging.
1.1.4 snmp_logfile
Located under /var/log/pandora/pandora_snmptrap.log by default. This is a log file which contains all received SNMP traps BEFORE the Pandora FMS server processes them. It's not recommended to edit or even touch this file.
1.1.5 errorlog_file
The Pandora FMS error registry file (log). It's located under /var/log/pandora/pandora_server.error by default. This logfile stores all non-controlled errors or non-captured output from tools executed by the server. It's important for locating problems and debugging as well.
1.1.6 dbname
The name of the database the server will connect to. It's located under 'pandora' by default.
1.1.7 dbuser
Username used in the Pandora database connection. It's located under 'pandora' by default.
1.1.8 dbengine
Deprecated: always 'Mysql' (default value).
1.1.9 dbpass
The password for the connection against the Pandora FMS Database.
1.1.10 dbhost
The IP address or equipment name which hosts the Pandora FMS database. In reduced installations, it's usually the same equipment where the server is located, which is localhost.
1.1.11 dbport
It's used to define a different port in your database setup (optional).
1.1.12 daemon
It shows whether or not Pandora server is executed as a daemon. If the server is launched with the '–D' option, it's executed as daemon.
1.1.13 verbosity
The detail level for the server and error messages, the register or log files. 0: default, 1: detailed, 2: debug, 3-10: noisy. If you experience any problem with Pandora FMS, put this value to 10 to get the maximum detail. High values (e.g. 10) are not intended to be used in production systems because they have a great performance impact.
1.1.14 master
Master Server priority. The running server with the highest master value will be the master. Ties are broken at random. If set to 0, this server will never become master. See the High Availability (HA) chapter for more information.
1.1.15 snmpconsole
'1' enables the SNMP traps reception console, '0' disables it. The console depends on the snmptrapd UNIX service. Before starting Pandora FMS server, please make sure that the 'snmptrapd' process IS NOT running on your server.
1.1.16 networkserver
'1' enables the Pandora FMS Network Server, '0' disables it.
1.1.17 dataserver
'1' enables the Pandora FMS Data Server, '0' disables it. This server processes the XML files coming from the agents, among many other tasks. This server should be always running on the system.
1.1.18 reconserver
'1' enables the Pandora FMS Recon Server, '0' disables it. If you don't want to use the recon server, it's better to keep it disabled.
1.1.19 pluginserver
'1' enables the Pandora FMS Plugin Server, '0' disables it.
1.1.20 predictionserver
'1' enables the Pandora FMS Prediction Server, '0' disables it. Prediction server manages Services and synthetic modules, among others.
1.1.21 wmiserver
'1' enables the Pandora FMS WMI Server, '0' disables it.
1.1.22 inventoryserver
(Pandora FMS Enterprise only)
'1' enables the Pandora FMS Inventory Server, '0' disables it. It manages the remote inventory data. The inventory data transmitted by software agents is processed by the Data Server, so there's no need to enable this server unless you want to get inventory data from devices monitored remotely.
1.1.23 exportserver
(Pandora FMS Enterprise only)
'1' enables the Pandora FMS Export Server, '0' disables it.
1.1.24 webserver
(Pandora FMS Enterprise only)
'1' enables the Pandora FMS Web Server (also known as Goliath Server), '0' disables it.
1.1.25 eventserver
(Pandora FMS Enterprise only)
'1' enables the Pandora FMS Event correlation Server, '0' disables it (default value is '1').
1.1.26 icmpserver
(Pandora FMS Enterprise only)
Enables (1) or disables (0) the Enterprise ICMP server (default value is 0). The Enterprise ICMP server uses NMAP to perform block ICMP requests. The XML output of older versions of NMAP does not report round-trip time. If all your ICMP latency modules return a value of '0', please set this configuration variable to '0'. If the version is incorrect, please install NMAP 5.51 or higher. If you're unsure, you may run NMAP and see if the round-trip time is returned:
nmap -nsP -PE -oX - www.pandorafms.com | grep srtt
1.1.27 snmpserver
(Pandora FMS Enterprise only)
Enables ('1') or disables ('0') the Enterprise SNMP server (default value is '0'). The Enterprise SNMP server uses an external utility called braa to perform the block of SNMP queries. Modules which can't be processed by braa will be marked as uninitiated and handled by the Network server. If you experience additional problems with braa, simply set this configuration variable to '0'.
1.1.28 network_timeout
It's the timeout -in seconds- for the network server connections on network ICMP modules. Default value is 2 seconds. If you are performing remote checks on WAN networks, you probably should increase this value to avoid incorrect results.
1.1.29 server_keepalive
Time before classifying the server as 'down' in seconds. The default value is '45'.
1.1.30 server_threshold
The number of seconds for the main loop. Its value is '5' by default. This is a very important configuration token, because it defines how many times Pandora FMS looks into the database or on the hard drives for new data to process. '5' through '10' are good values in most cases - the minimum value is '1'. If you set it to '1', the system CPU load will be very high. You can set it to '1' in in specific cases, e.g. your server has been down for a while and you're required to process the pending XML files and network modules as quick as the system can. Set this to '1', wait for all pending modules / XML processes to be finished and set them to 5 - 15 again. This value, used in conjunction with 'server_threads' and 'max_queue_files', is used to adjust the performance of your server.
1.1.31 network_threads
Number of threads for the network server. It shows how many checks can be done at the same time, but as it increases it requires much more processing capacity. Its default value is 5. Please do not use more than 20 - 25 threads or the system could either get unstable or have very low performance.
1.1.32 icmp_checks
Defines the number of pings to each 'icmp_proc' kind of module. At least one of these checks has to give back '1' to the module for getting classified as correct. Its default value is '1'. If you set '5' here and the first ping is OK, the other 4 will be skipped.
1.1.33 (> 5.1SP2) icmp_packets
Defines the number of ICMP packets sent in each ping request. 1 by default.
1.1.34 tcp_checks
Number of TCP retries in case the first one fails. Its default value is 1.
1.1.35 tcp_timeout
Specific timeout for TCP connections. The default value is '30'.
1.1.36 snmp_checks
Number of SNMP retries in case the first one fails. The default value is '1'.
1.1.37 snmp_timeout
Specific expiration time for SNMP connections. Its default value is '3'.
1.1.38 snmp_proc_deadresponse
Gives back 'DOWN' if it's impossible to connect with a boolean SNMP module (proc) or if it gets 'NULL' as a response. If set to '0' it should be ignored.
1.1.39 plugin_threads
Number of threads for the plugin server. It shows how many checks could be done simultaneously. Its default value is '3'.
1.1.40 plugin_timeout
Timeout for the checks with plugins. After this time, the module status will be shown as 'unknown'. Its default value is 5, so you'll need to raise this value if your plugins' execution take a few seconds. If a plugin has a higher timeout value, the value set at this parameter of the server will prevail.
1.1.41 wmi_timeout
WMI timeout checks. After this time, the module status will be shown as 'unknown'. Its default value is '10'.
1.1.42 wmi_threads
Number of threads for the WMI server. It shows how many checks can be done simultaneously. Its default value is '2'.
1.1.43 prediction_threads
Number of threads for the prediction server.
1.1.44 recon_threads
Number of threads for the network recon server. Shows how many checks can be done simultaneously. Its default value is '2'.
1.1.45 dataserver_threads
Number of threads for the data server. Shows how many threads for XML processing can be active simultaneously. Its default value is '2'. Recommended max. is '4'.
1.1.46 inventory_threads
(Pandora FMS Enterprise only)
Number of threads assigned to the remote inventory server. It shows how many simultaneous threads are assigned to this component.
1.1.47 export_threads
(Pandora FMS Enterprise only)
Number of threads assigned to the export server. It shows how many simultaneous threads are assigned to this component.
1.1.48 web_threads
(Pandora FMS Enterprise only)
Number of threads assigned to the WEB test server. It shows how many simultaneous threads are assigned to this component.
1.1.49 web_timeout
(Pandora FMS Enterprise only)
Default timeout in seconds for web modules.
1.1.50 web_engine
(Pandora FMS Enterprise only)
Set this parameter to "curl" to use cURL instead of LWP for web monitoring. The cURL binary must be installed and set in PATH.
1.1.51 mta_address
Mail Server IP address (Mail Transfer Agent)
1.1.52 mta_port
Mail server port ('25' by default)
1.1.53 mta_user
Mail server user (if necessary for use with authentication)
1.1.54 mta_pass
Password for the mail server (if necessary with authentication)
1.1.55 mta_auth
Mail server authentication system (if necessary. The supported values are: 'LOGIN', 'PLAIN', 'CRAM-MD5' and 'DIGEST-MD')
1.1.56 mta_from
Mail address from which messages will be sent. The default value is [email protected].
1.1.57 mail_in_separate
'1' by default. If set to '1', it delivers separate mail for each destination. If set to '0', the mail will be shared among all destinations.
1.1.58 xprobe2
Used to determine the operating system of the remote systems, assigned to the agents when a recon network task is launched. The default path is /usr/bin/xprobe2. If not provided, NMAP will be used instead - it's much more imprecise, though.
1.1.59 snmpget
Required for SNMP checks. The default path is /usr/bin/snmpget. It refers to the location of the SNMP standard client for the system. It's recommended not to change this parameter unless you know exactly what you're doing.
1.1.60 nmap
Required for the recon server. The default path is /usr/bin/nmap. It's recommended not to change this parameter unless you know exactly what you're doing.
1.1.61 (> 5.1) nmap_timing_template
A value that specifies how aggressive nmap should be, from 1 to 5. '1' means slower but more reliable, '5' means faster but less reliable. '2' by default.
1.1.62 (> 5.1) recon_timing_template
Like nmap_timing_template, but applies to Satellite Server and Recon Server network scans.
1.1.63 plugin_exec
Shows the absolute path to the program which executes the plugins in a controlled way in time. The default path is /usr/bin/timeout. It's recommend not to change this parameter unless you know exactly what you're doing. If your base system doesn't have a timeout command, you should use the path /usr/bin/pandora_exec instead.
1.1.64 autocreate_group
Numeric ID of the default group for the new agents, created with the data server through the datafile reception. The default value is '2'.
1.1.65 autocreate
If you change this value to '1' the agents will be created automatically when processing a XML file which hasn't been sent by an existing agent. When set to '0', autocreation is disabled and XML files sent by unknown agents will be discarded, so they will have to be created by hand (bear in mind, agent names are case sensitive).
1.1.66 max_log_size
Maximum size of Pandora FMS log file, in bytes. When this size is reached, the log file's name is changed to pandora_server.log.old and the server generates a new one. Default size is 65536 Bytes.
1.1.67 max_queue_files
Maximum number of XML data files read by the Pandora FMS Data Server from the directory specified by incomingdir. This prevents the Data Server from trying to process too many files, which would affect server performance. Default value is 5000.
Incremental modules may not work properly if this value is not big enough to hold all the XML data files. |
|
1.1.68 use_xml_timestamp
Deactivated by default. If activated ('1') it uses the XML file timestamp, generated with time and date of the server in the moment of reception, instead of the internal XML file timestamp, which was generated by the server. This can be deactivated globally in case of conflict with the use of the dates generated by the agents and date / hour (timestamp) of the server as a reference for all data. In systems which experience problems with synchronization or systems with wrong date / hour, it's an option which could solve almost any problem.
1.1.69 auto_restart
Deactivated by default. If it's activated (value in seconds), it forces the server to do an internal restart each X seconds (1 day = '86400'). This option is useful if you observe a degradation or loss of control of any thread or specific server in use with Pandora FMS.
1.1.70 restart
Default value is '0'. If set to '1', the server will restart on critical errors after a given number of seconds.
1.1.71 restart_delay
Default value is '60'. The number of seconds the server will wait before restarting after a critical error if restart is enabled.
1.1.72 self_monitoring
The server has a self monitoring flag which creates a virtual agent in the server which monitors most of the important parameters of a Pandora FMS Server. To activate it, the parameter self_monitoring must be set to '1'.
1.1.73 (>= 5.1SP1) self_monitoring_interval
Time interval for self_monitoring in seconds.
1.1.74 update_parent
Although the server has a parameter to define if the agent can update it's parent by sending the parents name on the XML: If this parameter is not defined or set to '0', the agent information is ignored. If not, when the server receives an XML with 'parent_name' attribute, it is going to look for an agent with this name - and if it's found, it updates the parent of the agent from the XML.
1.1.75 icmp_threads
(Pandora FMS Enterprise only)
Number of threads for the ICMP Enteprise server (default value is '3').
1.1.76 snmp_threads
(Pandora FMS Enterprise only)
Number of threads for the Enteprise SNMP server (default value is '3').
1.1.77 block_size
(Pandora FMS Enterprise only)
Block size for block producer / consumer servers, which is the number of modules per block (default value is 15).
1.1.78 braa
(Pandora FMS Enterprise only)
Location of the braa binary required for the Enterprise SNMP server (default path is '/usr/bin/braa').
1.1.79 braa_retries
(Pandora FMS Enterprise only)
Number of retries before braa handles a module over to the Network Server in case of an error.
1.1.80 event_window
(Pandora FMS Enterprise only)
Event window: It's the time window (in seconds) in which the event server will look for events. For example, if set to '3600', the event server is going to check events generated within the last hour.
1.1.81 wmi_client
Default WMI client used (default value is 'wmic'). Changing this value is not recommended.
1.1.82 activate_gis
Flag to activate GIS (positional information for agents and maps). It's deactivated by default.
1.1.83 location_error
Radius of error in meters to consider two GIS locations as the same location.
1.1.84 recon_reverse_geolocation_mode
Recon reverse geolocation mode [disabled, sql, file]
- disabled The recon task doesn't try to geolocate the IP discovered.
- sql The recon task tries to query the SQL database to geolocate the IP discovered.
- file The recon task tries to find the geolocation information of the IP discovered in the file indicated in the 'recon_reverse_geolocation_file' parameter.
1.1.85 recon_reverse_geolocation_file
Recon reverse geolocation file. This is the database with the reverse geolocation information using MaxMind GPL (GeoLiteCity.dat format).
1.1.86 recon_location_scatter_radius
Radius (in meters) of the circle where the agents are randomly placed when found by a recon task. Center of the circle is guessed by geolocating the IP.
1.1.87 google_maps_description
This enables realtime reverse geocoding using Google Maps public API. This requires Internet access and could have performance penalties processing GIS information due to the connection needed to resolve all GIS input. NOTE: If you don't pay the Google, they are going to ban your IP in a few days.
1.1.88 openstreetmaps_description
This enables realtime reverse geocoding using Openstreet Maps public API. This requires Internet access, and could have performance penalties processing GIS information due the connection needed to resolve all GIS input. You can alter the code to use a local (your own) openstreet maps server.
1.1.89 event_file
This configuration token lets you configure a text file where events, generated by Pandora FMS, will be written in CSV format.
For example:
event_file /var/log/pandora/pandora_events.txt
The first line of the text file is a header containing a list of field names. The contents of pandora_events.txt could be:
id_agente,id_grupo,evento,timestamp,estado,utimestamp,event_type,id_agentmodule,id_alert_am,criticity,user_comment,tags,source,id_extra,id_usuario,critical_instructions,warning_instructions,unknown_instructions,ack_utimestamp Agent_1,Servers,Module Connections opened (136.00) is going to NORMAL,2013-07-01 19:00:57,1,1372698057,going_down_normal,Connections opened,,2,,,Pandora,,,,,,1372698057 Agent_2,Servers,Alert recovered (Critical condition) assigned to (Network Traffic (Outgoing)),2013-07-01 19:00:59,0,1372698059,alert_recovered,Network Traffic (Outgoing),Critical condition,4,,,Pandora,,,,,,0
1.1.90 snmp_storm_protection
Pandora FMS's SNMP Console will not process more than this number of SNMP traps from a single source in a defined time interval. If this number is reached, an event is generated.
1.1.91 snmp_storm_timeout
Time interval for snmp_storm_protection in seconds.
To e.g. prevent a single source from sending more than 1000 traps per 10 minutes:
snmp_storm_protection 1000 snmp_storm_timeout 600
1.1.92 text_going_down_normal
Text for the event that is generated when a module goes to normal status. The macros '_module_ and _data_' are supported.
text_going_down_normal Module '_module_' is going to 'NORMAL'(_data_)
1.1.93 text_going_up_critical
Text for the event which is generated when a module goes to 'critical' status.
1.1.94 text_going_up_warning
Text for the event which is generated when a module goes from 'normal' to 'warning' status.
1.1.95 text_going_down_warning
Text for the event which is generated when a module goes from 'critical' to 'warning' status.
1.1.96 text_going_unknown
Text for the event which is generated when a module goes to 'unknown' status.
1.1.97 event_expiry_time
Events older that the specified time (in seconds) will be auto-validated. Set to '0' to disable this feature.
To e.g. automatically validate events 10 hours after they were generated, just use the command:
'event_expiry_time 36000'
1.1.98 event_expiry_window
This parameter is used to reduce the impact of 'event_expiry_time' so the entire event table does not have to be searched. Only events more recent than the specified time window (in seconds) will be automatically validated. This value must be bigger than event_expiry_time.
The default value ('86400') is the equivalent of one day:
event_expiry_window 86400
1.1.99 (>= 5.X) snmp_forward_trap
Enables ('1') or disables ('0') the SNMP trap forwarding to the host specified in snmp_forward_ip.
1.1.100 (>= 5.X) snmp_forward_ip
IP address of the host to which SNMP traps will be forwarded to.
Bear in mind that setting a local IP address will cause a forwarding loop that is going to induce a collapse of the Monitoring Server. |
|
1.1.101 (>= 5.X) snmp_forward_version
SNMP version to use when forwarding SNMP traps. This token can only have the following values:
- 1
- 2c
- 3
1.1.102 (>= 5.X) snmp_forward_secName
Only for SNMP version 3. It defines the security name. More information at snmpcmd's man page.
1.1.103 (>= 5.X) snmp_forward_engineid
Only for SNMP version 3. It defines the authoritative (security) engine ID. More information at snmpcmd's man page.
1.1.104 (>= 5.X) snmp_forward_authProtocol
Only for SNMP version 3. It defines the authentication protocol. This token can only have the following values:
- MD5
- SHA
More information at snmpcmd's man page.
1.1.105 (>= 5.X) snmp_forward_authPassword
Only for SNMP version 3. It defines the authentication pass phrase. For more information, please go to snmpcmd's man page.
1.1.106 (>= 5.X) snmp_forward_privProtocol
Only for SNMP version 3. It defines the privacy protocol. This token can only have the following values:
- DES
- AES
More information at snmpcmd's man page.
1.1.107 (>= 5.X) snmp_forward_privPassword
Only for SNMP version 3. It defines the privacy pass phrase. More information at snmpcmd's man page.
1.1.108 (>= 5.X) snmp_forward_secLevel
Only for SNMP version 3. It defines the security level. This token can only have the following values:
- noAuthNoPriv
- authNoPriv
- authPriv
More information at snmpcmd's man page.
1.1.109 (>= 5.1) claim_back_snmp_modules
If set to 1, SNMP modules run by the Network Server will be claimed back by the SNMP Enterprise Server when the database maintenance script (pandora_db) is run.
1.1.110 (> 5.1) snmpconsole_threads
Number of threads for the SNMP Console. Each thread processes an SNMP trap. Set to '1' by default.
1.1.111 (> 5.1) translate_enterprise_strings
(Pandora FMS Enterprise only)
If set to 1 the SNMP console will attempt to translate enterprise strings when processing SNMP traps. Set to '1' by default.
1.1.112 (> 5.1) translate_variable_bindings
(Pandora FMS Enterprise only)
If set to 1 the SNMP console will attempt to translate variable bindings when processing SNMP traps. Set to '0' by default.
1.1.113 (> 5.1SP1) async_recovery
If set to 1 asynchronous modules that do not receive data for twice their interval will become normal. Set to 0 to disable.
1.1.114 (>= 6.0) console_api_url
Console's api direction. Usually the direction of the server and the console ending with the route /include/api.php.
1.1.115 (>= 6.0) console_api_pass
Password of the console's api. This password can be found in the general section of the setup and can be left empty.
1.1.116 (>= 6.0) console_user
User of the console with permissions to execute the required actions, like get a module graph image to put it in an alert email.
1.1.117 (>= 6.0) console_pass
Password of the previously introduced console user.
1.1.118 (>= 6.0) unknown_interval
Time interval (as a multiple of the module interval) before a module becomes unknown. Twice the module's interval by default.
1.1.119 (>= 6.0) global_alert_timeout
Defines -in seconds- the maximum processing time of an alert. When that time is elapsed, the execution is interrupted. By default, it is 15 seconds. If this token is set to 0, Pandora Server ignores it and the alert execution will not be interrupted.
1.1.120 (>= 6.0) remote_config
This parameter controls the possibility to configure the server remotely from the console Manage servers view. It works by Tentacle similarly to agents remote configuration. It's deactivated by default. This parameter, in addition to other remote configuration tokens, is only useful in the Enterprise version.
1.1.121 (>= 6.0) remote_config_address
Machine IP Address where remote configuration files will be sent. It is localhost by default.
1.1.122 (>= 6.0) remote_config_port
Tentacle port for remote configuration. It is 41121 by default.
1.1.123 (>= 6.0) remote_config_opts
Allows to give additional parameters to the Tentacle client for advanced configurations. They should be between "" (e.g. "-v-r 5").
1.1.124 (> 6.0) warmup_event_interval
Module status change events will not be generated and module alerts will not be executed for the specified number of seconds since the server starts up (disabled by default). System events will be generated when the warmup interval starts and ends, but the ending event will be delayed until a status change or an alert check occurs.
1.1.125 (> 6.0) warmup_unknown_interval
Modules will not become unknown (so no unknown events will be generated) and keepalive modules will not be set to 0 for the specified number of seconds since the server starts up (5 minutes by default). System events will be generated when the warmup interval starts and ends.
1.1.126 (> 6.0SP4) enc_dir
Path to a directory containing additional .enc files for the XML parser. This files will be automatically loaded by the Data Server at startup.
1.1.127 (> 6.0SP4) unknown_events
Enable (1) or disable (0) events related to the unknown module status.
1.1.128 (>= 7.0) dynamic_updates
The number of times dynamic thresholds will be recalculated per dynamic interval.
1.1.129 (>= 7.0) dynamic_warning
Percentage relative to the length of the critical interval used to calculate dynamic warning thresholds. The lower the value, the closer the critical and warning thresholds will be.
1.1.130 (>= 7.0) dynamic_constant
Percentage relative to the module's mean used to adjust the module's standard deviation for constant data. A higher value results in wider dynamic threshold intervals.
1.2 Snmptrapd configuration
The SNMP Console of Pandora FMS uses snmptrapd to grab SNMP traps. Snmptrapd is a standard tool, present on almost all UNIX systems, to grab traps and write a logfile. Pandora FMS configures snmptrapd to write a custom logfile and reads it every x seconds, executing alerts if defined.
Previously, snmptrapd will accept all incoming notifications, and log them automatically (even if no explicit configuration is provided). Starting with version 5.3, access control checks will be applied to incoming notifications.
If snmptrapd is running without a suitable configuration file (or equivalent access control settings), then such traps will not be processed.
You're probably required to configure your snmptrapd using the file /etc/snmp/snmptrapd.conf. If it doesn't exist, please check /var/log/pandora/pandora_snmp.log file for warnings or errors.
A basic snmptrapd.conf could be like:
authCommunity log public
If doesn't work on your linux distribution, please check your version syntax to enable the reception of traps in your snmptrapd daemon with
man snmptrapd.conf
1.3 Tentacle Configuration
By default, Pandora FMS software agents send the data packages to the server through the Tentacle protocol (Port 41121/TCP assigned by IANA [1]). The agent could also be reconfigured to send data in alternative ways: local transfer (NFS,SMB),SSH or FTP, etc. IF you want them to send the data packages using the Tentacle protocol, then you're required to configure a Tentacle server where this data is intended to be received. When a Pandora FMS server is installed, a Tentacle server is also installed in the same machine by default.
If it is necessary to adjust some parameters of the Tentacle server configuration, then it can be done by modifying the script that launches the Tentacle Server daemon directly which is in:
/etc/init.d/tentacle_serverd
Furthermore, there is a list of the different options for Tentacle Server configuration:
PANDORA_SERVER_PATH
The path to the entry directory of data. The default path is /var/spool/pandora/data_in
TENTACLE_DAEMON
The Tentacle daemon. The default command is 'tentacle_server'.
TENTACLE_PATH
The path to the Tentacle binary. The default path is '/usr/bin'.
TENTACLE_USER
User from which the Tentacle demon will be launched. The default value is pandora.
TENTACLE_ADDR
Direction to listen to the data packages. If you fix 0.0.0.0. it listens to all of them. The default value is to listen in all directions. This is true when it's IP is 0.0.0.0.
TENTACLE_PORT
The listening port for package reception. By default it's 41121 (official port assigned by IANA).
TENTACLE_EXT_OPTS
Additional options for executing the Tentacle server. You can set up Tentacle to use authentication with certs (x509) and/or symmetric password in both sides here.
1.4 Tentacle secure configuration
Both the server and the agents can use a secure configuration with SSL and/or password using Tentacle. The communication can be established tentacle_client -> tentacle_server, or tentacle_client -> tentacle_proxy -> tentacle_server.
The most common actions are:
Simple file transfer with password authentication (not secure):
Extra parameters in the tentacle server setup
-x password
Extra parameters in the client side (TENTACLE_EXT_OPTS)
-x password
Secure file transfer without client certificate:
Extra parameters in the tentacle server setup
-e cert.pem -k key.pem
Secure file transfer with client certificate:
Extra parameters in the tentacle server setup
-e cert.pem -k key.pem -f cacert.pem
Extra parameters in the client side (TENTACLE_EXT_OPTS)
-e cert.pem -k key.pem
Secure file transfer with client certificate and password authentication:
Extra parameters in the Tentacle Server setup
-x password -e cert.pem -k key.pem -f cacert.pem
Extra parameters on the client side (TENTACLE_EXT_OPTS)
-x password -e cert.pem -k key.pem
1.4.1 Secure configuration, real case
How to configure the agents and the Tentacle server for a secure connection, using Tentacle proxy as well.
Firstly, we recommend carrying out the previous testing manually from the shell terminal to make sure that the configuration, parameters and certificates are correct.
Manual testing:
1. Start tentacle_server manually:
sudo -u user tentacle_server -x password -e tentaclecert.pem -k tentaclekey.pem -f cacert.pem -s /tmp -v
2. Start proxy manually (only if you will use a Tentacle proxy, if not, skip this step):
sudo -u user tentacle_server -b ip_server -g 41124
3. Launch tentacle_client manually:
sudo -u user tentacle_client -a ip_proxy/ip_server -x password -e tentaclecert.pem -k tentaclekey.pem -v /bin/ls (or any file)
It is necessary to ALWAYS specify the absolute path where the certificates are stored, for example /home/tentaclecert.pem |
|
Once we have checked that the sending of the file has been successful, we can proceed to permanently configure tentacle_server and the clients.
To configure tentacle_server with the secure certificate options, you have to edit the starting script of the tentacle_serverd service, commonly on /etc/init.d/tentacle_serverd, the same for the intermediate proxy. To configure the agents to use the secure tentacle communication, you have to edit the configuration files of the agent pandora_agent.conf, commonly on /etc/pandora/pandora_agent.conf.
Permanent configuration:
1. Start the server with SSL. Modify the script /etc/init.d/tentacle_serverd. Search the line TENTACLE_EXT_OPTS, and add "-x password -e tentaclecert.pem -k tentaclekey.pem -f cacert.pem". It should look like this:
TENTACLE_EXT_OPTS="-i.*\.conf:conf;.*\.md5:md5;.*\.zip:collections -x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem -f /home/cacert.pem"
2. Start the proxy. Modify the script /etc/init.d/tentacle_serverd on the system that will act as a proxy. Same as in the previous step, search for the line TENTACLE_EXT_OPTS, and add "-b ip_server -g 41121". Like this:
TENTACLE_EXT_OPTS="-i.*\.conf:conf;.*\.md5:md5;.*\.zip:collections -b 192.168.70.208 -g 41121"
3. Launch the agent with the related options. Modify the pandora_agent.conf file, search the token server_opts and add "-x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem". Don't forget to set the token server_ip with the ip of the proxy instead of the main server if you use it. It should look like this:
server_opts -x password -e /home/tentaclecert.pem -k /home/tentaclekey.pem
If you don't want to use any of the options, like for example the password, just don't set it on the configuration. |
|
2 WEB Console
The Pandora FMS web console has a configuration file which usually is created and configured when it's installed. If the installation is done through the DEB or RPM packages or from the Pandora FMS installation CD, then it's configured automatically. If it's installed manually, it's contained in the tarball package. It could also be configured by the web assistant through http://ip_instalacion_consola/pandora_console/install.php
The configuration file config.php is in the directory '/include/' in the console installation directory. This could be '/var/www/pandora_console' (Debian, Ubuntu) or '/srv/www/htdocs/pandora_console/' (SUSE, RH, Fedora...), depending on the distribution.
2.1 Configuration File config.php
The configuration options in the file are contained in the header, and these are:
$config["dbname"]
Database name to connect to. The default value is 'pandora'.
$config["dbuser"]
User name for the connection against the Pandora database. The default value is 'pandora'.
$config["dbpass"] Password for the connection against Pandora FMS database.
$config["dbhost"]
IP address or equipment name which hosts the Pandora FMS database. In a reduced installation, it is usually on the same equipment as the server, which is 'localhost'.
$config["homedir"]
Directory where the Pandora FMS web console is located. This is usually '/var/www/pandora_console' or '/srv/www/htdocs/pandora_console'.
$config["homeurl"]
Base directory for Pandora FMS. This is usually '/pandora_console'.
$config["public_url"]
The full URL is set with the string value, the value is the URL of inside Pandora FMS Server if you use an inverse proxy e.g. 'mod_proxy' from Apache.
2.1.1 Redirection to '/pandora_console' from /
If you only have one Pandora FMS in your Apache server then it's possible that you could benefit by automatically re-addressing '/pandora_console' when users connect with the URL of their server. To do this, you could create the following file index.html and put it in the web server root directory ('/var/www' or '/srv/www/htdocs'):
For the case if users connect with the URL / of their server. You can create the following file index.html and put it in the web server's root directory:
<html> <head> <meta HTTP-EQUIV="REFRESH" content="0; url=pandora_console/index.php"> </head> </html>
3 Pandora FMS Software Agents
3.1 What is an Agent?
Pandora FMS software agents collect all data from their systems. They are executed on local systems, but they can also collect information remotely through the monitoring system's agent installation on several different machines.
They are developed to work with a fixed platform, using specific tools from the language which was used: VBScript / Windows scripting for Microsoft platforms (Windows 2000, Windows XP, Windows 2003 and Windows Vista), ShellScripting for UNIX including GNU/Linux, Solaris, AIX, HP-UX and BSD and also the Nokia IPSO. The Pandora FMS agents could be developed in any language as long as it is a system with an easy API and open code. There are modalities of the Pandora FMS project which have been started for agent creation in Posix, C, Perl and Java for systems which require closed agents.
Pandora FMS is 100% open code, e.g. in the way the agents collect and send information is documented and could analyze and / or modify the code to suit to your needs. An agent could be created again in any programming language and could also be easily updated to improve aspects of the program that hadn't been covered completely.
This document describes the agent installation in machines that work with Windows and UNIX operating systems.
3.1.1 General Role of Software Agents
The Software Agents general role is based on obtaining information about the operating system on which they are installed, to collect this information and send it to the Server.
Pandora FMS software agents use the specific commands of the operating system in order to obtain the information. The Pandora FMS Data Server keeps and processes the data generated by these commands and sends it to the server in an XML file.
The information returned by these commands is kept in what is called a 'Module'. If the agent has been added in 'learning mode', the modules which have been sent and which haven't been previously defined in the logical agent will be created automatically by the server.
3.2 Introduction to the Agent Configuration
The agent is controlled by a unique configuration file which has a syntax which is almost identical in UNIX systems as in Windows Systems. This file is named pandora_agent.conf and it's located in the agent installation directory (in Windows Systems) and under /etc/pandora/pandora_agent.conf in Unix systems.
This configuration file is a plain text file with different options which could all be modified by the administrator. To modify it or its performance, just configure where the data is supposed to get sent to, which things have to be monitored and how it's going to be done.
Configuration file encoding. It's very important and has to have the same value which is set in the encoding configuration parameter. If the encoding is set properly, the reception of data with improper encoding characters is going to be avoided. |
|
Now we're going to deal with all the general parameters for the Software Agent and the monitoring modules - which are the ones defining how and what is locally monitored with the Software Agent.
3.3 General Agent Parameters
The Configuration of the General Agent Parameters is defined in this section. Some of them are common for all systems and others are intended specifically for Windows or Unix machines. The general parameters are:
The first time the server receives data from an agent is going to save all of the information into the database. For the following received data it will only update (depending on learning mode status enabled/disabled) the following fields from XML file: version, date, OS version, and the following parameters from the configuration file: gis_exec, latitude, longitude, altitude parent_agent_name, timezone_offset, address and custom_field. |
|
3.3.1 server_ip
The IP address or the name of the Pandora FMS Server Host where all data will be stored. The server has to be prepared to collect the data either by SSH (listening on port 22), Tentacle (port 41121), FTP (port 21), SMB or NFS.
3.3.2 server_path
The server path is the comprehensive file path where the server stores all the data which was sent by the agent. The default path is '/var/spool/pandora/data_in'.
3.3.3 temporal
This is the complete path of the folder where the agent stores the local data before sending it to the server.
Remember! Data packages are deleted by default once the agent tries to contact with the Pandora FMS Server. Whether the connection was successful or not is not taken into account (although this function could be changed, as we see later).
This is done to prevent an overload on the hard drive of the host system where the agent runs. The location of the local file changes, depending on the architecture of the host system. Under UNIX systems it's usually at '/var/spool/pandora/data_out', and under Windows systems it's 'C:\program files\pandora_agent\temp'. The Windows installer is going to create this directory depending on where it decides to install Pandora FMS by default.
And under Windows systems, the Windows installer is going to create this directory by default, depending on where it decides to install Pandora FMS.
3.3.4 description
Sends the description of the agent in XML and Pandora FMS imports this description when it creates the Agent.
3.3.5 group
Sends the name of the group we want the agent to own, and that is only used in the moment the agent is created. The Pandora FMS Server will automatically use this group to put the agent in the selected group.
3.3.6 temporal_min_size
If the free space (in MB) of the partition in which the temporary directory is located is lower than this value, it would continue generating data packages. It avoids the disk becoming full if the connection with the server is lost during an extended interval under any circumstances.
3.3.7 logfile
The path to the Pandora FMS agent events record file. The file could be used to check the system and to investigate other things.
3.3.8 interval
This is the time interval (in seconds) in which the agent is going to collect data from the host system and send the data packages to the server. The range of recommended values constitutes from 300 (5 minutes) to 600 (10 minutes). This value could be bigger, but it's important to consider the impact of a higher value in the database. The execution is not recommended if it's configured to be below 30-60 seconds.
3.3.9 disable_logfile
This parameter disables log writing in pandora_agent.log. Only for Windows.
3.3.10 debug
This parameter is used to check the creation of data in the files, so the data content of the files could be checked. No data is destroyed when the process has been completed, so the data of the files will be at the temporary directory. The activity is registered in the registry file. The registry file is 'pandora_agent.log' (see logfile above).
Before Pandora 6.0, an agent in debug mode did not report to server.
3.3.11 agent_name
This is an alternative name for the host. This parameter is optional. This has not been declared but obtained directly from the system. The parameter could be used to overwrite the host name for another one in case of a conflict.
3.3.12 (>=5.1SP2) agent_name_cmd
If you want to define agent name using external command, set this parameter. This is optional. When this parameter is set, 'agent_name' is ignored. External command should return agent name string to STDOUT. If that returns several rows, the string in the first row is used as the agent name.
3.3.13 (>=7.0) agent_alias_cmd
If you want to define agent alias using external command, set this parameter. This is optional. When this parameter is set, 'agent_alias' is ignored. External command should return agent alias string to STDOUT. If that returns several rows, the string in the first row is used as the agent alias.
3.3.14 address
This is the IP address of the software agent. It could be an IP address with the format X.X.X.X or a domain name such as 'localhost' or 'auto'. If it's an IP address or a domain name, it will be added to the addresses of the agent and established as a main address. If the value is 'auto', it will obtain the IP address from the host and added to the agent as in the previous case.
3.3.15 encoding
Installs the kind of codification of the local system, such as ISO-8859-15 or UTF-8. This option is available for the UNIX and Windows agents from Pandora FMS 2.0.
3.3.16 server_port
This parameter allows to identify the remote port of the server that is waiting. By default it's 41121 for Tentacle. In case Tentacle is not used or that the server is configured to use another port, this is the place where it should be changed.
3.3.17 transfer_mode
This parameter specifies the transfer mode we have to install in order send the agent data to the server. The available modes are SSH (using SCP), Tentacle, FTP o local. The local mode is only for systems where the agent is executed in the same machine that the server, because it is basically an copy between directories. The local mode is available only for GNU/Linux agents.
3.3.18 (>= 6.0) transfer_timeout
This parameter specifies timeout in seconds for file transfer programs execution. The default value is '30' if not defined.
3.3.19 server_pwd
Specific for the password of Windows FTP and for the Tentacle transference mode, although the password at the last one is optional. Server password for authentication with password.
3.3.20 server_ssl
Specific for the Tentacle transfer mode. Allows to authorize ('1') or deny ('0) the connections which encrypt through SSL.
3.3.21 server_opts
Specific for the Tentacle transfer mode. Allows to give additional parameters to the Tentacle client for advanced configurations. For example: server_opts -v -r 5
Coming with the 3.2 agent version, tentacle supports the optional use of a HTTP proxy (using CONNECT) mode to send information to the server. This is implemented using an advanced option like this:
server_opts -y user:[email protected]:8080
This will force the tentacle client to use 'proxy.inet' on port 8080 using "user" and "pass" for authentication. If you intend to use a proxy on e.g. 192.168.1.2 on port 9000 without credentials, the command would have to be:
server_opts -y 192.168.1.2:9000
3.3.22 delayed_startup
This parameter allows the Pandora FMS agent to be configured in order to start working after any specific amount of time (in minutes) after manual execution. Useful for systems with a lot of load packages. It's deactivated by default, which means the Pandora FMS agent is going to start working from the moment it is executed manually. This option is only valid for UNIX agents.
3.3.23 pandora_nice
This parameter allows the priority the Pandora FMS agent process will have within the system to be specified. It's only available for Unix / Linux agents.
3.3.24 autotime
If it's enabled ('1') it sends a timestamp of special execution (AUTO) that makes the server use its local date / hour to establish the data hour, not paying attention to the hour sent by the agent. This is necessary in agents which have a wrong hour or a different hour from the server for any reason.
3.3.25 cron_mode
With this parameter, it's possible to make the agents using the Linux crontab functions to execute itself in a predetermined interval instead of using the agents internal system to execute itself at a certain time. It's deactivated by default and it's -not- recommended to use it unless it's an absolute necessity.
3.3.26 remote_config
This parameter controls the possibility to configure the agent remotely from the console. '1': The remote configuration is allowed. '0': The remote configuration is not allowed. It's deactivated by default.
3.3.27 xml_buffer
The default value is '0'. If set to '1', the agent is going to save any XML data files which couldn't be sent and retries later.
if you are in a secured environment under UNIX and want to enable the XML buffer, you should consider changing the temporal directory, since anyone has the right to write into '/tmp'.
An example of the general parameters from a UNIX configuration would be:
server_ip 192.168.1.1 server_path /var/spool/pandora/data_in temporal /var/spool/pandora/data_out logfile /var/log/pandora/pandora_agent.log interval 300 debug 0 agent_name box01 server_port 41121 transfer_mode tentacle remote_config 1
An example of the general parameters from a Windows configuration would be :
server_ip 192.168.1.1 server_path /var/spool/pandora/data_in temporal c:\archivos de programa\pandora_agent\temp interval 300 debug 0 agent_name box01 server_port 41121 transfer_mode tentacle remote_config 1
3.3.28 timezone_offset
The agent can set its timezone offset with the server now. It's very useful to have agents with a different timezone synchronized on the same time with a server in another timezone. Agents will send the shifted timezone to the server.
# Timezone offset: Difference with the server timezone timezone_offset 3
It is calculated by subtracting the agent's timezone from the server's timezone. For example, if the server's timezone is UTC+1 and the agent's timezone is UTC-5, the timezone offset should be 6 = 1 - (-5).
3.3.29 parent_agent_name
If the server allows it, it's also now possible to update the parent of an agent by sending the name of the parent agent in XML.
parent_agent_name parent_name
3.3.30 agent_threads <threads>
Number of threads the agent is going to launch to execute modules simultaneously. by default there is a single thread, to execute one module, and later the other, and go on until all of them are finished. This is only available in Unix agents.
3.3.31 include <filename>
This is the alternative configuration file path. This file can contain additional modules and collections alongside the ones found in the main configuration file. This token is optional. In matters related to perl agents, it allows for filename wildcards.
3.3.32 broker_agent <name>
It manages configuration and data collection from an agent as if they were be multiples of the same. A new configuration file is created for each broker agent added in the main configuration file with the name we have assigned to it. This token will be used only in the broker agent and not in the new agents created by it. These new agents will start reporting after the next execution. This token is optional.
3.3.33 pandora_user <user>
This parameter is optional and allows the agent to be executed with the specified system user. This user has to have permissions to execute the agent and all associated resources.
As we can see, most of the parameters from a Windows and a UNIX agent are the same.
3.3.34 (>= 5.X) custom_id
Custom ID of the agent for external applications.
3.3.35 (>= 5.X) url_address
Custom URL to open it from the agent in the console.
3.3.36 (>= 5.X) custom_fieldX_name
Name of an agent custom field which already exists on the system. If doesn't exist, it will be ignored.
Example:
custom_field1_name Model
3.3.37 (>= 5.X) custom_fieldX_value
Value for the custom field X defined in the previous parameter.
Example:
custom_field1_value C1700
3.3.38 (> 5.1 Unix agent only) macro<macro> <value>
It defines a local execution macro which can be used in the module definition. These kind of macros are used mostly in the metaconsole system, and in the local module component system to "abstract" the difficulty of use a local module, to not have to edit the source module definition. With these, a new field will appear in the GUI. The local execution macros have similar names to the local plugin macros: _field1_, _field2_....
Example:
module_begin module_name FreeDisk_opt module_type generic_data module_exec df -kh _field1_ | tail -1 | awk '{ print $5}' | tr -d "%" module_macro_field1_ /opt module_end
3.3.39 (>= 6.0SP5) group_password <password>
Password for the agent group. Leave commented if the group is not password protected.
3.3.40 (>= 7.0) ehorus_conf <path>
Absolute path to a valid eHorus agent configuration file. The agent will create a custom field named eHorusID that contains the eHorus agent's identifying key.
Sample:
ehorus_conf /etc/ehorus/ehorus_agent.conf (linux) ehorus_conf /usr/local/ehorus_agent/ehorus_agent.conf (mac) ehorus_conf "c:\program files\ehorus_agent\ehorus_agent.conf" (windows)
3.3.41 (>= 7.0OUM13) transfer_mode_user <usuario>
Usuario de los ficheros copiados en el modo de transferencia local. En las carpetas de la consola este usuario debe tener permisos de lectura y escritura para que funcione correctamente la configuración remota. Por defecto es apache.
3.4 Secondary Server
A special kind of general configuration parameter is the definition of a secondary server. This allows the definition of a server to send data to, in a complementary way to the standard definition of a server. The secondary server mode works in two different ways:
- on_error: Send data to the secondary server only in cases it could not send them to the primary one.
- always: Always send data to the secondary server, no matter if it's able to contact the main server or not.
Configuration example:
secondary_server_ip 192.168.1.123 secondary_server_path /var/spool/pandora/data_in secondary_mode on_error secondary_transfer_mode tentacle secondary_server_port 41121
3.5 UDP Server
The Pandora FMS Agent (both, Unix and Windows) allows the agent to be configured for listening to remote commands. This server listens on a user specified UDP port and allows orders to be received from a remote system - ideally from Pandora FMS through the execution of alerts on the server.
There are several options to configure the UDP remote server. The default file is pandora_agent.conf
- udp_server: To activate the UDP server, set it on '1'. This is deactivated by default.
- udp_server_port: Port where it listens.
- udp_server_auth_address: Authorized IP address to send orders. Several Addresses can be set separated by commas. If it is configured with 0.0.0.0, UDP Server will accept orders from all addresses. Nevertheless, for security reasons, please restrict the access to this agent from known IPs.
- process_<name>_start <command>: Command which is going to start a user-defined process.
- process_<name>_stop <command>: Command which is going to stop the process.
- service_<name> 1: Allows the service <name> to be started or stopped remotely from the UDP server.
Configuration Example:
udp_server 1 udp_server_port 4321 udp_server_auth_address 192.168.1.23 process_firefox_start firefox process_firefox_stop killall firefox service_messenger 1
The server accepts the following commands:
* <START|STOP> SERVICE <name of the service>: Starting or stopping a service. * <START|STOP> PROCESS <name of the process>: Starting or stopping a process. * REFRESH AGENT <name of the agent>: Forces one execution of the agent and refreshes data.
In 5.0 version, Unix agent only implements REFRESH AGENT command.
For example:
STOP SERVICE messenger START PROCESS firefox REFRESH AGENT 007
There is a script on the server at /util/udp_client.plwhich is used by the Pandora FMS Server as a command of an alert to start process or services. It has this syntax:
./udp_client.pl <address> <port> <command>
To e.g. restart an agent:
./udp_client.pl 192.168.50.30 41122 "REFRESH AGENT"
For more information, please go to the Alert Configuration section.
3.6 Modules definition
Each piece of information which is collected has to be perfectly defined in each module, using the most precise syntax. You can implement as many values as necessary in order to be collected, adding, at the end of the general parameters as many modules as the number of values to compile. Each module is composed of several directives. The list which appears below is a descriptive list of all available modules and signals for UNIX agents (almost all of them can also apply to the Windows agent).
The general syntax is the following:
module_begin module_name NombreDelMódulo module_type generic_data . . . module_description Ejecución del comando module_interval Número module_end
There are different kinds of modules, with different sub-options, but all modules have a structure similar to this. The parameters module_interval and module_description are optional and the rest of them completely compulsory. First, we're going to see the common elements.
3.6.1 Common elements of all modules
Module fields (except module data, description and extended info) are only stored on module creation and will never be updated if the module is already created. This behavior is identical to the agent's enabled learning mode. |
|
3.6.1.1 module_begin
Defines the beginning of the module (compulsory).
3.6.1.2 module_name <name>
Name of the module. This is the module ID. Please pick a name without blanks and not too long. There is no specific limitation (max. 250 characters), but a short name would be easier to work with. This name CANNOT be duplicated ' with a similar name in the same agent. This name could be duplicated with other modules in other agents. Just like in other chapters, Pandora FMS is case-sensitive.
3.6.1.3 module_type
The data type that the module is going to use. There are several data types for agents:
- Numerical (generic_data). Simple numerical data, in floating points or wholes. If the values are in the floating point type, they are going to be cut to their whole value.
- Incremental (generic_data_inc). Numeric data equal to the difference between the current value and the previous one divided by the elapsed time in seconds. When this difference is negative, the value is reset.
- Absolute incremental (generic_data_inc_abs). Numeric data equal to the difference between the current value and the previous one, with no division made, so the value is the total difference or increment, and not the increment per second. When this difference is negative, the value is reset, this means that at the time when the difference is again a positive value, the base value used to make this calculation is the last one from which the incremental value is positive.
- Alphanumeric (generic_data_string). Collect alphanumeric text strings.
- Monitors (generic_proc). Useful to evaluate the state of a process or service. This type of data is called 'monitor', because it assigns a '0' to a 'false' state and any value higher than '1' to a 'true' state.
- Asynchronous Alphanumeric (async_string). Collects alphanumeric text strings which could enter any moment without a fixed periodicity. The rest of the parameters (generic) work synchronously, which means they expect the data entry every XX time, and if they don't arrive then it's said they are in an unknown state (unknown). The asynchronous modules are unable to adopt this state.
- Asynchronous Monitor (async_proc). Similar to 'generic_proc' but asynchronous (compulsory).
- Asynchronous Numerical (async_data). Similar to 'generic_data' but asynchronous (compulsory).
3.6.1.4 module_min <value>
This is the minimum valid value to generated data within this module. If the module has not been defined in the web console yet, this value would be taken from this directory. This command is not compulsory. This value does not eliminate the defined value within the agent. If the module does not exist in the dashboard, then it's going to get created automatically when the learning mode is in use.
3.6.1.5 module_max <value>
This is the maximum valid value for generated data in this module. If the module has not been defined in the web console yet, this value could be taken from this directory. This guideline is not compulsory and it's not supported by the Windows agent. It doesn't eliminate the defined value within the agent. If the module does not exist in the dashboard, it will be created automatically when the learning mode is in use.
3.6.1.6 module_min_warning <value>
This is the minimum value which will make the module state go to the 'warning' status. This guideline is not compulsory. If the module doesn't exist in the dashboard, then it's going to get created automatically when the learning mode is in use.
3.6.1.7 module_max_warning <value>
This is the maximum value which will make the module go to 'warning' status. This guideline is not compulsory. It uses a <= (less than) operator.
3.6.1.8 module_min_critical <value>
This is the minimum value which will make the module state go to 'critical' status. This guideline is not compulsory. This uses a > operator, not a >= operator.
3.6.1.9 module_max_critical <value>
This is the maximum value which will make the module state go to 'critical' status. This guideline is not compulsory. This uses a <= operator.
3.6.1.10 module_disabled <value>
Indicates if the module is enabled ('0') or disabled ('1'). This guideline is not compulsory. If the module does not exist in the dashboard, it's going to get created automatically when the learning mode is in use.
3.6.1.11 module_min_ff_event <value>
This is the interval between new status changes which are filtered to avoid continuous changes of module state. This guideline is not compulsory. If the module doesn't exist in the dashboard, it's going to be created automatically when the learning mode is in use.
3.6.1.12 (>= 6.0 SP4) module_each_ff <value>
If enabled (1), per status flip flop thresholds are used instead of module_min_ff_event (module_min_ff_event_normal, module_min_ff_event_warning and module_min_ff_event_critical). Set to 0 to disable.
3.6.1.13 (>= 6.0 SP4) module_min_ff_event_normal <value>
Per status flip flop thresholds. See module_min_ff_event and module_each_ff.
3.6.1.14 (>= 6.0 SP4) module_min_ff_event_warning <value>
Per status flip flop thresholds. See module_min_ff_event and module_each_ff.
3.6.1.15 (>= 6.0 SP4) module_min_ff_event_critical <value>
Per status flip flop thresholds. See module_min_ff_event and module_each_ff.
3.6.1.16 (>= 6.0 SP4) module_ff_timeout <seconds>
Reset the flip flop threshold counter after the given number of seconds. This means module_min_ff_event status changes must be triggered within module_ff_timeout seconds before the status is actually changed.
3.6.1.17 module_description <text>
This guideline will be employed to add a comment to the module. This guideline is not compulsory and it doesn't overwrite the value defined by the agent. If the module doesn't exist in the dashboard, it's going to get created automatically when the learning mode is in use.
3.6.1.18 module_interval <factor>
Since Pandora 1.2 introduced this new type, it's possible for each module to fix its own interval. This interval is calculated as a multiplier for the agent interval. If the agent has e.g. an interval 300 (5 minutes) and you want a module which is going to get processed every 15 minutes only, you should add this line: module_interval 3. This module will be processed every 300sec x 3 = 900sec (15 minutes).
3.6.1.19 module_timeout <secs>
(Windows only)
In the 3.1 version, Pandora FMS supports specifying the total of seconds in each module independently. The agent is going to wait for the execution of the module, so if it takes more than XX seconds, it's going to abort the execution of the module (to avoid becoming 'dead' in the implementation of a module). In version 3.1, it's supported on Windows only - but in future versions, it's also going to get implemented into the UNIX agents.
3.6.1.20 module_postprocess <factor>
Same as in the definition of post processing of a module that is done from the console, a numeric value of floating comma could be defined here which is going to send this value to Pandora FMS in order to use it to multiply the received (raw) by the agent. If you e.g. want to multiply the value that the agent returns by 1024, just put "1024" in here. If you want to divide it by 1024, then just put 1/1024 here - which is 0,000976563.
3.6.1.21 module_save <variable name>
From version 3.2, it's possible to save the modules return value in an environment mode variable, so it could be used in other modules later. It's important to consider the values are updated after the modules are executed in the same order in which they were defined.
For example:
module_begin module_name echo_1 module_type generic_data module_exec echo 41121 module_save ECHO_1 module_end
module_begin module_name echo_2 module_type generic_data module_exec echo $ECHO_1 module_end
In Windows agents the module would have to be formed with %var% instead of $var. Following the example
module_begin module_name echo_2 module_type generic_data module_exec echo %ECHO_1% module_end
3.6.1.22 module_crontab <minute> <hour> <day> <month> <day of the week>
From version 3.2, it's possible to schedule modules in the order they'll be executed on a specific date. To do this, you're required to define the module_crontab', using a similar format to that of the crontab file: (http://es.wikipedia.org/wiki/Cron_(Unix)#Sintaxis)
module_crontab <minute> <hour> <day> <month> <day of the week>
Being:
- Minute 0-59
- Hour 0-23
- Day of the month 1-31
- Month 1-12
- Day of the week 0-6 (0 is Sunday)
It's also possible to specify intervals using the - character as a divider.
In order for one module to be executed e.g. every Monday between 12 and 15, we could use the following configuration:
module_begin module_name crontab_test module_type generic_data module_exec script.sh module_crontab * 12-15 * * 1 module_end
The module will be executed once during the interval. If we want it to be executed while the interval is on, we could use the module_cron_interval 0 option in the following way:
module_begin module_name crontab_test2 module_type generic_data module_exec script.sh module_crontab * 12-15 * * 1 module_cron_interval 0 module_end
To execute a command every hour, in an hour and 10 minutes:
module_begin module_name crontab_test3 module_type generic_data module_exec script.sh module_crontab 10 * * * * module_cron_interval 0 module_end
3.6.1.23 module_condition <operation> <command>
From version 3.2, it's possible to define commands that will be executed if the module returns some specific values. It's necessary to specify one of the following options:
- > [value]: Executes the command if the module value is higher than the given one.
- < [valor]: Executes the command if the module value is lower than the given one.
- = [valor]: Executes the command if the module value is equal to the given one.
- != [valor]: Executes the command if the module value is different to the given one.
- =~ [regular expression]: Executes the command if the module value coincides with the given regular expression.
- (valor, valor): Executes the command if the module value is ranged between the given values.
It's possible to specify multiple conditions for the same module. For example:
module_begin module_name condition_test module_type generic_data module_exec echo 2.5 module_condition (1, 3) script_1.sh module_condition > 5.5 script_2.sh module_end
Examples:
module_begin module_name MyProcess module_type generic_data module_exec tasklist | grep MyProcess | wc -l module_condition > 2 taskkill /IM MyProcess* /F module_end
module_begin module_name PandoraLogSize module_type generic_data module_exec ls -la "c:\Archivos de programa\pandora_agent\pandora_agent.log" | gawk "{ print $5 }" module_condition > 10000 del "c:\Archivos de programa\pandora_agent\pandora_agent.log" module_end
module_begin module_name Service_Spooler module_type generic_proc module_service Spooler module_condition = 0 net start Spooler module_end
- NOTE: On Windows platforms, it's recommended to use cmd.exe /c to execute the command to ensure it's executed properly. For example:
module_begin module_name condition_test module_type generic_data module_exec echo 5 module_condition (2, 8) cmd.exe /c script.bat module_end
3.6.1.24 module_precondition <operation> <command>
If the precondition is true, the module is going to run. It's necessary to specify one of the following options:
- > [value]: Executes the command if the module value is higher than the given one.
- < [value]: Executes the command if the module value is lower than the given one.
- = [value]: Executes the command if the module value is equal to the given one.
- != [value]: Executes the command if the module value is different to the given one.
- =~ [regular expression]: Executes the command if the module value coincides with the given regular expression.
- (value, value): Executes the command if the module value is ranged between the given values.
An example of a module using preconditions is the following:
module_begin module_name Precondition_test1 module_type generic_data module_precondition (2, 8) echo 5 module_exec monitoring_variable.bat module_end
Like postconditions, it's also possible to use several preconditions. The module is only going to be executed if all preconditions are met:
module_begin module_name Precondition_test2 module_type generic_data module_precondition (2, 8) echo 5 module_precondition < 3 echo 5 module_exec monitoring_variable.bat module_end
- NOTE: On Windows platforms, it's recommended to use cmd.exe /c to execute the command to ensure it's proper execution. For example:
module_begin module_name Precondition_test3 module_type generic_data module_precondition (2, 8) cmd.exe /c script.bat module_exec monitoring_variable.bat module_end
3.6.1.25 (>= 5.x) module_unit <value>
This is a unit of the value retrieved by the module.
Example:
module_unit %
3.6.1.26 (>= 5.x) module_group <value>
This is the name of the module group. If the group doesn't exist, the module will be created without getting assigned.
Example:
module_group Networking
3.6.1.27 (>= 5.x) module_custom_id <value>
This is a custom identifier for the module.
Example:
module_custom_id host101
3.6.1.28 (>= 5.x) module_str_warning <value>
This is a regular expression to define the 'warning' status in the string types modules.
Example:
module_str_warning .*NOTICE.*
3.6.1.29 (>= 5.x) module_str_critical <value>
This is a regular expression to define the 'critical' status in the string type modules.
Example:
module_str_critical .*CRITICAL.*
3.6.1.30 (>= 5.x) module_warning_instructions <value>
These are the instructions to the operator if the module changes to 'warning' status.
Example:
module_warning_instructions Increase incident priority
3.6.1.31 (>= 5.x) module_critical_instructions <value>
These are the instructions to the operator if the modules changes to 'critical' status.
Example:
module_critical_instructions Call to sys department
3.6.1.32 (>= 5.x) module_unknown_instructions <value>
These are the instructions to the operator if the module changes to 'unknown' status.
Example:
module_unknown_instructions Open incident
3.6.1.33 (>= 5.x) module_tags <value>
These are the tags which will be assigned to the module separated by commas. It will only be assigned to tags which exist in the system.
Example:
module_tags tag1,tag2,tag3
3.6.1.34 (>= 5.x) module_warning_inverse <value>
This is a flag (0/1) which will inverse the 'warning' threshold of the defined value when activated.
Furthermore, if you use a negative value for the interval, e.g. the 'warning' status for values under '-50', you need set the 'min_warning' to '-50' and set this parameter.
Example:
module_critical_inverse 0
3.6.1.35 (>= 5.x) module_critical_inverse <value>
This is a flag (0/1) which will inverse the 'critical' threshold of the defined value when activated.
Furthermore, if you use a negative value for the interval, e.g. the critical state for values under '-75', you're required to set the 'min_critical' to '-75' and set this parameter.
Example:
module_critical_inverse 1
3.6.1.36 (>= 5.x) module_native_encoding <value>
(Win32 only)
This configuration token only affects executed modules by command line, that is, there is a module_exec in the module configuration.
Windows manages three encodings for its processes: the command line encoding (OEM), the system encoding (ANSI) and UTF-16. Both encodings are agree on basic characters, but they are different on less common characters, like written accent. With this token, the Pandora's agent transforms the output to the encoding specified in the configuration file (pandora_agent.conf).
module_native_encoding has four acceptable values:
- module_native_encoding OEM: to command line encoding
- module_native_encoding ANSI: to system encoding
- module_native_encoding UTFLE: to UTF-16 little-endian
- module_native_encoding UTFBE: to UTF-16 big-endian
If module_native_encoding does not appear, no re-encoding will be done.
3.6.1.37 (>= 5.x) module_quiet <value>
This is a flag (0/1) which will turn the module into quiet mode when activated. It won't generate events or alerts anymore, and won't store historic data, so the reports such as SLA won't be affected.
Example:
module_quiet 1
3.6.1.38 (>= 5.x) module_ff_interval <value>
This is the flip flop execution threshold of the module (in seconds).
Example:
module_ff_interval 2
3.6.1.39 (>= 5.x) module_macro<macro> <value>
This is a macro generated by the console in conjunction with the components macro system. Setting this parameter from the configuration file is futile, because it's intended for modules created with local components only.
Example:
module_macro_field1_ 8080
3.6.1.40 (>= 5.1 SP4) module_alert_template <template_name>
This macro assigns to the module the alert template that corresponds to the name introduced as parameter(see Alert templates)
Example:
<module> <name><![CDATA[CPU usage]]></name> <type>generic_data</type> <module_interval>1</module_interval> <min_critical>91</min_critical> <max_critical>100</max_critical> <min_warning>70</min_warning> <max_warning>90</max_warning> <alert_template><![CDATA[Critical condition]]></alert_template> <![CDATA[92]]> </module>
3.6.1.41 module_end
Defines the end of the module (compulsory).
3.6.2 Specific guidelines to obtain information
Furthermore, there are the specific guidelines that could be specified for each module in order to obtain information. Only one kind of them can be used in each module.
3.6.2.1 module_exec <command>
This is the general way to gather information by executing a command. Both for the UNIX and for the Windows agent. There is only one guideline to obtain data the generic way, executing only one command (it's able to use pipes to re-address the execution to another command). This guideline executes a command and keeps the return value. This method is also available under the agents for Windows; it's the general purpose method for both agents.
If execution returns a return code different from '0', it will be interpreted as "execution error" and the information will be discarded. |
|
In some cases where you're sure your command is ok, even if returning code is !=0, you can pipe the execution to another "dump" command to clean the return code, e.g.:
top -n 1
Will give you error code 1 (check which echo $?). To "clean" that error code, just use this command:
top -n 1 | grep ""
There are the following, additional guidelines for the agents to obtain data:
3.6.2.2 module_service <service>
Checks if a specific service is being executed on the machine. Remember to use the «" "» characters if the name of the service contains blanks.
module_begin module_name Service_Dhcp module_type generic_proc module_service Dhcp module_description Service DHCP Client module_end
The service is identified with the short name of the service (service name), such as it appears in the Windows services manager. There is one other identifier, called "display name", longer and usually more descriptive, but this is not the one used by Pandora FMS to identify the process. Neither it is the process related to the server. In this snapshot, we can see the short name (service name) of the service monitored in the previous example. It is important to stress that there is a difference in the use of the "capital and the small letters (case sensitivity).
UNIX
Under Unix, it works like under Windows, but under UNIX, 'service' and 'process' is considered the same concept. For example, to see if the process named bash is running, the module definition would be:
module_begin module_name Service_bash module_type generic_proc module_service /bin/bash module_description Process bash running module_end
'service watchdog' and 'service asynchronous detection' aren't possible under UNIX agents.
Asynchronous Way
Pandora FMS usually executes a test battery (each of it defined by a module) every X seconds (300 seg. = 5 min. by default). If a service is down just after an execution of Pandora, it's going to take additional 300 seconds to recognize the service went down. The difference on asynchronous mode is that modules immediatly notify Pandora FMS about the fail or shutdown of this service. This is called asynchronous operation mode. It would be sufficient to add the following command to the guideline to use it:
module_async yes
This feature is not supported on broker agents.
Watchdog of services
There is a watchdog mode for the services, so the agent is able to restart them if they stop. In this case, the restarted service doesn't require any parameter, because Windows already knows how to do it. In such cases, the configuration is a lot easier:
module_begin module_name ServiceSched module_type generic_proc module_service Schedule module_description Service Task scheduler module_async yes module_watchdog yes module_end
3.6.2.3 module_proc <process>
Checks if an specific name of process is working in this machine. If the name of the process has blanks no use «" " », please consider that the name of the process should have the .exe extension. The module is going to return the number of processes executed with this name. Same as in the other cases, it's important to know that the name of the process has to be exactly the same as the one shown by the Windows Task Manager, including blanks, capital letters / small letters; e.g. cmd.exe is not the same as CMD.exe (case sensitivity).
This is an example of the monitoring of the process 'cmd.exe':
module_begin module_name CMDProcess module_type generic_proc module_proc cmd.exe module_description Process Command line module_end
UNIX
Under UNIX, this module works like 'module_service'. It doesn't support asynchronous and / or watchdog mode.
Asynchronous mode
In a similar way to the services, monitoring processes can be critical in some cases. The Windows agent supports asynchronous checking for the module_proc. module now. In this case, the agent immediately reports it if the process changes its state without waiting for the agent to execute the verification as it's configured in the agent interval again. In this way, you're able to get informed about the failure of critical processes almost in the moment they happen. This is an example of asynchronous monitoring of the processes:
module_begin module_name Notepad module_type generic_proc module_proc notepad.exe module_description Notepad module_async yes module_end
The difference is located in the configuration token 'module_async yes'. This feature is not supported on broker agents.
Processes Watchdog
A Watchdog is a system which allows to act immediately if an agent is down, usually picking up the process which went down. The Pandora FMS Windows Agent could act as a watchdog when a process is down. This is called watchdog mode for the process.
Executing a process would require some parameters, so here are some additional configuration options for these kinds of modules. It is important to keep in mind that the watchdog mode only works if the module type is set to asynchronous. This is an example of configuration of 'module_proc' with 'watchdog' enabled:
module_begin module_name Notepad module_type generic_proc module_proc notepad.exe module_description Notepad module_async yes module_watchdog yes module_start_command c:\windows\notepad.exe module_startdelay 3000 module_retrydelay 2000 module_retries 5 module_end
This is the definition of additional parameters for 'module_proc' with watchdog enabled:
- module_retries: Number of consecutive attempts for the module will try to start the process before deactivating the watchdog. If the limit is reached, the watchdog device for this module will be deactivated. It's never going to try and start the process, even if it's recovered by the user (at least until the agent gets rebooted). There is no limit for the number of retries for the watchdog by default.
- module_startdelay: Number of milliseconds the module is going to wait before starting the process for the first time. If the process takes lot of time at starting, it would be a good idea to order the agent to wait by using this parameter until it starts checking for if the process has been started or not. In this example, it has been set to wait for 3 seconds.
- module_retrydelay: Similar to the previous one but for subsequent falls / reattempts, after having detected a fall. When Pandora detects a fall, it relaunches the process, waits for the preset number of milliseconds and checks if the process is already up again.
It's important to keep in mind that Pandora FMS is executed as a service. If you want to utilize the watchdog functionality to execute processes which allow interaction with the desktop, you should check the box 'Interactive access with desktop' under the Pandora FMS service functionalities as shown in this snapshot:
It's also necessary to understand that Pandora FMS is executed under the count of "SYSTEM" if started as a service. The executed process is going to run with the user and environment of the one who started it, so if it wants to e.g. execute a specific process which requires the environment and rights of a specific user, one should include the previous processes for starting the environment (environment variables, etc.) and execute this script as a watchdog action in a script (.bat or similar).
3.6.2.4 module_cpuproc <process>
(UNIX only)
Returns the CPU usage of a specific process.
module_begin module_name myserver_cpu module_type generic_data module_cpuproc myserver module_description Process Command line module_end
3.6.2.5 module_memproc <process>
(Unix only)
Returns the memory used by a specific process.
module_begin module_name myserver_mem module_type generic_data module_memproc myserver module_description Process Command line module_end
3.6.2.6 module_freedisk <unit_letter:>|<volume>
This module works under UNIX and Windows. It checks for the free space in the disk unit (don't forget «":"» after the unit_letter) or the UNIX volume e.g. '/var'.
3.6.2.7 module_freepercentdisk <unit_letter:>|<volume>
This module returns the free disk percentage under a Windows unit: (don't forget the ":") or on a Unix system, the volume, like '/var'.
module_begin module_name freepercentdisk module_type generic_data module_freepercentdisk C: module_end
module_begin module_name disk_var module_type generic_data module_freepercentdisk /var module_end
3.6.2.8 module_occupiedpercentdisk <unit_letter:>|<volume>
(Unix only)
This module returns the occupied disk percentage in a UNIX volume e.g. '/var'.
module_begin module_name disk_var module_type generic_data module_occupiedpercentdisk /var module_end
3.6.2.9 module_cpuusage <cpu id>
This works under UNIX and Windows. It returns the CPU usage in a CPU number. If there is only one CPU, please leave it blank or use 'all'. It's also possible to obtain the average use of all CPU in multiprocessor systems in this way:
module_begin module_name SystemCPU module_type generic_data module_cpuusage all module_description Average CPU use in systme module_end
To check the CPU usage in CPU #1:
module_begin module_name SystemCPU_1 module_type generic_data module_cpuusage 1 module_description Average CPU use in system for CPU #1 module_end
3.6.2.10 module_freememory
Supported under Windows and UNIX. It returns the free memory of the whole system:
module_begin module_name FreeMemory module_type generic_data module_freememory module_description Non-used memory on system module_end
3.6.2.11 module_freepercentmemory
Supported under UNIX and Windows. This module returns the free memory percentage on one system:
module_begin module_name freepercentmemory module_type generic_data module_freepercentmemory module_end
3.6.2.12 module_tcpcheck
(Windows only)
This module tries to connect with an IP and a specified port. It returns '1' if successful and '0' if not. It's also recommended to specify a timeout:
module_begin module_name tcpcheck module_type generic_proc module_tcpcheck www.artica.es module_port 80 module_timeout 5 module_end
3.6.2.13 module_regexp
(Windows only)
This module monitors a record file (log) looking for coincidences using regular expressions, ruling out the already existing lines when starting the monitoring. The data returned by the module depend on the module type:
- generic_data_string, async_string: Returns all the lines which fit the regular expression.
- generic_data: Returns the number of lines which fit with the regular expression.
- generic_proc: Returns '1' if there is a coincidence and '0' if not.
- module_noseekeof: With this configuration token active, with a '0' default value in each module execution and independently from any modification of the target file, the module will restart its check process without searching for the file's EOF flag. It will always extract from the XML output all lines that correspond to our search patterns.
module_begin module_name regexp module_type generic_data_string module_regexp C:\WINDOWS\my.log module_pattern ^\[error\].* module_noseekeof 1 module_end
To obtain more information about the syntax of regular expressions in general, please visit [2].
3.6.2.14 module_wmiquery
(Windows only)
The WMI modules allow to locally execute any WMI query without the use of an external tool. It's configured through two parameters:
- module_wmiquery: Used WQL query. As a result, several lines could be obtained which will be placed as several data.
- module_wmicolumn: Name of the column which is going to be used as a data source.
For example, we could obtain a list of the installed services:
module_begin module_name Services module_type generic_data_string module_wmiquery Select Name from Win32_Service module_wmicolumn Name module_end
Or the current CPU load:
module_begin module_name CPU_speed module_type generic_data module_wmiquery SELECT LoadPercentage FROM Win32_Processor module_wmicolumn LoadPercentage module_end
3.6.2.15 module_perfcounter
(Win32 only)
Obtains data from the performance counter (http://msdn.microsoft.com/en-us/library/aa373083(v=vs.85).aspx Performance Counters (Documentación en ingles Performance Counters Documentation) through the PDH interface (the library pdh.dll should be installed in the system. PDH.DLL is a Windows library. If you have not installed it yet, you have to install the Windows performance analysis tool (which is usually installed by default).
module_begin module_name perfcounter module_type generic_data module_perfcounter \Memory\Pages/sec module_end
The Windows performance monitor is a powerful tool which has hundreds of parameters that could be used for monitoring. Each manufacturer also adds their own monitors, so this is a powerful, versatile and easy to use tool to monitor the system parameters and also the devices which run on it.
The syntax of the perfcounter elements depends on the language. In a e.g. German version, Windows is going to have specific identification strings and in an English version, Windows will have other ones. This makes it difficult to use on systems with heterogeneous languages.
To explore the different values which could be used, you can use the the Windows tool "Performance" to see which strings of performance you're able to monitor.
You can see the Windows performance monitor on this snapshot:
On this snapshot you can see how the interface shows things if we want to add a new monitoring element.
We can view several parameters of the Procesador (in Spanish in the original version) which has different sub elements, of which we have selected % of processor time and in several sub elements here. We're interested in total _Total in this case.
Surfing with the SO tool in this way, we could get different elements of the system performance. For this specific example, the module would be:
module_begin module_name Processor_Time module_type generic_data_inc module_perfcounter \Procesador(_Total)\% de tiempo de procesador module_end
By default the raw value of the counter is shown, to get the cooked value add the module_cooked 1 parameter:
module_begin module_name Disk_E/S_Seg module_type generic_data module_cooked 1 module_perfcounter \DiscoFísico(_Total)\E/S divididas por seg. module_end
Most of the returned data that are counters, so you should use 'generic_data_inc' as data type. It's also able to return values in very high data scales (several millions), so you could reduce these values using the module post process with values like '0.000001' or similar.
3.6.2.16 module_inventory
It's implemented as an agent plugin under Linux / Unix
Using predefined WMI consults and queries on the registry. This module obtains information about the different aspects of a machine ... from software to hardware.
The module can get different parameters to mark the kind of information it gets. Here is the parameter list and the kind of information that it gives:
- CPU: Gets information about the system CPUs (processor name, watch frequency and description).
- CDROM: Gets information about the CD-ROM (name, description and unity letter).
- Video: Gets information about video cards (description, RAM and processor).
- HDs: Gets information about the hard disks (model, size and name in the system).
- NICs: Gets information about the network interface controllers(description, MAC address and IP address).
- Patches: Gets information about the installed patches (identifier, description and comments).
- Software: Gets information about MSI packages installed (name and version).
- RAM: Gets information about RAM modules (tag, capacity and name).
- Services: Gets information about the installed services. The short name shown in the first column is the name of the service that Pandora FMS probably uses to monitor services.
Additional Module Parameters:
- module_interval: This module has an additional line to specify the interval in days, where one can obtain the information for the module.
This is an example to use this module:
module_begin module_name Inventory module_interval 7 module_type generic_data_string module_inventory RAM Patches Software Services module_description Inventory module_end
3.6.2.17 module_logevent
(Windows only)
This new module allows information to be obtained from the Windows event log file. It returns the elements which fit to a given pattern, also allowing to filter by source and event type. The module implemented in version 2.0 has been improved, using the Win32 native API now to have access to the events from the file, instead of using the WMI subsystem (much slower). This method is quicker and works on systems with many elements. The new implementation also allows much more field filtering compared to the previous version. The standard format of the module is the following:
module_begin module_name MyEvent module_type async_string module_logevent module_source <logName> module_eventtype <event_type/level> module_eventcode <event_id> module_application <source> module_pattern <text substring to match> module_description module_end
To avoid repeating what has already been shown, we only consider those events which occurred since the last time the agent was executed, as with other modules (e.g. 'regexp').
'module_logevent' accepts the following parameters (all of them case sensitive):
- module_source: Event source (System, Application, Security). This field is compulsory.
- module_eventtype: Event type (failure, information). This is an optional field.
- module_pattern: Pattern to search (substring). It's an optional field.
- module_eventcode: It's a numeric ID of the event, e.g. 5112. It's an optional field.
- module_application: Application source of the event. Be careful not to confuse it with 'module_source' which shows the name, source or log file where the events are looked for.
For showing all events of an error type system we e.g. should define the following module:
module_begin module_name log_events module_type generic_data_string module_description System errors module_logevent module_source System module_eventtype error module_end
To show all events which contain the word 'PandoraAgent':
module_begin module_name log_events_pandora module_type async_string module_description PandoraAgent related events module_logevent module_source System module_pattern PandoraAgent module_end
Another example: Filtering the event showed on the snapshot:
module_begin module_name MyEvent module_type async_string module_source Application module_eventtype Information module_eventcode 6000 module_application Winlogon module_pattern unavailable to handle module_description module_end
It's very important to understand that Pandora FMS is not a system to collect logs. This tool is intended to be used to select critical or important events for monitoring which collects all events without classifying them from a common source (as the 'system' could be one). Doing so will only cause problems in a way that e.g. the database can collapse and the system will work very badly. It's extremely important to understand that the event collection which comes with Pandora should always be used with taking this into account and not to abuse Pandora FMS as a generic event collector.
3.6.2.18 module_plugin
A parameter to define the data which is obtained at the exit of a plugin agent. It's a special case of a module which builds all its XML on its own. It also doesn't require any other delimiter like 'module_begin', 'module_type', etc. It requires this format:
module_plugin plugin_filename parámetro_1 parámetro_2 parámetro_3
In order to configure additional parameters for the plugin, please use the standard syntax:
module_begin module_plugin plugin_filename parameter_1 parameter_2 parameter_3 module_interval 2 module_condition (0, 1) script.sh module_end
Each plugin has its own syntax. We are going to describe the regular expressions plugin which comes with the agent by default.
module_plugin grep_log /var/log/syslog Syslog ssh
In this example, the name of the plugin is 'grep_log'. It's going to search for the regular expression 'ssh' in the file '/var/log/syslog' which will be kept in a module called 'Syslog'.
Another example intended to be solely used on Windows-based systems (and only on versions 3.1 or later):
module_plugin cscript.exe //B "%ProgramFiles%\Pandora_Agent\util\df_percent.vbs"
File collection and plugins
When you use file collections, you need to know where the file collection stores the files. File collections use a "handle" or short name which is generated when you first create the collection. It has to have a name similar to "fc_2". Here are some examples of 'module_plugin' usage using file collections:
UNIX:
module_plugin /etc/pandora/collections/fc_1/always_1.sh
Windows:
module_plugin cscript //B "%ProgramFiles%\pandora_agent\collections\fc_2\df_percent.vbs"
It's very important to know the plugin execution output could return more than one module, because it returns a full XML structure. This is e.g. the plugin output of the '/util/df.vbs' plugin in windows:
<module> <name><![CDATA[C:]]></name> <description><![CDATA[Drive C: free space in MB]]></description> <![CDATA[2361]]> </module> <module> <name><![CDATA[D:]]></name> <description><![CDATA[Drive D: free space in MB]]></description> <![CDATA[32020]]> </module> <module> <name><![CDATA[Z:]]></name> <description><![CDATA[Drive Z: free space in MB]]></description> <![CDATA[10168]]> </module>
3.6.2.19 module_ping <host>
(Only for Windows versions 4.0.1 or newer)
This module pings the preset host and returns '1' if it's up and '0' if not. It's a wrapper for ping.exe.
Is supports the following configuration parameters:
- module_ping_count x: Number of 'ECHO_REQUEST' packets to be sent ('1' by default).
- module_ping_timeout x: Timeout in milliseconds to wait for each reply ('1000' by default).
- module_advanced_options: Advanced options for ping.exe.
Example:
module_begin module_name Ping module_type generic_proc module_ping 192.168.1.1 module_ping_count 2 module_ping_timeout 500 module_end
3.6.2.20 module_snmpget
(From version 4.0.1 onwards, Windows only)
This module performs an SNMP get query and returns the requested value. It's a wrapper for snmpget.exe.
It supports the following configuration parameters:
- module_snmpversion [1,2c,3]: SNMP version (1 by default).
- module_snmp_community <community>: SNMP community (public by default).
- module_snmp_agent <host>: Target SNMP agent.
- module_snmp_oid <oid>: Target OID.
- module_advanced_options: Advanced options for snmpget.exe.
Example:
module_begin module_name SNMP get module_type generic_data module_snmpget module_snmpversion 1 module_snmp_community public module_snmp_agent 192.168.1.1 module_snmp_oid .1.3.6.1.2.1.2.2.1.1.148 module_end
3.7 Examples
Example of a Windows module, checking if 'EventLog' works. Example:
module_begin module_name ServicioReg module_type generic_proc module_service Eventlog module_description Eventlog service availability module_end
An example for a UNIX module would be:
module_begin module_name cpu_user module_type generic_data module_exec vmstat | tail -1 | awk '{ print $14 }' module_min 0 module_max 100 module_description User CPU module_end Tipos de agentes software
3.8 Specific Configuration by Technologies
With Pandora FMS it's possible to monitor any system. This could either be done with an installed Software agent on the system, which collects data straight from the system to be monitored, or by using a 'Satellite Agent' which consists of an agent which is executed in a server and monitors some parameters of systems which have adjacents through SNMP or user-defined commands.
The software agents could be Windows or UNIX agents. The agents could be installed using any of the agents described in the following lines. To use a satellite agent, it's enough to install a software agent and define the configured modules to collect data from an external system through, e.g. the snmpget tool or ping.
3.8.1 UNIX / Linux Agents
UNIX has several command line tools that allow data to be received through commands. The Unix agents are based in this premise. There are two kinds of UNIX agents:
- ShellScript: With a defined shellscript for each kind of SO based on bash, ksh or csh. In the classical UNIX Systems (Solaris, AIX, HPUX), all functionalities are not implemented yet - but under Linux or MAC they are.
- Perl: There is a unique multi-platform agent based on Perl 5.8 that works alike in all Unix systems. You're required to have a Perl 5.8 system or higher installed for proper functioning.
The shellscript agents have been designed to work in even the oldest UNIX versions: HPUX11.0, AIX 4.1, Solaris 6 ... They work, but are feature limited e.g. not having the Tentacle client and having to use the FTP or SSH system to upload the monitoring data to its server.
3.8.1.1 Pandora FMS UNIX Agents Configuration
There is hardly any difference between AIX, Solaris and GNU / Linux. We are going to describe some of their most important parameters and paths.
After starting the installer, the agents main directory or 'home' directory is '/usr/share/pandora_agent/' where the Pandora FMS agent is installed. In the system where this isn't possible for reasons of e.g. a strict system policy, we recommend creating a link to this path from the real installation path, e.g. '/opt/pandora' -> '/usr/share/pandora_agent'.
The other important folders are:
- /var/spool/pandora/data_out: Folder where the collected data from the agents is kept.
- /etc/pandora/pandora_agent.conf: Main agent configuration folder. The definition of where the data is collected is defined by the used command.
- /usr/local/bin/pandora_agent: The current Pandora FMS agent. This file is a shellscript which collects the configuration data in the 'pandora_agent.conf' files and sends the data packages to the Pandora Server. It usually has a link to '/usr/bin/pandora_agent'.
- /usr/local/bin/tentacle_client: The agent which adds the Tentacle client for being able to send the data files to the server. This is a client written in Perl 5.8. It usually has a link to '/usr/bin/tentacle_client'.
- /etc/init.d/pandora_agent_daemon: Script for starting and stopping. This daemon calls up 'pandora_agent' and gives two options (start / stop). On the AIX systems, the daemon's name is /etc/rc.pandora_agent_daemon.
- /var/log/pandora/pandora_agent.log: Text file where the activity of the Pandora FMS agent is kept if the agent is executed in depuration mode.
- /etc/pandora/plugins: Directory which keeps the agent's plugins. It's a link to /usr/share/pandora_agent/plugins.
3.8.1.2 Initial Execution of a UNIX Agent
When you start the Pandora FMS agent, this should copy the data file to the Pandora FMS server through the dispatch system which is specified in the configuration file of /etc/pandora/pandora_agent.conf. It's recommended to configure the dispatch system (Tentacle, SSH, FTP) before that.
To start the agent, execute:
/etc/init.d/pandora_agent_daemon start
For IPSO systems the agent will be launched with a priority of '-10', so it turns into the process with the lowest priority in the system CPU. It will be executed when other processes with a higher priority are waiting in the CPU system queue. The IPSO agent has a special parameter (harmless_mode ) for a special management of the CPU process on systems Checkpoint/NOKIA. This is a very special case.
In BSD systems the highest priority is '+20' and the lowest '-20'.
To stop the agent, just execute:
/etc/init.d/pandora_agent_daemon stop
3.8.1.3 Advanced Configuration for the UNIX Agent
The real power of Pandora FMS is on the agent's capacity to start processing the user defined scripts. This could be used to collect specific data or to make an operation which returns any desired value, because it's the aim of the agent plugin structure. For more information, please check the Annex on creating Agent Plugins.
3.8.1.4 Examples of Implementation for UNIX Agents
Example #1: Calculate the number of displays on the Apache Web server main page (it could degrade the running of huge records):
module_begin module_name WEB_Hits module_type generic_data_inc module_exec cat /var/log/apache/access.log | grep "index" | wc -l module_end
Example #2: Checks if the process of the (named) DNS is working or not:
module_begin module_name DNS_Daemon module_type generic_proc module_exec ps -Af | grep named | grep -v "grep" | wc -l module_end
3.8.1.5 Altering the way UNIX Agents obtain system information
This is valid for UNIX Perl agents only (version 3.2 or higher).
There are some modules which work like "blackboxes". They are performing operations the user doesn't have to know about. These modules are:
- module_procmem
- module_freedisk
- module_freepercentdisk
- module_cpuproc
- module_proc
- module_procmem
- module_cpuusage
- module_freememory
- module_freepercentmemory
Modules like e.g. 'module_cpuusage' return a percentage of the current system CPU usage, but the user doesn't need to use a command. On windows and on UNIX systems, Pandora 'already knows' what to do.
Pandora UNIX Agents have predefined commands to do that. The below mentioned commands are executed in different ways depending on the OS:
linux => 'vmstat 1 2 | tail -1 | awk \'{ print $13 }\, solaris => 'vmstat 1 2 | tail -1 | awk \'{ print $21 }\, hpux => 'vmstat 1 2 | tail -1 | awk \'{ print $16 }\
It could happen that your system is slightly different from the tested system and the command is not valid. You're able to use your own command with a simple 'module_exec' or redefine internal pandora commands to do that. You need to edit some lines of Pandora FMS Unix Agent code for that, but don't worry - it's Perl code and it's very basic editing.
The Pandora agent is usually located in '/usr/bin/pandora_agent'. Please edit with vi or nano (they are common text editors for the console), and search for "Commands to retrieve" text. You should see something like this:
# Commands to retrieve total memory information in kB use constant TOTALMEMORY_CMDS => { linux => 'cat /proc/meminfo | grep MemTotal: | awk \'{ print $2 }\, solaris => 'MEM=`prtconf | grep Memory | awk \'{print $3}\'` bash -c \'echo $(( 1024 * $MEM ))\, hpux => 'swapinfo -t | grep memory | awk \'{print $2}\ };
This is the piece of code which defines how pandora gets information from the system to get the total memory. AIX is not defined because we don't have the information on how to get this information in an AIX system yet.
# Commands to retrieve partition information in kB use constant PART_CMDS => { # total, available, mount point linux => 'df -P | awk \'NR > 1 {print $2, $4, $6}\, solaris => 'df -k | awk \'NR > 1 {print $2, $4, $6}\, hpux => 'df -P | awk \'NR > 1 {print $2, $4, $6}\, aix => 'df -kP | awk \'NR > 1 {print $2, $4, $6}\ };
These are the commands to get disk information in KB (total, free and mount point). To change any of the predefined values to get the information, just edit the command but be careful with it:
- Check that lines end with ";"
- Check that commands are between ' ' symbols.
- Check that any ' symbol you use ends on the \ symbol, e.g.:
df -P | awk 'NR > 1 {print $2, $4, $6}'
Will be
df -P | awk \'NR > 1 {print $2, $4, $6}\'
It's the same used above, so see how it's written in the code.
3.8.2 Pandora FMS Windows Agents
3.8.2.1 Check Windows agent is working
The exit of the Pandora FMS Windows agent can be checked in the file C:\archivos de programa\pandora_agent\pandora_agent.log. It's a plain text file that contains information about the agent's execution flow.
To check if Tentacle or SSH are working well, you can use the command tentacle_client or the parameter '--test-ssh' on the binary. The first command will return an error, because neither the address nor the file to send is specified, but it checks if the Tentacle client tentacle-client is in the system. The second one will force Pandora FMS to connect using SSH internally and copy a file called ssh.test. Remember that you're required to configure SSH properly, to generate the required keys and to import them onto the server if you want to use it.
3.8.2.2 Checking of Pandora FMS Agent service
The Pandora FMS 3.0 version has been carefully checked and "debugged" in order to avoid all kinds of memory leaks, handles of processes, files or TCP/IP ports. It's very stable and has been tested on all Windows platforms where it has to operate. Nevertheless, it could happen that the service crashes a few times on some systems. We have tried to give some solutions to those users which require a restarted system or a supplementary control of the agent for it.
There are two ways of having more control over the agent. The first one is to force the restart of the agent every X days through the Windows internal programmer for tasks through the AT command.
Restart with AT
In English
To schedule a restart on Mondays and Fridays:
at 00:00 /every:Monday,Friday "c:\program files\pandora_agent\scripts\restart_pandora_agent.bat"
In Spanish
For example, to schedule an every day restart:
at 00:00 /every:L,M,Mi,J,V,S,D "c:\archivos de programa\pandora_agent\scripts\restart_pandora_agent.bat"
To see a list of the scheduled tasks, just execute the following command in the command line:
at
This will give you the scheduled tasks.
Automatic control of the service in case of crashes
Windows provides an additional way of controlled restart of the service if this crashes for any reason. This allows you to tell the Windows service to restart automatically in case of a crash. You have to go to the Windows services dashboard and to the Pandora FMS agent and click on 'Properties' for it. On the 'Recovery' slide, you're required to change the default values into this:
This causes an automatic restart if the service crashes - but only once a day. If it happens to crash more than once a day, it won't get restarted again. The reason for this configuration is avoidance of a possible system overload due to a forced execution that downs too much of the other services, which is caused by a problem within the system. Pandora FMS should never be down. In any case, you can adjust these parameters if a Pandora FMS service crash should be controlled by the system and to make sure that you'll always have the agent running this way.
3.8.2.3 Configuration of Pandora FMS Windows Agent
The whole installation is done through the file pandora_agent.conf. This file is a list of pairs of keys and values which have been described before. Here is an example of this file:
# General Parameters # ================== server_ip mypandoraserver.host.com server_path /var/spool/pandora/data_in temporal "c:\windows\temp" interval 300 agent_name myagent_name # Module Definition # ================= # Counting OpenedConnections (please check language string) module_begin module_name OpenNetConnections module_type generic_data module_exec netstat -na | grep ESTAB | wc -l | tr -d " " module_description Conexiones abiertas (interval 2) module_interval 2 module_end # Is Eventlog service running ? module_begin module_name ServicioReg module_type generic_proc module_service Eventlog module_description Servicio Registro de sucesos module_end # Is lsass.exe process alive ? module_begin module_name Proc_lsass module_type generic_proc module_proc lsass.exe module_description LSASS.exe process. module_end # Received packets. # Please notice that "Paquetes recibidos" string must be replaced by # the correct string in your Windows system language. module_begin module_name ReceivedPackets module_type generic_data module_exec netstat -s | grep "Paquetes recibidos " | tr -d " " | cut -f 2 -d "=" | tr -d "\n" module_description Conexiones abiertas (interval 2) module_end # Free space on disk module_begin module_name FreeDiskC module_type generic_data module_freepercentdisk C: module_description Free space on drive C: module_end module_begin module_name FreeMemory module_type generic_data module_freepercentmemory module_description Amount of free memory. module_end
3.8.2.4 Extending the agents functionality with VBS code
Starting with the 3.1 version, Windows agents started to have plugins like the Unix agents, but don't forget they also have the possibility of executing the external scripts, based on VBScript as simple modules. Take a look at the VBS code which obtains the CPU total use of a system:
strComputer = "." Set objWMIService = GetObject("winmgmts:" _ & "{impersonationLevel=impersonate}!\\" _ & strComputer & "\root\cimv2") Set object1 = objWMIService.Get( _ "Win32_PerfRawData_PerfOS_Processor.Name='_Total'") N1 = object1.PercentProcessorTime D1 = object1.TimeStamp_Sys100NS Wscript.Sleep(1000) set object2 = objWMIService.Get( _ "Win32_PerfRawData_PerfOS_Processor.Name='_Total'") N2 = object2.PercentProcessorTime D2 = object2.TimeStamp_Sys100NS ' CounterType - PERF_100NSEC_TIMER_INV ' Formula - (1- ((N2 - N1) / (D2 - D1))) x 100 PercentProcessorTime = (1 - ((N2 - N1)/(D2-D1)))*100 Wscript.Echo PercentProcessorTime
We keep it in a file called "CPUTotal.vbs" which is located at c:\program files\pandora_agent\util.
Now we're going to create the new module type of 'module_exec' with this content:
cscript.exe /NoLogo c:\program_filespandora_agent\util\CPUTotal.vbs
We already have a new module that returns the CPU total use, obtained through the external script in VB. There are plenty of things that can be obtained through VBScript. Microsoft has an excellent online documentation about VBS that you can check in MSDN: [3].
3.8.2.5 Running the Pandora FMS Agent under a different user than SYSTEM
You can setup the Windows agent to run under a different user. You're required to configure the startup service with a different user and provide this user with special privileges to do that. That user is required to be included in the 'Administrators' group.
In the WMI console, all users from the group 'Administrators' have ALL permissions enabled.
This is an example of a user and it's WMI settings for the ROOT environment. Branches will inherit the root permissions by default:
You can look up some Microsoft links related to this issue on : [4] [5]
3.8.3 Auto-upgrading Software Agents
Pandora FMS 3.2 has a new feature called "File collection". File collections are described in a few chapters below, they are a 'centralized file distribution system' to copy files (binary, scripts and data) from the console to the agents running the Pandora FMS software agent.
We can provide a way to 'auto-upgrade' the software agents using that mechanism and a very special tool. It works in the following way:
1. Agents receive new binaries e.g. in the file collection's incoming directory:
c:\program files\pandora_agent\collections\fc_1\pandoraAgent.exe
2. The agent utilizes a special module to execute the pandora_update tool. This tool receives a single parameter, the FileCollection handle (or short name). In this scenario, it's fc_1. It checks for a file called 'pandoraagent.exe' (or 'pandora_agent' under UNIX), looks at the size and contents of both files (by using a HASH), the running 'pandora_agent' and the binary provided in the file collection. If they are different, 'pandora_update' stops the agent, replaces the binary and restarts the agent again, using the new binary.
3. Furthermore, 'Pandora_update' writes the update event to a small log to be able to recover the next execution and warns the user about the agent's updating process by means of an 'async_string' module.
This means that the used modules could be configured to have a high interval to perform the update process.
UNIX Standard Installation
module_begin module_name Pandora_Update module_type async_string module_interval 20 module_exec nohup /etc/pandora/plugins/pandora_update fc_1 2> /dev/null && tail -1 nohup.out 2> /dev/null module_description Module to check new version of pandora agent and update itself module_end
UNIX Custon Installation
module_begin module_name Pandora_Update module_type async_string module_interval 20 module_exec nohup /var/opt/PandoraFMS/etc/pandora/plugins/pandora_update fc_1 /var/opt/PandoraFMS 2> /dev/null && tail -1 nohup.out 2> /dev/null module_description Module to check new version of pandora agent and update itself module_end
NOTE: The second parameter of the 'pandora_update' command is the installation path of Pandora FMS. This parameter is only required if Pandora FMS is installed in a path different from the default path.
Windows
module_begin module_name Pandora_Update module_type async_string module_interval 20 module_exec pandora_update.exe fc_1 module_description Module to check new version of pandora agent and update itself module_end
NOTE: If it has the agent in a non "standard" path under UNIX, you're required to modify some of the 'pandora_update' utility values, specifically the following lines:
# Setup your particular paths / process settings here # [SETUP BEGIN] 12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC)12:46, 23 November 2010 (UTC) # Location of binaries # UNIX my $running_binary = "/usr/bin/pandora_agent"; my $updated_binary = "/etc/pandora/collections/$fc_path/pandora_agent"; # UNIX style my $start_pandora = "/etc/init.d/pandora_agent_daemon start"; my $stop_pandora = "/etc/init.d/pandora_agent_daemon stop";
Please change the paths to the ones which fit with your system manually.
3.8.4 Process to Auto Upgrade Agents from versions previous to 3.2
The first thing is to get the executables from the Pandora FMS agent and the 'pandora_update' tool ('pandoraAgent.exe' and 'pandora_update.exe' under Windows and 'pandora_agent' and 'pandora_update' under UNIX).
Many of the steps that we are giving here means the following things:
1. You have a way to copy files to the systems which you want to update. This is a feature which the Pandora FMS 3.2 version provides (File Collection) but just now, you want to migrate to the 3.2 version, because this feature is missing there. It's assumed that you have alternative mechanisms.
2. The agent's configuration and remote management is activated and working. This will be useful. It's recommended to create several directories and configure a new module in your Pandora FMS agent configuration.
Windows Platforms
We should copy 'pandora_update' to one directory of the system path or to the directory '/util' of our Pandora (in Windows).
Supposing that we have Pandora FMS installed in:
C:\Archivos de programa\pandora_agent
We have to copy 'pandora_update.exe' in the directory:
C:\Archivos de programa\pandora_agent\util
Then we create two directories:
C:\Archivos de programa\pandora_agent\collections C:\Archivos de programa\pandora_agent\collections\fc_1
And after this, we should copy the new agent's binary to the last directory which we have created:
C:\Archivos de programa\pandora_agent\collections\fc_1\PandoraAgent.exe
We create one module in the agent as the one that follows:
module_begin module_name Pandora_Update module_type async_string module_interval 20 module_exec pandora_update.exe fc_1 module_description Module to check new version of pandora agent and update itself module_end
This special module that uses the 'pandora_update' executable, executes a special tool ('pandora_update') which compares the current executable with the one that already exists in the directory '/collections/xxxx', where 'xxxx' is a parameter that is passed on to the module. This location is the one specified with the file collections. After using the 3.2 version, the distribution of the new *.exe of the agents will be done through file collections and this identifier will be necessary to 'locate' in which file collection our executable is located.
UNIX Platforms
Similar to the Windows platforms, we have to copy the executable of the UNIX agent and the 'pandora_update' feature. If it has a non-standard installation and possesses customized paths, you should have to pay lot of attention to the previous paragraph where it's described which files should be modified.
You have to copy pandora_update into your agent's plugins / folder:
/etc/pandora/plugins/pandora_update
Now create directory 'collection/fc_1' in the base directory of your '/etc/pandora':
/etc/pandora/collections/ /etc/pandora/collections/fc_1
The call to 'pandora_update' will be done on its system paths to the plugins. In this case, the default path is '/etc/pandora/plugins/pandora_update'.
The module for the UNIX case will be the following:
module_begin module_name Pandora_Update module_type async_string module_interval 20 module_exec nohup /etc/pandora/plugins/pandora_update fc_1 2> /dev/null && tail -1 nohup.out 2> /dev/null module_description Module to check new version of pandora agent and update itself module_end
NOTE: It's recommended to check if both 'pandora_update' and 'pandora_agent' have suitable permissions and owners, executing permissions and the same user which owns the 'pandora_agent' executable.
3.9 Pandora FMS Drone Agents
3.9.1 What is a Drone Agent ?
The Pandora FMS Drone Agent is a running mode of Pandora FMS Software Agent. This running mode only works on Windows and Linux machines. It was developed to deal with complicated environments with restricted access to the machines. The Drone Agent has two main features:
- Proxy mode
- Broker mode
Running in this mode, the Drone Agent can report data and utilize all features of the standard Pandora FMS Software Agent.
The picture below shows an architecture of Pandora FMS using Drone Agents:
3.9.1.1 Proxy Mode
Proxy Mode is very useful for networks which have restrictions in their communications. The agent running this mode enabled a Tentacle Proxy Server to allow agents to communicate with the Pandora FMS Server through itself.
The new Tentacle version supports proxy usage (HTTP/Connect mode), so that agents can contact with the server using an intermediate standard proxy directly. You also can use a new tool called 'Tentacle Proxy Server' is used to centralize all communication between Pandora FMS and the agents, allowing the file management and remote configuration for policy based-monitoring. You can see more about the Tentacle Proxy Server here.
You'll get all functionalities of a proxy but managed by Pandora FMS Software Agent with this feature. This mode has two requirements 1. The agent cannot be run by the root. 2. If you want to use the proxy mode with Unix agent then it must be installed with a user without root privileges (the same user will execute the agent in proxy mode later).
All parameters to configure the Tentacle Proxy Server are available trough its agent configuration file:
server_ip
It's the IP address or the name of Pandora FMS server host. Be careful with the enabled Proxy Mode. This parameter cannot take values like 127.0.0.1, locahost, 0.0.0.0 or related.
proxy_mode
Proxy mode status. If the 'proxy_mode' is set to '1', the proxy feature of the drone agent is activated. If the proxy_mode is set to '0', the proxy feature is off. This feature is disabled by default.
proxy_max_connection
Number of max. simultaneous connections of the proxy. 10 connections are allowed by default.
proxy_timeout
Timeout for the proxied server. Default value is '1 second'.
3.9.1.1.1 Usage Examples
I only have one connection to the Pandora FMS Server
This situation is not a problem for the Pandora FMS Drone Agent. To configure the proxy mode, just set 'server_ip' to the Pandora FMS IP and the 'proxy_mode' parameter to '1'. You can configure some parameters like the number of connections and timeout if needed. You'll have the agent and the Tentacle Proxy Server up and running on the machine which can connect with Pandora FMS Server with this configuration.
To configure the other agent, just set the 'server_ip' parameter to the IP address of the Drone Agent with proxy mode enabled. That's all you have to do. The agents are going to use the drone agent to connect to the Pandora FMS Server.
I'm required to setup a double proxied connection
You're able to connect a Drone Agent to another. It's very easy.
To perform the double proxy, just configure the Drone Agent which can connect to Pandora FMS Server to set the 'server_ip' to the Pandora FMS IP address. 'proxy_mode' must be set to '1' and the other parameters if you need.
To configure the second Drone Agent, just set the 'server_ip' to the one of the first Drone Agent and enable the proxy mode by setting 'proxy_mode' to '1'.
With this configuration, an agent connected to the second Drone Agent can send data to Pandora FMS Server through the two proxies.
3.9.1.2 Broker Mode
The Broker Mode is designed to "recreate" different agents (as an entity) from a single software agent installed on a server. Broker agents execute different setups, like if it has different personalities or different agents installed on the same server with different configurations. Each configuration file is independent and can have it's own plugins, inventory modules, etc. It can be remotely managed as any other agent of course. This is perfect to monitor servers / Comm devices nearby and useful when you're unable to reach a router but can install an agent in a nearby host. You can monitor ten routers from a single agent and have eleven agents in your Pandora FMS console (10 routers + 1 host) for example.
It's important to know that the broker_agent token will be ignored in the configuration of an agent which is set like a broker agent.
The main features of "broker mode" are:
- Send local data with another agent name. Useful to monitoring different instances of a software applicationn as independent agents.
- Send data from remote devices / checks executed from a single host and have it under Pandora FMS like they were different independent agents.
3.9.1.2.1 Examples
Send data to server with different agent names, using different configurations
Modify your pandora_agent.conf with following lines:
broker_agent router_1 broker_agent router_2 broker_agent router_3
On the next execution or restart you will have three new files: 'router_1.conf', 'router_2.conf' and 'router_3.conf'. They are an exact copy from origial "pandora_agent.conf" file, except the attribute of 'agent_name' which will be selected from the 'broker_agent' call.
You now have four agents with different configuration files. You can now add different modules in each configuration file, e.g. edit 'router_1.conf' and add:
Sample of remote check
Please add the following line to the remote configuration file 'pandora_agent.conf':
broker_agent server_1
A new file called 'server_1.conf' will be created and we'll edit it for the purpose of adding specific modules for this broker agent:
module_begin module_name Check SSH Status module_type generic_proc module_tcpcheck 192.168.1.1 module_port 22 module_timeout 5 module_end
This configuration can be interesting when making checks against another remote machine. Even if it has an agent installed Pandora, is unattainable by the server.
This feature is available from version 4.0 onward.
3.10 Agent / Module Autocreation from XML File / Learning Mode
Pandora FMS supports the automatic creation of agents and/or modules if you receive the information coming from an XML (data server). This happens automatically, unless you completely disable this behavior by disabling the server autocreate parameter. The 'creation' only happens the first time agent data arrives on the server. That means you can create the information but you cannot update the agent or module information each time you're getting a new XML - with a few exceptions as you can see below.
This behavior can be avoided in specific agents by disabling the learning mode of the agent. By disabling this feature, the agent will not create new modules when the XML arrives with the new module. The information won't update the agent configuration parameters.
Autodisable mode: From version 6.1 onward agents have this third mode available. In terms of creating agents and modules it behaves exactly the same as an agent in learning mode: when the first XML reaches it, the first agent is created and, on each report, if there are new modules they can also be added automatically. Nevertheless, when all modules from an agent that are in autodisable mode are also marked as unknown, the agent is automatically disabled. In any case, if the agent reports again, it gets enabled again on its own.
3.10.1 Loaded Data from the XML in the Creation of an Agent
Stored Data for an agent is the following:
In 4.x version:
- Agent name.
- IP address.
- Agent description.
- Agent's parent.
- Timezone offset.
- Group.
- Operating system.
- Agent interval.
- Agent version
In 5.x version
It's the same as in 4.x version, plus the following:
- Custom fields.
- Custom ID.
- URL address.
In 6.1 version
- Agent mode: (Learning -default-, No-learn, Autodisable).
3.10.2 Data modified in the Agent when receiving XML (Learning Mode enabled)
- Agent's IP address
- Agent's parent (if defined in server setup, for v4.x parents it's always updated)
- OS Version.
- Agent's version.
- Timezone.
- Custom fields.
By enabling the learning mode the new modules which get received through the XML file are going to be created under Pandora FMS.
3.10.3 Data added to the Module on Creation Time
The first time you get data coming from an XML for a module, the read data from the XML and inserted in the system are the following:
In 4.x version
- Name.
- Type.
- Description.
- Max Min value filter.
- Post process.
- Module interval.
- Min / Max Critical.
- Min / Max Warning.
- Disabled module.
In 5.x version
The same as in 4.x plus the following:
- Units.
- Module group.
- Custom ID.
- Str. Warning / Critical.
- Critical instructions.
- Warning instructions.
- Unknown instructions.
- Tags.
- Critical inversion mode.
- Warning inversion mode.
- Quiet mode.
- Min. FF Threshold.
- Alert template (from SP4)
In 6.x version
- Crontab
3.10.4 Loaded Data when Module already exists
If the data server processes an XML containing information for a pre-existent module, part of its information will be overwritten / updated. The description and extended information (see next epigraph) are updated.
Note: GIS data are always updated unless you have the GIS update disabled for that agent (this is configured in agent's GIS setup).
3.11 Extended Module Information
This epigraph is for advanced and development environments. You're able to send custom XML data (using your own application or altering the Pandora agent's source code). This XML file has two 'custom' tags named 'rack_number' and 'severity':
<module> <name><![CDATA[battery_level]]></name> <description><![CDATA[The actually device battery level]]></description> <type><![CDATA[generic_data]]></type> <data><![CDATA[61]]></data> <rack_number>2</rack_number> <severity>MAJOR</severity> </module>
The module is going to be shown like on the picture below.
These fields don't store history values. They're only going to store the last received value from the XML data. |
|