Pandora:Windows Agent

1 Get the last source

To get the last source from our repository, you will need a Subversion client. Then execute this:

svn co https://pandora.svn.sourceforge.net/svnroot/pandora

2 Build from sources

2.1 Windows

In order to build from sources, you will need the latest Dev-Cpp IDE version, with the MinGW tools. Download it from here.

Open PandoraAgent.dev with Dev-Cpp and construct the project. Everything should compile fine in a default installation.

If you found any problem when building from source, please contact us by email (ramon.novoa AT artica DOT es) or the SourceForge project web.

2.2 Cross-compiling from Linux

To cross-compile the Pandora FMS Windows Agent from Linux follow these steps:

• Install MinGW:

  sudo aptitude install mingw32

• Install the extra libraries needed by the agent: win32api, curl, openssl and zlib. For example, to install openssl:
  • Go to http://sourceforge.net/projects/devpaks/files/ and download the file openssl-0.9.8e-1cm.DevPak.
  • Uncompress the file openssl-0.9.8e-1cm.DevPak:

    tar jxvf openssl-0.9.8e-1cm.DevPak

  • Copy the libraries and include files:

    cp lib/*.a /usr/i586-mingw32msvc/lib/; cp -r include/* /usr/i586-mingw32msvc/include/

• Install autoconf & autogen

  sudo apt-get install autoconf autogen

• Go to the Pandora FMS Agent source directory and run:

  ./autogen.sh

• Go to the Pandora FMS Agent source directory and run:

  ./configure --host=i586-mingw32msvc && make

3 Installation

Before running the installation of Pandora Windows agent, you must create the Pandora directory and copy the PandoraAgent.exe file into it. It does not matter where it is installled, because Pandora Agent will adapt to any local directory. This directory should also have this content:

\pandora_agent.conf  :: Pandora Windows Agent main configuration.
\key\                :: Directory which holds the private and public key files.
\key\id_dsa          :: Private key to access the Pandora server using SSH.
\key\id_dsa.pub      :: Public key to access the Pandora server using SSH.

Optionally, it could have:

\utils\              :: Directory where the user could put misc utils to use whith 
                        modules exec type. I.e. UNIX-like tools (cut, 
                        grep, etc...)

Once these files and directories have been created, you can install the Pandor Windows Agent. To do so, execute these sentences in a Windows command line:

cd c:\Path\to\PandoraAgent
PandoraAgent.exe --install

The Agent will be installed into the Windows services system. You can check it on Control Panel -> Administrative tools -> Services. You can run it by clicking the "play button". To stop the service, open the "Services" dialog, search the "Pandora Agent" and click the stop button.

4 Configuration

4.1 General configuration

The Pandora Windows Agent configuration is done via the pandora_agent.conf file. This file is special and has a own syntax. The file is a list of keys/values pairs. Here is an example of this file.

# Begin of pandora_agent.conf example
# The comments begin with the '#' character
server_ip       192.168.50.1
server_path     /opt/pandora/data_in/
# Please notice that if the directory has a blankspace, it must be between "
temporal        "C:\temp files"
include         "C:\Program Files\pandora_agent\pandora_agent_alt.conf"
broker_agent    broker_name
interval        60
agent_name      antiriad

The variables which can be defined are:

server_ip     : IP of the Pandora Server. Required.
server_path   : Remote path of the incoming directory of the Pandora Server. Required.
temporal      : Local path to the temporal directory. Required.
include       : Alternative configuration file. Optional.
broker_agent  : Manage configurations and data collections from an agent like several agents. Optional.
interval      : Interval between executions (in seconds). Optional (60 seconds by default)
agent_name    : Name of the agent. Optional (machine name by default).
pandora_debug : Debug mode. Optional (off by default).

The module definitions must be also in the pandora_agent.conf files. Please read underneath to learn how to define a module.

4.2 Modules definition

The modules are defined with a own syntax, which is the same that the UNIX/Linux/Solaris agents. Here is an example of a module. Please notice the syntax:

module_begin
module_name ModuleName
module_type generic_data
module_exec Command
module_description Execution of Command
module_interval number
module_end

There are two optional fields, one is the module_description, which defines a human readable description of the module, the other is module_interval wich defines the number of iterations between each module execution, for instance if interval is set to 30 and module_interval is set to 3, that module will be executed every 3 * 30 = 90 seconds.

Actually, the Pandora Windows Agent support these modules:

4.2.1 module_exec

These modules execute a sentence provided in the definition.

module_begin
module_name ListenConnections
module_type generic_data
module_exec netstat -na | grep LISTEN | wc -l | tr -d " "
module_description Number of listen connections
module_end

4.2.2 module_proc

These modules check if a process is running in the system. It requires the full name, including the extension of the executable.

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

Since monitoring processes may be critical in some cases, Windows agent now supports asynchronous checking for module_proc. This allow the agent to inform Pandora server whenever a process is down. In the following example, as soon as notepad.exe is closed and stop running, the agent will send a tiny XML including only the status of this module.

module_begin
module_name Notepad
module_type generic_data
module_proc notepad.exe
module_description Notepad
module_async yes
module_end

4.2.3 module_service

These modules act like the module_proc, but checking if a Windows service is running.

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

In a similar way like in processes, monitoring services may be critical in some cases. Windows agent now supports asynchronous checking for module_proc, allowing the agent to inform Pandora server whenever a service is down. In the following example, as soon as ServiceSched is stopped, the agent will send a tiny XML including only the status of this module.

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

There's also a watchdog mode to services, so the agent can start a service when it's stopped. In this case, starting a service does not require any parameters, because Windows knows how to do it. So in this case, the configuration is easier and can be like:

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

4.2.4 module_freedisk

These modules get the amount of free space in the logical drive defined (please notice that the drive must have the :). The data is in MB.

module_begin
module_name FreeC
module_type generic_data
module_freedisk C:
module_description Free space on C:
module_end

4.2.5 module_cpuusage

These modules gets the average percentage load of the defined CPU.

module_begin
module_name UsoCPU0
module_type generic_data
module_cpuusage 0
module_description Uso de la CPU#0
module_end

It is possible to get the average CPU load on multiprocessor systems.

module_begin
module_name UsoCPU
module_type generic_data
module_cpuusage all
module_description Uso medio de CPU
module_end

4.2.6 module_freememory

This module get the amount of free memory. The data is in MB.

module_begin
module_name FreeMemory
module_type generic_data
module_freememory
module_end

4.2.7 module_freepercentdisk

This module returns the percentage of free space in a logical drive.

module_begin
module_name freepercentdisk
module_type generic_data
module_freepercentdisk C:
module_end

4.2.8 module_freepercentmemory

This module returns the percentage of free memory.

module_begin
module_name freepercentmemory
module_type generic_data
module_freepercentmemory
module_end

4.2.9 module_tcpcheck

This module tries to connect to the given host:port. Returns 1 if successful, 0 otherwise. A timeout may be specified.

module_begin
module_name tcpcheck
module_type generic_proc
module_tcpcheck www.artica.es
module_port 80
module_timeout 5
module_end

4.2.10 module_regexp

This module monitors a log file for matches of a regular expression, discarding existing lines at startup. The data returned by the module depends on the module type:

• generic_data_string: All lines that match the regular expression.
• generic_data: The number of lines that match the regular expression.
• generic_proc: 1 if there are any matches, 0 otherwise.

module_begin
module_name regexp
module_type generic_data_string
module_regexp C:\WINDOWS\my.log
module_pattern ^\[error\].*
module_end

For more information on the regular expression syntax see [1].

4.2.11 module_perfcounter

Retrieves performance counter data through the PDH interface (pdh.dll must be installed).

module_begin
module_name perfcounter
module_type generic_data
module_perfcounter \Memory\Pages/sec
module_end

4.2.12 module_logevent

The logevent module has been improved from version 2.0. It now uses the direct API to load events from file, instead use WMI bridge, as uses in 2.0, this method is much more faster. It has been thoroughly tested on Windows 2003 and Windows 2008 (which uses the new XML based event system) and should work on other versions too.

The new logevent module supports more filters to grab the event:

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

module_source is mandatory.

As you can see, could be easy to missunderstand the meaming of all fields. Main parameter is "Source" and this defines the windows log (Application, System, Security and others) where to search. Application defines the source of the event inside the windodows log. All this parameters are case sensitive.

A full example, matching the event in the screenshot.

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

4.2.13 module_logchannel

(Sólo Windows. A partir de 7.0OUM715)

Tipo de módulo que permite obtener información de los canales de logs de Windows. Si bien module_logevent solo tiene acceso a los logs de los Registros de Windows, este tipo de módulo permite extraer datos de otros ficheros de logs que estén configurados como canales. De esta forma, es posible obtener los logs englobados en los Registros de aplicaciones y servicios.

El formato general de este módulo es el siguiente:

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

Para evitar mostrar información repetida, sólo se tienen en cuenta aquellos eventos que hayan tenido lugar desde el momento en el que se inicia el agente.

module_logchannel acepta los siguientes parámetros (todos ellos case-sensitive):

• module_source: Canal del evento. Con el comando wevtutil.exe enum-logs se obtiene un listado de todos los canales de logs locales de la máquina. Campo obligatorio.
• module_eventtype: Tipo de evento (error, information...). Campo opcional.
• module_pattern: Patrón a buscar (subcadena). Campo opcional.
• module_eventcode: ID numerico del evento, p.e: 5112. Campo opcional.

Por ejemplo, definiríamos el siguiente módulo para mostrar todos los eventos del canal Microsoft-Windows-TaskScheduler/Operational, de tipo information, con código 201 y que en el texto del log apareciera el texto code 0:

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

Con esta configuración de módulo, el agente de Pandora recogería el siguiente log:

4.2.14 module_inventory

See below Inventory Module under New Feaures.

5 Uninstallation

To uninstall the Pandora Agent, run these sentences in a Windows command line:

cd c:\Path\to\PandoraAgent
PandoraAgent.exe --uninstall

Please notice that this will not stop the agent, which has to be stopped manually. In the next restart of Windows, the Pandora Agent will not be in the Windows services system.

6 New features

6.1 Watchdog

Another need may be reopen any process that was unexpectedly stopped. Pandora Window agent can now open any monitored process and work like a watchdog. Since opening a process might require some parameters, there's a new configuration line for this module. Notice that it only works when the module is set to be asynchronous. Here's an example of how to configure a module_proc module.

module_begin
module_name Notepad
module_type generic_data
module_proc notepad.exe
module_description Notepad
module_async yes
module_watchdog yes
module_start_command c:\windows\notepad.exe
module_end

These additional parameters are available for proc modules:

• module_retries: Number of consecutive times the module will try to launch the process before disabling the watchdog. If the limit is reached, the watchdog mechanism for this module will be disabled and never will try to launch again the process, even if this proccess is recovered by the user. To get the watchdog system restarted, you need to restart Pandora FMS agent. Please note that there is no limit by default on retry.

• module_startdelay: Number of milliseconds the module will wait before launching the process for the first time. This is a good idea to setup a value of 5000 (5 secs) here for example if your process take a lot on load in system.

• module_retrydelay: Number of milliseconds the module will wait before launching the process after a failure. Has the same meaning that module_startdelay, it's used to "wait" until process completely load on system.

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

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

6.2 Secondary server

A secondary server can be defined in pandora_agent.conf. The configuration options are the same as for the primary server, preceded by secondary_.

There are two modes of operation, specified in secondary_mode:

• on_error: Sends data to the secondary server only if it could not be sent to the primary server.
• always: Always sends data to the secondary server, even if it was already sent to the primary server.

Configuration example:

secondary_server_ip 192.168.1.123
secondary_server_path C:\pandora\data_in
secondary_mode on_error

secondary_transfer_mode tentacle
secondary_server_port 41121

6.3 UDP Server

Pandora FMS's Windows Agent runs a UDP server that allows it to receive commands from the web console.

To configure the UDP server the following options must be set in pandora_agent.conf:

• udp_server: Set to 1 to enable the UDP server.
• udp_server_port: Port the server listens on.
• udp_server_auth_address: Addresses authorized to send commands to the UDP server.

• process_<name>_start <command>: Local command to start a process.
• process_<name>_stop <command>: Local command to stop the process.

• service_<name> 1: Allows service <name> to be started or stopped.

Agent execution can be forced at any time from the web console.

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

6.4 WMIQuery module

The new wmiquery module can run any WQL query locally. It is configured by two new parameters:

• module_wmiquery: WQL query to run. Several rows may be returned for string data types.
• module_wmicolumn: Name of the column to be fetched.

For example, we can retrieve a list of installed system 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

6.5 Inventory Module

Using predefined WMI queries this module retrieves information about different aspects of a the machine, from sofware to hardware.

The module can receive diffferent parameters to mark what kind of information is retrieved. Here is the list of parameters and what kind of information they provide:

• CPU: Gets information about the CPUs on the system (Processor Name, Clock speed and Description).
• CDROM: Gets information about the CDROMs (Name, Description and Drive letter).
• Video: Gets information about the video cards (Descripiton, RAM and Proccessor)
• HDs: Gets information about the Hard Drives (Model, Size and System Name)
• NICs: Gets information about the Network Interface Controlers (Description, MAC address and IP address)
• Patches: Gets informaton about the patches installed (ID, Description and Comments)
• Software: Gets information about the MSI packages installed (Name and Version)
• Services: Gets information about system services (Name, Path and Status)
• RAM: Get information about the RAM modules (Tag, Capacity and Name)

This module has also an optional module_interval line used to specify the interval (in days) to get this module information.

module_begin
module_name Inventory 
# Establish the module interval to run (in days)
module_interval 3
module_type generic_data_string
# Parameters available: 
# * CPU -> Gets information about the CPUs
# * CDROM -> Gets information about the CDROMs
# * Video -> Gets information about the video cards
# * HDs -> Gets information about the Hard Drives
# * NICs -> Gets information about the Network Interface Controlers
# * Patches -> Gets informaton about the patches installed
# * Software -> Gets information about the MSI packages installed
# * Services -> Get information about system services
# * RAM -> Get information about the RAM modules
module_inventory CDROM Patches Software
module_description Inventory
module_end

7 Extending agent features with VBS code in agents

Probably you need some post-operation with your WQL queries and WMI modules don't give you enough power. For example, what happen if you need a total CPU usage, not per CPU, a global one ?. Consider to have a basic VBS script:

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

Call it "CPUTotal.vbs" and place on c:\program files\pandora_agent\util

Create a new execution module with this syntax:

cscript.exe /NoLogo c:\program_filespandora_agent\util\CPUTotal.vbs

Voilá!. You have now a CPU global usage counter. There ara a lot more VBS stuff you can use for your own modules. Just checkout excelent documentation from MSDN [2].