Pandora:Documentation en:Inventory

From Pandora FMS Wiki

Jump to: navigation, search

Go back to Pandora FMS documentation index

Inventory

Introduction

The Pandora FMS Enterprise Version allows you to generate an inventory of the devices of which the servers monitored by Pandora FMS are composed of. By this inventory, it's possible to keep a list which contains the CPU, expansion cards, memory, patches, software, etc. or the company's servers.

The inventory is independent from the monitoring and could be accomplished either locally (by Pandora FMS Agents) or remotely.

Data Collection for the Inventory

The data collection for the system inventory is conducted in two different ways: Remotely by inventory modules, by scripts integrated within Pandora FMS which perform the WMI queries or by executable scripts which utilize SSH along with 'Expect' or similar methods.

If the data collection is conducted locally by the Pandora FMS Agent, it's going to be performed by plug ins within the agent or a special type of module in case of Windows-based systems.

Inventory Modules

The inventory modules are remote modules which execute a command against a remote machine. These modules work in a similar way as a plug in. The same modules could be defined as 'locals' if they obtain data by an agent.

Remote Inventory

Creating Remote Modules

The creation of a remote inventory module by an administrator is seen as unusual. These inventory modules already come 'preconfigured' along with Pandora FMS Enterprise. Pandora FMS also allows you to create your own inventory modules or modify the already existing ones by using the Inventory Module Editor.

In order to create a remote module, please click on 'Configuration' -> 'Inventory Modules'. You're going to find all preconfigured inventory modules there. Note that you also have the local preconfigured inventory modules here, with their defined format.



In1.png



In order to create a new module, please click on the 'Create' button.



In2.png



Now we're going to describe the fields you'll find there.

Name: The field intended for the module's name.

Description: The field intended for the module's description.

OS: The combo in which you're able to pick the operating system the module was intended for. It's important to pick the operating system carefully, because, by adding inventory modules to an agent, only modules matching to the one of the agent's are going to show up in there.

Interpreter: The field intended to input the appropriate command interpreter to be used within the module. You may also put in a shell script, use the Perl language or any other valid interpreter for the Inventory Server which is intended for use in conjunction with a Linux-based system in there.

Format: The field in which the fields are going to be separated by the ';' character which the module is going to return.

Code: The module's code, It's usually Perl or a shell-script code. If you intend to use binary code here, it's going to require a different loading procedure which is required to be introduced by peripheral scripts.

Once the module has been created, please click on the 'Create' button.



In3.png



Editing Remote Modules

In order to edit a remote module, please click on 'Configuration' and 'Inventory Modules'. It's the location in which all the inventory modules created so far are listed. Please click on the module you intend to edit or the wrench icon which is located on the right side as shown below.



In4.png



In this moment, the module creation window is going to appear again.



In5.png



Please edit the fields you intend to change and click on the 'Update' button.

Deleting Remote Modules

In order to delete a remote module, please click on 'Configuration' -> 'Inventory Modules'. It's the location in which all the inventory modules which have been created so far are listed. Please click on the trash icon which is located on the right side of the module you intend to delete.



In6.png



Assigning Remote Modules

The inventory module's assignment is conducted within the agent's administration flap.

Under 'Resources' and 'Manage Agents', please click on the agent's name to which you intend to assign inventory modules to.



In7.png



Please click on the 'Inventory' flap.



In8.png



This is the menu in which you're able to add the new inventory modules.



In9.png



Now we're describing the fields which you're going to encounter in the moment of adding an inventory module.

  • Module: The combo designed to pick the inventory module you intend to add. It's only going to show the modules that match the agent's operating system.
  • Target: The IP or server name from you intend to obtain the inventory from.
  • Interval: The combo to pick the time interval in which the inventory module is going to be executed.
  • Username: The user which is going to execute the inventory module.
  • Password: The user's password which is going to be used to execute the inventory module.

Once the form has been filled out, please click on the 'Add' button in order to add the new module to the other inventory modules.



In10.png



Editing an assigned Inventory Module

You may also edit the inventory modules. This editing is conducted on the same page on which they've been created before. In order to edit an inventory module, please click on the module's name or on the key icon which is shown on the picture below.



In20.png



Deleting an assigned Inventory Module

It's possible to delete inventory modules. This deletion process is conducted on the same page on which they've been created before. In order to delete an inventory module, please click on the trash icon which is located on the right side of the module's name.

Complete Example of a Remote Inventory Module

Just imagine for a moment you're required to obtain a list of physical addresses from a server - in this case, a UNIX server. This is usually achieved by the command of 'arp -a -n'. If we're executing it on a server, it's going to give us something back like this:


artica@galaga:~$ arp -a -n
? (192.168.70.74) at 08:00:27:39:BF:6F [ether] on eth2
? (192.168.70.162) at B4:74:9F:94:98:84 [ether] on eth2
? (192.168.50.30) at 08:00:27:10:D1:1A [ether] on eth0
? (192.168.70.90) at 98:0C:82:54:2F:DE [ether] on eth2
? (192.168.50.2) at 08:00:27:EA:B2:FF [ether] on eth0
? (192.168.70.135) at C8:60:00:4B:96:67 [ether] on eth2
? (192.168.60.182) at FE:26:C5:91:B1:DA [ether] on tap0


What we're looking for is the IP address, the MAC address and the adapter's name.

This could be achieved by using a shell script in the below mentioned way. We're using " " to separate the fields:

arp -a -n | sort | grep -v incomplete | awk '{ print $2,$4,$7 }'


We have almost all the necessary data to 'import' this information into the remote Pandora FMS Inventory Server. To do so, we're going to use the 'CPU' remote inventory module as a basis and we're also going to change it slightly. This script is connected to the destination server via SSH and executes the command. The command's execution should return each file, separated by the ';' character.


At this point, you're required to have some knowledge of programming to produce your own scripts. Although they're not very complex, the remote inventory scripts require you to possess some knowledge of Perl, shell scripts or other languages. You're also able to write them in Java or C++ and to call up their execution from the module as long as you return the values of each field separated by the ';' character and take a new line for each line of data.


#!/usr/bin/perl
##########################################################################
# pandora_linux_arptable.pl
##########################################################################
# Copyright (c) 2012 Sancho Lerena <slerena@artica.es>
#           (c) 2012 Artica Soluciones Tecnologicas S.L
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; version 2.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
##########################################################################

use strict;
use warnings;

# Check for ssh
my $ssh_client = "ssh";
if (system("$ssh_client -v > /dev/null 2>&1") >> 8 != 255) {
	print "[error] $ssh_client not found.\n";
	exit 1;
}

if ($#ARGV < 1) {
	print "Usage: $0 <target ip> <username>\n";
	exit 1;
}

my $target_ip = $ARGV[0];
my $username = $ARGV[1];

# Retrieve ARP table
my ($ip, $mac, $iface);
my $command = '/usr/sbin/arp -a -n | sort | grep -v incomplete | awk \'{ print \$2,\$4,\$7 }\'';

my @info = `$ssh_client $username\@$target_ip "$command" 2> /dev/null`;
foreach my $line (@info) {
	if ($line =~ /^(.+)\s(.+)\s(.+)/) {
		$ip = $1;
		$mac = $2;
		$iface = $3;
		print "$ip;$mac;$iface\n";
	} 
}
 
exit 0;


In order for the SSH connection to work automatically, you're required to copy the user's public key, which requires 'root' privileges from the Pandora FMS Server on the destination server. Imagine this command to be executed on '192.168.50.10'. Please follow the below mentioned steps.


1. Please create a new key on the Pandora FMS Server as 'root' by the following command:

ssh-keygen


2. Please use the command 'ssh-copy-id' to copy the the destination server's public key of '192.168.50.10' along with the destination user (in this case, it's the user 'artica') by the command below:


ssh-copy-id -i /root/.ssh/id_rsa.pub artica@192.168.50.10


You're also required to enter the user password 'artica' once on '192.168.50.10' in order to install the public key on the destination user.

3. Now try to establish a connection. It should connect to it without asking for the password:


ssh artica@192.168.50.10


4. If the process was successful, the inventory module is going to follow the same process. Please try to execute it from the command line and save the previous script to the disk (temporal.pl) and execute it along with the IP and the user as parameters in the following way:


perl temporal.pl 192.168.50.10 artica
(192.168.50.1);00:0f:ea:27:ba:f0;eth0
(192.168.50.3);08:00:27:98:f8:48;eth0


Please keep in mind that the script remotely calls to '/usr/sbin/arp'. The command should be present within this path - if not, please change the script. As you've also certainly noticed, we call up our script by the 'perl' command which is usually located at '/usr/bin/perl'. In the moment of defining a module, this is exactly how it should be, as you can see below.




Inventory sample1 .png




When applying it to an agent, please make sure the operating systems are the same. If you encounter different operating systems, you're required to create a different module for each one of them, because the one which was shown here is not going to work for all of them.




Inventory sample2 .png




Once this module has been executed, the result could look like the one shown on the picture below.

800



Local Inventory by Software Agents

It's also possible to obtain the inventory data from a machine by using Software Agents. You're only required to apply the appropriate inventory modules within the software agent's configuration. Like in the remote modules, it's also necessary to add these modules as an inventory module under 'Operation' -> 'Manage Modules' and 'Inventory Modules'.

Creating Local Modules

In order to create a local module, please click on 'Administration' -> 'Manage Modules' and 'Inventory Modules'. This is the location in which all inventory modules created so far are listed. You're required to create all modules which are defined within the agent.



In22.png



In order to create a new module, please click on the 'Create' button.



In23.png



It's not necessary for the remote modules to complete all the fields. Now we're going to describe the fields you're encountering there:

  • Name: The field to insert the module's name.
  • Description: The field to insert the module's description.
  • OS: The combo to pick the operating system the module is intended for. For the location of modules, we recommend to use the option named 'Agent'.
  • Format: The field in which to insert the fields separated by the ';' character the module is going to return.

Once you have created the module, please click on the 'Create' button.



In24.png



Inventory Module by Software Agents within Windows Systems

The Windows Software Agent Module utilizes locally predefined WMIs to collect information about the machine's different software and hardware aspects.

The module syntax is the following:



In25.png



Now we're going to describe the fields you're required to fill out to add an inventory module within Windows-based machines:

module_begin: The beginning of any module of a software agent.

module_name: The field into which the module's name is inserted. In this case, it's 'Inventory'.

module_interval: The field which determines the module execution interval (in days). In this example, we're going to take '3 days'. Be mindful of errors within certain other documentations. It's not the module named 'module_inventory_interval', it's 'module_interval'. If the value is '0', the information will be sent on every execution of the agent.

module_type generic_data_string The value which defines data type in Pandora FMS. The of data for the inventory modules is 'generic_data_string'.

module_inventory CDROM Patches Software

The field where the inventory objects which we intend to collect are defined. In this example, we've collected 'CDROM', 'Patches' and 'Software'. In this field, the different parameters where the inventory objects which we intend to collect are defined. In order to add more objects, you're required to insert its name into the module named 'line_inventory'. It's possible to collect the following objects:

  • CPU: It obtains information about the CPUs.
  • RAM: It obtains information about the RAM modules.
  • CDROM: It obtains information about the CDROMs.
  • Video: It obtains information about the VGAs.
  • Hds: It obtains information about the hard drives.
  • Patches: It obtains information about the installed patches.
  • Software: It obtains information about the installed software.
  • Services: It obtains information about the services installed on the machine (no matter whether they're running or not).
  • NIC: It obtains information about network interface controllers.

module_description The field in which to insert the module's description. In this example, it's 'Inventory'.

module_end It's the end of any software agent's module. In order to activate the inventory module, you're required to copy the previously described code into the software agent's file named 'pandora_agent.conf'. This activation can be achieved locally on the machine or remotely from the agent's remote configuration.



In26.png



Inventory Module within UNIX Systems by a Software Agent

The UNIX software agent module locally utilizes a plug in to obtain information about different aspects of the machine from software and hardware.

The module's syntax is shown below.



In27.png



The module consists of one line and the following parameters:

  • Module activation



In28.png



  • The field which determines how often the module will be executed (in days). If the value is '0', the inventory information is going to be sent on every agent execution.



In29.png



  • The field in which the defined inventory objects are collected.



In30.png



Just like in the Windows agent, it's possible to collect the following objects:

  • CPU: It obtains information about CPUs.
  • cdrom: It obtains information about CDROMs.
  • video: It obtains information about VGAs.
  • hd: It obtains information about hard drives.
  • nic: It obtains information about network interface controllers.
  • Patches: It obtains information about the installed patches.
  • software: It obtains information about the installed software.
  • process: The processes in execution on the server in this moment.
  • ram: It obtains information about the RAM modules.
  • filesystem: It obtains information about the system's partitions.
  • users: It obtains information about the users.
  • init_services: It obtains information about the initiated services.

You can find the plug in which collects the inventory in the directory named '/etc/pandora/plugins'.



In31.png



It's also possible to set the plug in to gather all available information. In this example, the plug in is going to obtain all daily information on the inventory:

# Plugin for an inventory on the agent (Pandora FMS Enterprise Version only)
module_plugin inventory 1

In order to activate the inventory module, you're required to copy the previously described code within the 'pandora_agent.conf' from the software agent's file. This activation could be achieved locally on the machine or remotely from the agent's remote configuration.



In32.png



Assigning Local Modules

It's not necessary to activate the modules in the agents defined within the console. If the modules have been created by clicking on 'Configuration' -> 'Inventory Modules' and configured in the software agent, they're going to appear directly within the agent in the console.



In33.png



Creation of Local Inventory Modules (which are executed from within the Agent)

In addition to the inventory systems which come 'by default' within the agent, you may create inventory modules for UNIX and Windows-based systems a lot easier than the remote modules. You're required to create a script which generates an XML file with the following structure:


<inventory>
<inventory_module>
<name>INVENTORY_MODULE_NAME</name>
<type>generic_data_string</type>
<datalist>
    <data>DATA1;DATA2;DATA3....</data>
</datalist>
</inventory_module>
</inventory>

Under 'INVENTORY_MODULE_NAME' you're required to use the exact module name which is going to be registered under Pandora FMS. Under 'DATA1;DATA2 ...' the data you intend to obtain is going to be located.

Supposing that you intend to get an ARP table and the IPs along with their interfaces (please review the previous example regarding the remote inventory modules). This is basically a slightly modified exit of the command 'arp -a'.

This time, we're going to develop a small script that's required under Windows. We're going to save it within the path named 'C:\tmp\windows_arp_inventory.bat'. The script consists of the following:


@echo off
echo ^<inventory^>
echo ^<inventory_module^>
echo ^<name^>ARP_Table^</name^>
echo ^<type^>generic_data_string^</type^>
echo ^<datalist^>
arp -a | sort | grep "[0-9]"  | grep -v ":" | gawk "{ print \"^<data^>\" $1\";\"$2\";\"$3 \"^</data^>\" }"
echo ^</datalist^>
echo ^</inventory_module^>
echo ^</inventory^>

You're required to modify the 'pandora_agent.conf' and insert the following line:

module_plugin cmd.exe /C C:\tmp\windows_arp_inventory.bat


Template warning.png

This script is going to be executed every five minutes, which represents the default agent's interval. If it has to be executed within another interval, you're required to code that logic into the script for yourselves.

 


In order to inherit the changes, please keep in mind to create an inventory module within Pandora FMS before restarting the agent.



Inventory sample4 .png



Please keep in mind that it's a local module. It neither has the field named 'interpreter' nor the 'code' fields filled out, but it already holds information about the operating system.

The results obtained here are the same as the ones we've got for the remote module's equivalent under Linux:



Inventory sample5 .png



There are a lot more local and remote inventory modules available for download within the Pandora FMS Module Library. Within this library, there are also a lot of modules which have been specifically designed for Pandora FMS, as you certainly have seen within this section.

Data Display for the Inventory

The inventory data which have been locally or remotely collected from a system can be viewed from the agent or the console's inventory menu.

Inventory Data Display in the Agent

To review the agent's collected data including its inventory, please go to the agent's 'Operation' menu and click on the 'Inventory' flap.



In34.png



It's possible to filter the information by the inventory or a free-text search. Since Pandora FMS versions 4 and above, the searches include custom fields. It's very useful to search e.g. for a specific version of a software:



Inventory search 403.png



Inventory Data Display in the Inventory Menu

By clicking on 'Monitoring' -> 'Inventory', it's possible to view all agents inventory data, to conduct searches and to export data to a CSV file.



In37.png



The fields which could be used for searches are the following:

  • Group: The combo in which you're able to pick the group of agents you intend to filter by.
  • Module: The combo in which you're able to pick the inventory module you intend to filter by.
  • Agent: The field in which you're able to insert the agent's name you intend to filter by.
  • Search: The field in which you're able to insert a text in order to conduct a search by using all inventory fields.

It's also possible to see all agent's modules which have an inventory by selecting 'All' within the search options and clicking on 'Search'.



In38.png



It's also possible to search on a specific module in all agents with inventory by selecting the module and clicking on 'Search'.



In39.png



Exporting the Inventory Data to CSV

By clicking on 'Monitoring' and 'Inventory' it's possible to export the inventory data which are the result of a filtering to a CSV file.

Please pick the filter. Once there is any data present, please click on 'Export to CSV'.



In40.png



It has created a file which contains the inventory data, separated by a semicolon.

Diff view and Block mode

From version 5.1 of Pandora FMS the inventory information can be viewed in two columns so differences can be spotted easily. This only works when you are using remote inventory modules with "block mode" enabled. This mode is used to set the module to report all information as a single piece of information, instead a list of small items of information, like a list of packages in the server. Instead processing each line as a single entity, it process the whole report as a single item.

Plugin we use in this chapter can be downloaded from official module library at [1]

Inventory module Block mode is configured when you define a remote inventory module:



Block mode setup.png



To access this feature you must click on the icon that appears in the following image. All other inventory modules WITHOUT that mode, will not allow you to have "diff view". In this screenshot, the only moduel with diffview enabled is the third one:



Diff inventory.png



In the two column view all differences are shown between one inventory version and another. We can even set a different date.



Pandora FMS - the Flexible Monitoring System - 2014-07-01 19.09.10.png



Remember each time an inventory module detect a change it reports an event. In block mode, that event will not contain the changes, because could be very extense.


Go back to Pandora FMS Documentation Index