This is an old revision of the document!


Inventory

Inventory

Introduction

Pandora FMS Enterprise Version allows you to keep an inventory of the devices monitored by Pandora FMS. Thanks to this inventory, it is 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 obtained either locally (by Pandora FMS Software Agents) or remotely.

Data Collection for the Inventory

Data collection for system inventory is carried out in two different ways: Remotely through inventory modules, through scripts integrated within Pandora FMS which perform WMI queries or through scripts executed by means of SSH along with Expect or similar methods.

Locally using the Pandora FMS Agent, through agent plugins.

Inventory Modules

Inventory modules are remote modules that execute a command against a remote machine. These modules work in a similar way as a plugin does. The same modules could be defined as 'locals' if they obtain data through an agent.

In the User and Password parameters the following macros can be used:

  • _agentcustomfield_n_: Agent number custom field.

Remote Inventory

Creating remote modules

The creation of a remote inventory module by an administrator is seen as unusual. These inventory modules are already 'preconfigured' in 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, go to ConfigurationInventory Modules where all created inventory modules appear.

In order to create a new module, click Create.

OS: The operative system the module is created for.

Interpreter: Field featuring the command interpreter to be used within the module. It can be Shell Script, Perl or any other valid interpreter for the Inventory Server which is executed on a Linux system. Leave blank if it is a local module.

Block mode: It shows and detects configuration changes.

Format: It shows the fields returned by the module separated by the ; character.

Code: Module code. It is usually Perl or Shell Script. If you intend to use binary code here, it will require a different loading procedure which is required to be entered by peripheral scripts. Leave blank if it is a local module.

It is very important to choose the operative system correctly, because when adding inventory modules to an agent, only those whose module operating system and agent operating system match will appear.

Once the module is created, click on Create:

Editing Remote Modules

In order to edit a remote module, go to ConfigurationInventory Modules where all the inventory modules created so far are listed. Click on the module you intend to edit or on the wrench from the Action column.

The module creation window will appear again.

Edit the desired fields and click on the Update.

Deleting remote modules

In order to delete a remote module, go to ConfigurationInventory Modules, where all the inventory modules created so far are listed. Click on the trash icon located in the Action column of the module you intend to delete.

Each of them has a verification checkbox with which to select in bulk instead of deleting them one by one.

Assigning remote modules

Inventory modules are assigned within the agent's administration tab.

Click on the Inventory tab.

This is the menu where you may add the new inventory modules.

These are the fields that must be filled out when adding an inventory module.

  • Module: Choose the inventory module you intend to add. Only the modules that match the agent's operating system will appear.
  • Target: The IP or server name you intend to obtain the inventory from.
  • Interval: Time interval when the inventory module will be executed.
  • Username: User used 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, click Add in order to add the new module to the other inventory modules.

From version v7.0NG.724 onwards, it is possible to define fields instead of the user and password fields that normally exist. To do that, the following checkbox must be activated:

After doing this, a control to add new fields will appear:

In this control, enter the desired name before adding it. If you indicate that the field will contain a password, the value will be saved in the database in a obfuscated way.

After creating the fields, give them a value and finally add the module. These fields will be applied in order of creation in the execution of the remote inventory script.

Editing an assigned inventory module

You may also edit the inventory modules. This editing is carried out on the same page where they were previously created.

In order to edit an inventory module, click on the module's name or on the wrench icon which is shown on the picture below.

Deleting an assigned inventory module

It is possible to delete inventory modules. This deletion process is carried out on the same page where they have been previously created.

In order to delete an inventory module, click on the trash icon located in the module's Action column.

Complete example of a remote inventory module

Suppose you are required to obtain a list of physical addresses from a server - in this case a UNIX server. This is usually achieved through the arp -a -n command. If executed on a server, it will return something like this:

[email protected]:~$ 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 you are looking for is the IP and the MAC addresses and the adapter's name.

This could be achieved by using a shell script like this, using “ ” to separate the fields:

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

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

At this point, you need some programming knowledge to develop your own scripts or modify some. Although remote inventory scripts are not very complex, they require some knowledge of Perl, Shellscript or other interpreted languages. You may also write them in Java or C++ and call up their execution from the module as long as it returns the values of each field separated by the ; character and takes a new line for each line of data.

#!/usr/bin/perl
##########################################################################
# pandora_linux_arptable.pl
##########################################################################
# Copyright (c) 2012 Sancho Lerena <[email protected]>
#           (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, copy the root user's public key. If the target computer has the following IP adress, for example, 192.168.50.10. Follow the below mentioned steps:

1. Create a new key on the Pandora FMS Server as root. Fill in the requested fields.

ssh-keygen

2. Use the command ssh-copy-id to copy the public key on the target server (192.168.50.10) along with the target user (in this case, the user artica):

ssh-copy-id -i /root/.ssh/id_rsa.pub [email protected]

Enter the user password artica once on 192.168.50.10 in order to install the public key on the target user.

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

ssh [email protected]

4. If the process was successful, the process itself will be followed by the inventory Module, so try to execute it from the command line and save the previous script on the disk (temporal.pl) and execute it along with the IP and the user as parameters:

 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

Notice that the script remotely calls to /usr/sbin/arp. The command should be present within this path - if not, change the script. As you may have noticed, the script is called through the perl command, which is usually located at /usr/bin/perl. This is what you should configure when defining the module, as you can see below:

When applying it to an agent, make sure the operating systems match. If you have different operating systems, create a different module for each one of them, because the same code will not work on all of them.

Once this module has been executed, from the console you may access a view similar to the previous one:

Local inventory through software agents

It is also possible to obtain the inventory data from a machine by using Software agents. Just apply the appropriate inventory modules within the software agent's configuration. Like in remote modules, it is also necessary to add these modules as an inventory module under ConfigurationInventory modules.

Creating Local Modules

In order to create a local module, go to ConfigurationInventory modules where all inventory modules created so far are listed. Create all modules to be defined within the agent setup. The OS assigned to the console agent must match that of the created module.

In order to create a new module, click on Create.

The procedure is the same one used for the remote case, except for filling in the fields Interpreter and Code.

Once the fields have been filled in, click Create.

Local inventory setup for software agents

To adapt the software agent setup to the new version:

1. Deploy the script collection (download it from Pandora FMS library https://pandorafms.com/library/category/inventory/) through the collections.

From version 7 onwards, these plugins have agent installation by default, although they are commented in the configuration file.

2. Configure the local inventory script programmed execution in pandora_agent.conf file, adding this information at the end:

From version 7 onwards, there is no need to add it. Just uncomment the existing plugins in the agent configuration file.

Example for MS Windows®:

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\cpuinfo.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\moboinfo.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\diskdrives.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\cdromdrives.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\videocardinfo.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\ifaces.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\monitors.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\printers.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\raminfo.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\software_installed.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\userslogged.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\productkey.vbs"
#module_crontab * 12-15 * * 1
#module_end

#module_begin
#module_plugin cscript.exe //B //t:20 "%PROGRAMFILES%\Pandora_Agent\util\productID.vbs"
#module_crontab * 12-15 * * 1
#module_end
Inventory module within UNIX systems through software agent

The UNIX software agent module locally uses a plugin to retrieve information about different aspects of the machine, both software and hardware related.

The module's syntax is shown below.

module_plugin inventory 1 cpu ram video nic hd cdrom software init_services filesystem users route

The module consists of one line and the following parameters:

  • Module activation
" module_plugin inventory " 1 cpu ram video nic hd cdrom software init_services filesystem users route

</file>
  * Field where it is set how often the module will be executed (in days). If the value is 0, the inventory information will be sent **on every agent execution**.

<code>module_plugin inventory " 1 " cpu ram video nic hd cdrom software init_services filesystem users route

</file>
  * Field where the defined inventory objects are collected.

<code>module_plugin inventory 1 " cpu ram video nic hd cdrom software init_services filesystem users route "

</file>

Just like in the MS Windows® agent, it is possible to collect the following objects:

  * **CPU:**  It obtains information about CPUs.
  * **ram:** It collects information about RAM modules.
  * **video:**  It obtains information about VGAs.
  * **hd:**  It obtains information about hard drives.
  * **cdrom:** It collects information about the optical disk reading devices.
  * **nic:**  It obtains information about network interface controllers.
  * **patches:**  It obtains information about the installed patches.
  * **software:**  It obtains information about the installed software.
  * **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.
  * **Route**//://  It collects information about the system path table.
You may find the plugin that collects the inventory in the directory named ''/etc/pandora/plugins''

It is also possible to set the plugin to gather all available information. In this example, the plugin will obtain all daily information on the inventory:

<code>
 # Plugin for inventory on the agent (Only Enterprise)
 module_plugin inventory 1

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

Assigning Local Modules

It is not necessary to activate the modules in the agents defined within the console. If the modules have been created in ConfigurationInventory modules, the OS matches and the execution is defined in the software agent configuration file, the collected data will appear directly on the ViewInventory section of the console agent.

Creating local inventory modules (software agent)

In addition to the default inventory systems, you may create inventory modules for Unix® and Windows® systems easily.

Basically, it creates a script that 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>

INVENTORY_MODULE_NAME: The name should match that of the module that registered the inventory modules in Pandora FMS console.

DATA1;DATA2…: The data you intend to retrieve, which have been defined in the inventory module.

Suppose you intend to get an ARP table and the IPs along with their interfaces (see the previous example regarding remote inventory modules). Use the command arp -a and clean out the output to obtain the desired data.

Now to develope it in Windows® type in the script the C:\tmp\windows_arp_inventory.bat with the following definition:

@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^>

Modify the pandora_agent.conf and add the following line:

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

This script is executed every five minutes (the default agent interval). If you want it to be executed every X minutes, implement that logic into the script itself or use the programmed monitoring.

Remember: In order for the local script execution to store inventory information, it must have an inventory module defined in the console, specifying the OS, the module's name and the data to be stored separated by ;. Do not forget to create the inventory module in Pandora FMS before restarting Pandora FMS agent, so that it loads the changes, create Pandora FMS inventory module:

Make sure that when it is a local module, it has the Interpreter and Code fields empty and the OS one filled out.

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

There are a lot more local and remote inventory modules available for download within the Pandora FMS Module Library. You may also easily develop your own, as seen throughout this chapter.

Data display for the inventory

Inventory data that have been locally or remotely collected from a system can be seen from the agent or the console's inventory menu.

Inventory Data Display in the Inventory Menu

By clicking on MonitoringInventory, it is possible to view all agent inventory data, search and export data to a CSV.

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

  • Group: Choose the agent group you intend to filter by. The user will be able to see only the groups it belongs to, unless the user explicitly belongs to the ALL group.
  • Module: Choose the inventory module you intend to filter by.
  • Agent: Type in the agent name you intend to filter by.
  • Search: Type in a text in order to search by all inventory fields.

With searches it is also possible to see all module agents which have an inventory, by selecting All within the search options and clicking on Search.

Or a specific module in all agents with inventory by selecting the module and clicking on Search.

Inventory dates and changes

In the detail view of an inventory agent, you may choose the specific inventory report date you want to see through a selector:

If you see there are dates missing, it is likely to be due to data changes regarding the last inventory execution. That means, Pandora FMS only stores inventory data when these change compared to the last execution.

Exporting the Inventory Data to CSV

From Monitoring > Inventory it is possible to export inventory data which are the result of a filtering to a CSV file.

Choose the filter and once there is any data, click on Export CSV.

A file containing inventory data, separated by semicolon is created.

Inventory version differences

Block mode

From Pandora FMS version 5.1, inventory information can be viewed in two columns so differences can be spotted easily. Block mode specifies that the result of an inventory module is a single element, instead of interpreting each line as a different element of the same type, as it has been done in the previously seen inventory modules.

Block mode is configured when defining a remote or local inventory module:

When there is a module with block mode enabled, it allows seeing the divided view (to visually see the changes):

In the two column view, all differences between one inventory version and another are shown. Even the date filtering version can be seen.

Remember each time an inventory module change is detected, a new event will be generated.

Inventory alerts

The inventory alerts added in version 751 help launch specific alerts on the inventory content of an agent group. Similarly to SNMP alerts or event alerts, they are not applied agent by agent but rather they are global, in this case, they are applied by groups.

Inventory alerts are featured from version 751 (Dec/2020)

To configure them, go to section Alerts → Inventory alerts

Inventory alerts have fields similar to other alerts such as name, description, time threshold and action that do not require explanation if you know how to use Pandora FMS alerts. We will focus on what makes them different.

The group in this case works as alert term, so alerts will be evaluated for any data that comes from an agent of said group.

These alerts also have the option of disabling event help to not generate an alert event when the alert is triggered. It is useful since it is possible that with the inventory alert application many alerts might get triggered with a single execution. We recommend you to activate it unless you have a broad knowledge of what you are doing.

Alert triggering terms

Inventory alerts are applied in three different modes: simple match, white list and black list.

Text string match

That way, when a particular text string in a specific inventory module is received, e.g.: “software” the set action will be carried out. You have to bear in mind that inventory modules have dynamic fields; e.g. in the software inventory module there are name, version and description fields:

That way you may set an alert for any of the three dynamic fields, perfect for looking for a specific packages or a particular version package:

All inventory module fields will appear. In these fields you may add regular expressions to make more complex searches. If a field stays empty, it will count as .* (it will match any value).

Black list

In this case, specify just one field of the inventory module type, and specify a string list (one by line), so that if the agent contains an element from that list, the alert will fire. Think for example, in terms of software, that this black list is a software package list that must NOT be installed in the machine. If there is any from said list, the alert will fire.

White list

Similar to the previous one. Specify a list of elements, for one of the inventory fields, except this time, the inventory module value must be on one of the elements of the list, otherwise the alert will fire.

Inventory alert uses

This feature is perfect for detecting device vulnerable versions, non-authorized users in machines or non-authorized software in computers.

Go back to Pandora FMS documentation index