365 lines
15 KiB
Plaintext
365 lines
15 KiB
Plaintext
Pandora FMS Agents
|
|
==================
|
|
|
|
Please checkout our latest Pandora FMS documentation at http://pandorafms.org
|
|
|
|
This README file is not intended to be a documentation, only a brief introduction to Pandora FMS windows agent.
|
|
|
|
Understanding what is a Pandora FMS Agent
|
|
-----------------------------------------
|
|
|
|
Pandora FMS agents collect all system's data. They are executed in each local system, although they can also collect remote information by installing monitoring systems for the agent in several different machines - called satellite agents.
|
|
|
|
They are developed to work under a given platform, making use of the specific tools of the language being used: VBSCript/Windows Scripting for Microsoft platforms (Win2000, WinXP y Win2003), ShellScripting for UNIX - which includes GNU/Linux, Solaris, AIX, HP-UX and BSD, as well as the Nokia's IPSO. Pandora agents can be developed in virtually any language, given its simple API system and being open source. There are branches of the Pandora project started for the creation of agents in Posix C, Perl and Java for those systems requiring closed agents.
|
|
|
|
Pandora Agents are Free Software, i.e., the way agents collect and sent information is documented. An agent can be recreated in any programming language, and can be upgraded easily, to improve aspects of the program not covered so far.
|
|
|
|
This document describes the installation of agents in machines running over Windows and Unix operating systems.
|
|
|
|
Generic role of the agents
|
|
--------------------------
|
|
|
|
Regardless the platform an agent is running on, this is formed of the following elements: A script (or binary application in Windows) that collects and sends the data to
|
|
the server.
|
|
|
|
One or several configuration files where the values to be collected are defined. The file is called pandora_agent.conf both for Windows and Unix machines.
|
|
|
|
This simple structure makes it easy the customisation of an agent. There is no need to code again the agent to modify the way it works, as the configuration file holds most of the parameters needed to do so.
|
|
|
|
Pandora FMS Agent configuration
|
|
------------------------------
|
|
|
|
Main program
|
|
~~~~~~~~~~~~
|
|
|
|
The main script is the executable file that collects the data specified in the configuration file. It sends the data to the server in XML. In Windows machines application is installed as a service and is executed at the time intervals set in the configuration file. In machines running over UNIX the main script is run through a special script called pandora_agent, and runs continuously in the machine as a process.
|
|
|
|
Configuration File
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The data collection in the host system is the gathering of independent data units, which are defined in the /etc/pandora/pandora_agent.conf file. The pandora_agent.conf file is divided in two parts:
|
|
|
|
* General parameters: Configure general options about server location, agent name, interval, and other general options.
|
|
|
|
* Module definitions: Configure and define the method of extraction for each piece of information that will be extracted from local host and sent to Pandora Server.
|
|
|
|
General parameters
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
The general parameters of the agent configuration are defined in this section. Some of these parameters are common for all systems and others specific for Windows or UNIX. The general parameters are:
|
|
|
|
* server_path: The server path is the full path of the folder where the server stores the data sent by the agent. It is usually /var/spool/pandora/data_in.
|
|
|
|
* server_ip: The server IP is the IP address or the host name of the Pandora server, where the data will be stored. The host must be reachable and must be listening to port 22 (SSH).
|
|
|
|
* interval: This is the time interval in seconds in which the agent will collect data from the host system and send the data packages to the server. The recommended value ranges from 300 (5 minutes) to 600 (10 minutes). This number could be larger, although it is important to consider the impact of a larger number on the database.
|
|
|
|
* debug: This parameter is used to test the generation of data files, forcing the agent to do not copy data file to server, so you can check data file contents and copy XML data file manually. It does not delete any data when the process is finished, so data file will be in temp directory. The activity is written in a log file. The file is named pandora_agent.log. This log file can be used to test the system and to investigate potential issues.
|
|
|
|
* agent_name: This is an alternative host name. This parameter is optional as if it is not declared the name is obtained directly from the system.
|
|
|
|
* Transfer Mode: This parametrer let you specify which transfer mode is going to be set up to send the agent data to the server. Modes available are: tentacle (default), ssh (using scp), ftp or local. Local mode it is only for systems where the agent run in the same machine as the server does, cause it is basically a copy between directories.
|
|
|
|
* server_pwd: Specify password for FTP transfer mode (Windows only).
|
|
|
|
* encoding: Set the encoding type of your local system, like iso-8859-15, or utf-8.
|
|
|
|
|
|
An example of the general parameters from a Unix configuration would be:
|
|
|
|
server_ip 192.168.12.12
|
|
server_path /var/spool/pandora/data_in
|
|
temporal /var/spool/pandora/data_out
|
|
interval 300
|
|
agent_name dakotaSR01
|
|
debug 0
|
|
|
|
Module definition
|
|
-----------------
|
|
|
|
Each data item that is to be collected must be defined precisely in each module,
|
|
using the exact syntax. As many values as necessary can be set to be collected,
|
|
adding at the end of the general parameters as many modules as the number of
|
|
values to collect. Each module is made of several directives. Following is a
|
|
descriptive relation of all module marks available for Unix agents (almost all
|
|
of them are applicable to Windows Agent too).
|
|
|
|
|
|
module_begin
|
|
|
|
Defines the beginning of the module.
|
|
|
|
module_name <name>
|
|
|
|
Name of the module. This is the id for this module, choose a name without blank
|
|
spaces and not very long. There is no practical limitation (max of 250 chars)
|
|
but will be more easier to manage if you use short names. This name CANNOT be
|
|
duplicated with a similar name in the same agent. This name could be duplicated
|
|
with other modules in other agents.
|
|
|
|
module_type <type>
|
|
|
|
Data type the module will handle. There are four data types for agents:
|
|
|
|
* Numeric (generic_data). Simple numeric data, float or integer. If the
|
|
values are of the float type, they will be truncated to their integer value.
|
|
|
|
* Incremental (generic_date_inc). Integer numeric data equal to the
|
|
differential between the actual value and the previous one. When this
|
|
differential is negative the value is set to 0.
|
|
|
|
* Alphanumeric (generic_string). Text strings up to 255 characters.
|
|
|
|
* Monitors (generic_proc). Stores numerically the status of the processes.
|
|
This data type is called monitor because it assigns 0 to an "Incorrect"
|
|
status and any value above 0 to any "Correct" status.
|
|
|
|
module_exec <command>
|
|
|
|
This is the generic "command to execute" directive. Both, for Unix and Windows
|
|
agents there is only one directive to obtain data in a generic way, executing a
|
|
single command (you could use pipes for redirecting execution to anoter
|
|
command). This directive executes a command and stores the returned value. This
|
|
method is also available on Windows agents. This is the "general purpose method"
|
|
for both kind of agents.
|
|
|
|
For a Windows agent there are more directives to obtain data, who are described
|
|
following this lines.
|
|
|
|
|
|
module_service <service>
|
|
|
|
(Win32 Only)
|
|
|
|
Checks if a given service name is running in this host. Remember to use " "
|
|
characters if service name contains blank spaces.
|
|
|
|
|
|
module_proc <process>
|
|
|
|
(Win32 Only)
|
|
|
|
Checks if a given processname is running in this host. If the process name
|
|
contains blank spaces do not use " ". Also notice that the process name must
|
|
have the .exe extension. The module will return the number of process running
|
|
with this name.
|
|
|
|
module_freedisk <drive_letter:>
|
|
|
|
(Win32 Only)
|
|
|
|
Checks free disk on drive letter (do not forget ":" after drive letter).
|
|
|
|
module_cpuusage <cpu id>
|
|
|
|
(Win32 Only)
|
|
|
|
Returns CPU usage on CPU number cpu. If you only have one cpu, use 0 as value.
|
|
|
|
module_freememory
|
|
|
|
(Win32 Only)
|
|
|
|
Return free memory in the whole system.
|
|
|
|
module_min <value>
|
|
|
|
This is the minimum valid value for the data generated in this module. If the
|
|
module has not yet been defined in the web console this value will be taken from
|
|
this directive. This directive is not compulsory. This value does not override
|
|
the value defined in the agent if the module does not exist in the management
|
|
console is created automatically when working on learning mode.
|
|
|
|
module_max <value>
|
|
|
|
It is the maximum valid value for the data generated in this module. If the
|
|
module has not been defined in the web console this value will be taken from
|
|
this directive. This directive is not compulsory and is not supported by the
|
|
Windows agent. This value does not override the value defined in the agent if
|
|
the module does not exist in the management console. This is created
|
|
automatically when working on learning mode.
|
|
|
|
|
|
module_description <text>
|
|
|
|
This directive is used to add a comment to the module. This directive is not
|
|
compulsory. This value does not override the value defined in the agent if the
|
|
module does not exist in the management console. This is created automatically
|
|
when working on learning mode.
|
|
|
|
|
|
module_interval <factor>
|
|
|
|
Since Pandora 1.2 introduces this new feature. You can, for each module, setup
|
|
its own interval. This interval its calculated as a multiply factor for agent
|
|
interval. For example, if your agent has interval 300 (5 minutes), and you want
|
|
a module only be calculated each 15 minutes, you could add this line:
|
|
module_interval 3. So this module will be calculated each 300sec x 3 = 900sec
|
|
(15 minutes).
|
|
|
|
|
|
module_end
|
|
|
|
Ends module definition
|
|
|
|
|
|
Examples
|
|
|
|
An example of a Windows module, checking if EventLog service is alive, would be:
|
|
|
|
module_begin
|
|
module_name ServicioReg
|
|
module_type generic_proc
|
|
module_service Eventlog
|
|
module_description Eventlog service availability
|
|
module_end
|
|
|
|
An example of 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
|
|
|
|
|
|
Agent types
|
|
===========
|
|
|
|
It is possible to monitor virtually any system with Pandora. This can be done
|
|
either with a local agent collecting data directly from the system to be
|
|
monitored, using a a satellite agent collecting data from a system by SNMP or
|
|
using the new Pandora 1.2 agents, the remote agents, who can chack using remote
|
|
network polling (TCP, UCP, ICMP/PING and SNMP) remote services, from the Pandora
|
|
Network Server.
|
|
|
|
The local agents can be either Windows or Unix agents. The satellite agents can
|
|
be implemented using any of the agents above. The modules are configured to
|
|
collect data from the external system by, for example, an SNMPGET tool.
|
|
|
|
Pandora FMS Windows Agents
|
|
--------------------------
|
|
|
|
Build Pandora FMS Windows Agent from sources
|
|
|
|
In order to build from sources, you will need the latest Dev-Cpp IDE version,
|
|
with the MinGW tools. Download from http://www.bloodshed.net/devcpp.html
|
|
|
|
Open PandoraService.dev with Dev-Cpp and construct the project. Everything
|
|
should compile fine in a default installation.
|
|
|
|
|
|
|
|
Manual Pandora FMS Windows Agent installation (without installer)
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To install manually (without installer) the Pandora FMS Windows Agent execute
|
|
this sentence in a Windows command line:
|
|
|
|
PandoraService.exe --install
|
|
|
|
The Agent will be installed into the Windows services system. You can check it on Control Panel -> Administrative tools -> Services.
|
|
|
|
To run the Agent open the "Services" dialog (Control Panel -> Administrative tools-> Services), search the "Pandora Service" service and run it clicking the play button. To stop the service, open the "Services" dialog, search the "Pandora Service" and click the stop button.
|
|
|
|
To uninstall the Pandora Windows Agent, execute this sentence in a Windows command line:
|
|
|
|
PandoraService.exe --uninstall
|
|
|
|
Windows Agent testing
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
You can check the Pandora Windows Agent output in the pandora_debug.log file, that is a plain text file and includes info about the execution flow of the Agent.
|
|
|
|
To test that SSH is working correctly, you can use the --test-ssh parameter in the executable file. This force pandora to conect using internal SSH and copy a file called "ssh.test".
|
|
|
|
Windows Agent configuration
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
All setup is made in pandora_agent.conf. This file is a list of keys/values pairs. Here is an example of this file.
|
|
|
|
# General Parameters
|
|
# ==================
|
|
|
|
server_ip 127.0.0.1
|
|
server_path /var/spool/pandora/data_in
|
|
temporal "c:\windows\temp"
|
|
interval 300
|
|
agent_name localhost
|
|
transfer_mode ftp
|
|
server_pwd pandora123
|
|
|
|
# Module Definition
|
|
# =================
|
|
|
|
|
|
# Counting OpenedConnections (check the 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 Schedule service running ?
|
|
module_begin
|
|
module_name ServicioProg
|
|
module_type generic_proc
|
|
module_service Schedule
|
|
module_description Servicio Programador de tareas
|
|
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_freedisk C:
|
|
module_description Free space on drive C:
|
|
module_end
|
|
|
|
# CPU usage percentage
|
|
module_begin
|
|
module_name CPUUse0
|
|
module_type generic_data
|
|
module_cpuusage 0
|
|
module_description CPU#0 usage
|
|
module_end
|
|
|
|
module_begin
|
|
module_name FreeMemory
|
|
module_type generic_data
|
|
module_freememory
|
|
module_description Amount of free memory.
|
|
module_end
|