User Guide

Configuration

To install the Asset Management module, perform neteye-asset additional component installation by means of following steps in additional modules guide; the Asset menu item will then appear in the left side navigation menu. The module can be configured for:

Permissions

Access to GLPI from the NetEye GUI is granted by permissions of a particular user role. In order to create a role with mentioned permissions, go to the Assetmanagement module in Configuration > Authentication > Roles, where you can set suitable permissions and restrictions. It is recommended to inherit role properties from the default role neteye_tenant_master. This existing role should never be modified since it has all the GLPI Entity configurations.

The profile and entities in GLPI of users must be mapped correctly in the NetEye (Configuration > Authentication > Roles) to persist across login/logout otherwise the GLPI profile and entity will be lost as soon as the user logged out from NetEye.

Each NetEye role corresponds to a unique combination of GLPI recursive profile/entity. For example, if a user belongs to more than one entity, or has different profile inside GLPI, he should belong to multiple NetEye roles.

Note that, if the GLPI user role will inherit the neteye_tenant_master role properties, the already configured GLPI Entity Root entity > master will be used without additional configuration steps.

All entities and profiles must be created before users login for having a success permission synchronization. The only exceptions to this are the Root entity and the default GLPI profiles. If the profile/entities does not exist for the users in GLPI, then the mapping between NetEye and GLPI will not be successful.

Note that if you need to investigate on what happens during the permissions synchronization (e.g. for debugging purposes), you can have a look at the following logfile, in which are logged all the actions performed during the permissions synchronization:

/neteye/shared/glpi/data/_log/php-error.log

All the log messages printed during the SSO will be prefixed with GLPI-Plugin-Icingaweb2SSO.

Special Cases

There exist two special cases, with pre-defined triple recursive-profile-entity:

  • NetEye users with Administrative Access

  • NetEye users with Full Module Access for the Assetmanagement

Both cases correspond to users with Super-Admin recursive profile in the Root entity.

Note that for any reason you must not rename the GLPI Super-Admin profile and the Root entity.

Single Tenancy

As described in the concept section, for correctly performing an inventory the system should have the following configuration:

  • the Master Entity configured in the GLPI server

  • a NetEye user and role for the GLPI Agent that ensure that the inventory is sent to the correct Entity

  • GLPI Agents installed on the desired device and configured as described in Asset collection methods

NetEye is preconfigured with a default user and role named neteye_glpi_agent_master for the Agent related to the Master Entity. By default the Agent can act on the Root entity > Master entity, that is automatically created during Assetmanagement Module configuration.

In order to send assets directly to the GLPI Root entity, you can modify the GLPI entity of the parent role neteye_tenant_master with the following command:

neteye tenant config modify master \
--custom-override-glpi-entity "Root entity"

It is also possible to specify other GLPI Entities as main entity for the tenant master role. If you’re planning to utilize multple tenants in future, it is not recommended to override the default GLPI Entity. In any case the role neteye_tenant_master should never be modified by hand. More information can be found in neteye tenant config create.

Note

The Root entity > Master entity can be deleted in case you want to directly use the Root entity or another custom entity for inventory.

To start collecting assets, you can choose to run in agent-based or agentless configuration. All the configuration details can be found in the Asset collection methods section.

Multi Tenancy

Asset Management features in a Multi-tenancy environment can only be used if enabled for a specific Tenant. Execute the following command to enable it:

neteye teneant config modify <tenant_name> \
--enable-module "neteye-asset"

If the Tenant still doesn’t exist, follow neteye tenant to configure it properly.

If Multitenancy is used in GLPI, when creating a new NetEye Tenant as described in Configuration of Tenants, a dedicated GLPI Entity Root entity > 'New Tenant' will be created. All the users belonging to that Tenant should then be associated to the automatically created role neteye_tenant_<tenant_name> in order to have access to the Tenant’s entity in GLPI. For every new tenant created, there will be a connected user named neteye_glpi_agent_<tenant_name> that can be used for assets collection.

Warning

NetEye Roles, Users and GLPI Entities automatically created with the neteye tenant config create should never be modified to avoid permission issues or profile/entity mismatch between NetEye and GLPI.

Once the Tenant is configured to receive assets, agent-based or agentless mode can be selected as asset collection methods. All the configuration details can be found in the Asset collection methods section.

Asset collection methods

Asset collection can be performed with the help of GLPI Agent software that can be used in two different ways: agentless or agent-based. To correctly install and configure the GLPI Agent software, the following steps should be executed:

  1. Install GLPI Agent on the desired device following the official GLPI documentation. GLPI Agent can be installed on both Linux and Windows nodes that are external to the NetEye environment. For Windows installation we recommend to use the .msi package.

    Hint

    In order to execute glpi-agent and glpi-remote commands on Windows machines, be sure to operate as administrator from the GLPI-Agent folder.

  2. Find credentials for the agent: GLPI Agent has a dedicated NetEye user called neteye_glpi_agent_<tenant_name> authorized to send assets to the Master. User’s password can be found in /root/.pwd_neteye_glpi_agent_<tenant_name> and should be used for authentication when sending inventories.

    For installations with a Single Tenant the default credentials are:

    • user: neteye_glpi_agent_master

    • password can be found in /root/.pwd_neteye_glpi_agent_master.

  3. Configure the user and password credentials for the agent in the config file on the system.

  4. Choose the node where to send assets:

    • Master: GLPI Agent can send inventories directly to the Master. In that case, the Master hostname should be used as <neteye_addr>.

    • Satellite: In order to use a Satellite as a proxy to forward assets to the Master, the Satellite hostname should be selected as <neteye_addr>

After the first configuration parts has been executed, agent-based or agentless mode should be selected to start collecting assets.

Agent-based

The inventory can be performed on the node where the GLPI Agent software is installed with the following command:

Linux:

glpi-agent -f --logger=stderr \
-s https://<neteye_addr>/glpi/front/inventory.php \
--tasks inventory

Windows:

glpi-agent -f --logger=stderr ^
-s https://<neteye_addr>/glpi/front/inventory.php ^
--tasks inventory

Where <neteye_addr> is the address of the endpoint, as previously described. Once the inventory has been performed, the GLPI Agent will send it to the specified target hostname.

More information about the glpi-agent command can be found in glpi-agent.

Agentless

If no software can be installed on the devices from which assets are collected, agentless mode can be selected. A GLPI Agent server will perform the inventory on remote devices and subsequently send assets to the Master. Note that the software GLPI Agent should not be installed on remotes, but only on a separate node that will act as a server that performs the remote inventory.

Hint

We recommend to use agent-based asset collection method over agentless when applicable, since involving agents in the asset collection process proves to be a more secure solution.

../../_images/agentless-diagram.svg

Fig. 244 GLPI Agent performs inventories to the remote devices.

Windows remote configuration In order to establish a secure connection with a Windows remote WinRM with transport HTTPS should be correctly configured for a SSL connection. Detailed information can be found in the official Microsoft guide.

GLPI Agent, used as a server between remotes and NetEye, should be configured as it follows:

Linux server configuration

  1. Specify the target server: Using agentless mode, the target server should be declared before inserting the remotes. You should specify the previously defined parameters with the command:

    glpi-agent \
--server=https://<neteye_addr>/glpi/front/inventory.php

  2. Extract the ID of the specified target server with the command:

    glpi-remote list targets

  3. Add remote devices with the following command:

    For a Linux remote machine:

    glpi-remote \
add ssh://<remote_user>:<remote_pass>@<addr>/?mode=libssh2 \
--target <server_id>

    Hint

    Make sure to have the perl library Net:SSH2 installed by executing the command perl -e "use Net:SSH2. libssh2 should also be installed on the server machine.

    For Windows remotes:

    glpi-remote \
add winrm://<remote_user>:<remote_pass>@<addr>/?mode=ssl \
--target <server_id>

    • <remote_user> and <remote_pass> are the credentials that GLPI Agent should use on remotes to perform the inventory

    • <addr> is the IP address or hostname of the remote device

    • <server_id> is the ID of the previously inserted target server that can be shown with the glpi-remote list targets command.

    Warning

    NetEye Security is granted only if mode=libssh2 and mode=ssl are used for Linux and Windows remotes respectively.

    Hint

    By exchanging ssh keys, <remote_pass> is not needed when adding the remote device.

  4. Execute the remote inventory task of the GLPI Agent to collect assets and send them to the Master:

    glpi-agent -f --logger=stderr --tasks remoteinventory \
-s https://<neteye_addr>/glpi/front/inventory.php

Where <neteye_addr> is the address of the endpoint, as previously described in the Asset collection methods Once the inventory has been performed, the GLPI Agent will send it to the specified target hostname.

Windows server configuration

  1. Specify the target server: Using agentless mode, the target server should be declared before inserting the remotes. You should specify the previously defined parameters with the command:

    glpi-agent ^
--server=https://<neteye_addr>/glpi/front/inventory.php

  2. Extract the ID of the specified target server with the command:

    glpi-remote list targets

  3. Add remote devices with the following command:

    For a Linux remote machine:

    glpi-remote ^
add ssh://<remote_user>:<remote_pass>@<addr>/?mode=libssh2 ^
--target <server_id>

    Hint

    Make sure to have the perl library Net:SSH2 installed by executing the command perl -e "use Net:SSH2. libssh2 should also be installed on the server machine.

    For Windows remotes:

    glpi-remote ^
add winrm://<remote_user>:<remote_pass>@<addr>/?mode=ssl ^
--target <server_id>

    • <remote_user> and <remote_pass> are the credentials that GLPI Agent should use on remotes to perform the inventory

    • <addr> is the IP address or hostname of the remote device

    • <server_id> is the ID of the previously inserted target server that can be shown with the glpi-remote list targets command.

    Warning

    NetEye Security is granted only if mode=libssh2 and mode=ssl are used for Linux and Windows remotes respectively.

    Hint

    By exchanging ssh keys, <remote_pass> is not needed when adding the remote device.

  4. Execute the remote inventory task of the GLPI Agent to collect assets and send them to the Master:

    glpi-agent -f --logger=stderr --tasks remoteinventory ^
-s https://<neteye_addr>/glpi/front/inventory.php

Where <neteye_addr> is the address of the endpoint, as previously described in the Asset collection methods Once the inventory has been performed, the GLPI Agent will send it to the specified target hostname.

More information about the glpi-remote command can be found in glpi-agent.

Display asset information in monitoring host page

When asset management module is installed,|NE| will automatically search for the host inside GLPI to fetch its information and display it in the dedicated host detail page in icingaweb2 monitoring. The following guide details different ways to refine the search or force a link to a specific asset.

Note

To enable this feature for a user you need to have glpi/monitoring permission enabled under the assetmanagement section.

Search for asset information in GLPI by hostname

The default method to identify the icingaweb2 host in GLPI to then fetch its information is searching the hostname (FQDN), stripped of the domain part in GLPI. For example openshift01.wp.dach.local will be searched as openshift01.

The asset information will be displayed only when there’s a single search result. If multiple matches are found on GLPI, it’s possible to further filter results by status as detailed in the section below, to possibly end up with a single one.

Linking hosts to assets directly

It is also possible to force the link between a host and a specific asset by specifying an Asset ID and Asset Type as custom variables in the host configuration Custom properties collapsable section.

../../_images/link-asset-to-host-directly.png

Note

The Asset ID is the GLPI asset ID and can be found in the asset page URL in GLPI (i.e. https://<neteye_addr>/glpi/front/computer.form.php?id=20), while the Asset Type is the asset type in GLPI. Currently, only Computers and Network devices are supported.

Warning

Both Asset ID and Asset Type must be specified to link an asset directly to a host. If only one of them is provided, search by hostname will be performed as fallback instead.

Filtering search results by status

Since asset fields will be displayed only when there’s a single search result, it is possible to filter the assets retrieved by status to reduce the number of results.

It can be done globally at module configuration level, or on a per-tenant basis.

To do so globally, strings specifying active values can be provided at module configuration level in the /neteye/shared/icingaweb2/conf/modules/assetmanagement/config.ini file, under the [glpi-monitoring-integration] section, as a comma-separated string of values:

[glpi-monitoring-integration]
asset_status_active = "active,enabled,ok"

The same can also be done at Tenant level, which will override the global configuration at module level detailed above. To achieve that, a tenant must be specified in the NetEye collapsable section inside host configuration page:

../../_images/specify-host-tenant.png

Subsequently, the tenant-specific configuration can be set via the new --override-glpi-asset-active-statuses option of the neteye tenant config command. See neteye tenant for more information.

Asset displayable fields

By default, the following fields will be displayed in the monitoring host page:

Table 81 Asset fields

Name

The name of the asset in GLPI, should be the same as the hostname (minus the domain part).

Type

Only Computer and Network Equipment asset types are supported.

Location

The asset geographical location.

Status

The status assigned to that specific asset, filterable by custom values.

Serial number

The asset serial number.

Inventory number

The asset inventory number.

Manufacturer

The asset manufacturer.

OS Name

The name of the additional tab Operating systems in GLPI.

OS Version

The version of the additional tab Operating systems in GLPI.

Technician

The technician assigned to the asset.

Alternate username

The concatenation of Alternate username and Alternate username number of the asset.

GLPI link

Auto generated link to the asset in GLPI.

Note

In the event the search returns multiple assets, a warning will be displayed along a link to the search results directly in GLPI.

Hide specific asset fields in host page

Specific fields can be omitted from the asset information displayed in the monitoring host page.

They can be specified globally at module configuration level, or on a per-tenant basis.

To do so globally, strings specifying active values can be provided at module configuration level in the /neteye/shared/icingaweb2/conf/modules/assetmanagement/config.ini file, under the [glpi-monitoring-integration] section, as a comma-separated string of values:

[glpi-monitoring-integration]
asset-hidden-fields = "name,type,serial"

The same can also be done at Tenant level, which will override the global configuration at module level detailed above. To achieve that, a tenant must be specified in the NetEye collapsable section inside host configuration page:

../../_images/specify-host-tenant.png

Subsequently, the tenant-specific configuration can be set via the new --set-glpi-asset-hidden-fields option of the neteye tenant config command. See neteye tenant for more information.

The list below is a reference of all fields that can be hidden, with their string identifiers in the configuration:

Table 82 Asset fields identifiers

name

is the identifier for the asset name field.

type

is the identifier for the asset type field.

location

is the identifier for the asset location field.

status

is the identifier for the asset status field.

serial

is the identifier for the asset serial number field.

inventory

is the identifier for the asset inventory number field.

manufacturer

is the identifier for the asset manufacturer field.

os_name

is the identifier for the asset OS name field.

os_version

is the identifier for the asset OS version field.

technician

is the identifier for the asset technician field.

username

is the identifier for the asset alternate username and Alternate username number fields.

link

is the identifier for the asset GLPI link field.