ToolBox interface

ToolBox is a simple web interface embedded into GLPI Agent that allows users to configure some features when there is no GLPI server available.

For example:

  • When you have an isolated network that cannot or should not be connected to a GLPI Server or via GLPI Agent Proxy Server Plugin for any reason but you still need to run a network discovery or a network inventory.

  • When you need to review and update the inventory with custom fields which can be setup using a YAML file exported from GLPI Fields plugin.

Here are the main features ToolBox provides:

  • manage inventory task jobs (available since GLPI Agent 1.6)

  • manage credentials definitions

  • manage ip range definitions

  • manage scheduling definitions (available since GLPI Agent 1.6)

  • display light inventory results and eventually edit custom fields

  • manage remotes definition (deprecated since GLPI Agent 1.6)

  • manage mibsupport rules to tune the results for SNMP network devices

Note

ToolBox is not intended to replace a plugin like GlpiInventory or FusionInventory for GLPI plugins but can be helpful where none of these plugin can or should be used for any reason.

See also

Don't miss the Unlocking Efficient Network Inventory Management with the GLPI Agent Toolbox Plugin blog post including this demo video by Arthur Schaefer:

Again ToolBox is mainly a GLPI-Agent based tool allowing to run a netscan tasks over a network only using a glpi-agent and a browser. Netscan task is firstly used to discover and inventory networks devices or printer supporting SNMP, but now (available since GLPI Agent 1.6), it also supports to discover and inventory computers like ESX, Unix/Linux supporting ssh and windows computers supporting WinRM using RemoteInventory task.

Run tasks results can be stored in the agent environment and you can browse them on Results dedicated pages. But (available since GLPI Agent 1.6) you can also simply and directly send them to a GLPI server, without storing them locally. You can indeed select as job target any glpi-agent configured target (local or server) or the local glpi-agent installation folder.

Note

Since GLPI Agent 1.5, ToolBox also permits to manage RemoteInventory task by defining and updating remotes. It can also be used to expire remotes and require a remoteinventory task run to handle any expired remotes right now. The interface is really basic: it doens't show the status of a remote and you'll still have to audit your agent log if some remotes are failing to upload an inventory in GLPI.

For this reason, and as GLPI Agent 1.6 will provide a netscan feature supporting RemoteInventory task, the remotes page is deprecated and will be removed in a future version.

Setup

By default, this plugin is disabled. So the first required step is to enable it creating a dedicated configuration:

  1. Locate the toolbox-plugin.cfg file under the GLPI agent configuration folder [1],

  2. Make a copy - avoid renaming it - of this file in the same folder by just changing the file extension from .cfg to .local.

  3. Edit the toolbox-plugin.local and set disabled to no and comment or remove the include directive at the end

  4. Restart the glpi-agent service

This way, the agent will start to accept toolbox requests on its current port and on /toolbox as base url, by default: http://127.0.0.1:62354/toolbox

Warning

By default, anybody can access this feature after it has been enabled. You should first set forbid_not_trusted = yes in your toolbox-plugin.local to enable a "by trusted IP address" filtering, authorizing IP only enabled with the httpd-trust option.

You MUST not enable ToolBox on an unsecure network.

Also, since GLPI Agent 1.5, you can enable Basic Authentication Server Plugin and SSL Server Plugin to completely secure the ToolBox interface.

By default, you have a very restricted interface displayed on the first access. But you can edit everything under the setup page clicking on the top right gear icon. That is where you can activate additional pages in the Navigation bar section.

You should enable the following pages:

  1. Credentials: to manage SNMP credentials, ESX user/password, SSH and WinRM credentials for RemoteInventory netscan

  2. Inventory: to configure and manage jobs for local or netscan inventory tasks

  3. IP Ranges: to manage ip ranges and to define credentials to use on each one

  4. Scheduling: to define scheduling to be used by inventory jobs

You can disable the Results page if your glpi-agent will directly submit inventories to a GLPI server and you won't use the local agent installation folder as target.

Note

After you have configured your interface, you can disable any further online configuration to avoid mistake by disabling the Configuration update authorized checkbox in the Toolbox plugin configuration section.

If you need to tune again the configuration, you need to edit the toolbox.yaml file and change the updating_support line in the configuration section like:

configuration:
   updating_support: yes

Credentials

Initially, the credentials page will show you it found no credential:

../_images/credentials.png

So it essentially gives you access to the Add Credential button.

Create a credential

You can quickly create a new credential after you have clicked on the Add Credential button on the Credentials list page:

../_images/credentials-new.png

You have then a simple form permitting you to set a Name, choose a Type and when applicable:

  1. Set the SNMP version

  2. Set the SNMP community

  3. Set the SNMP port if different than the default 161

  4. Set the SNMP protocol, the default beeing udp

  5. Set the SNMP username for SNMP v3

  6. Set the SNMP authentication password for SNMP v3

  7. Set the SNMP authentication protocol for SNMP v3

  8. Set the SNMP privacy password for SNMP v3

  9. Set the SNMP privacy protocol for SNMP v3

  10. Set the username for a remote credential (ssh, winrm or esx)

  11. Set the authentication password for a remote credential

  12. Set the remote authentication port if different than the defaults: 22 for ssh, 5985 for winrm or 5986 for winrm with ssl mode enabled

  13. Enable one or more remote inventory mode for ssh or winrm

You can also define a description for this credentials if this can help you to manage them. It is not used by GLPI Agent and it's up to you to use it.

The name is free but mandatory and will be used as key name to associate it to IP ranges. So choose it carefully to be meaningful for your credentials management.

Note

Passwords are not shown but you have an eye icon on right of the field to click on if you need to check them.

When you click on Create Credential, the agent will check few field and will add it to the list unless something is wrong:

../_images/credentials-added.png

From the credentials list, you'll always have the option to edit or delete a credential.

You also can move you mouse pointer other the config column to check few details. Passwords won't be shown:

../_images/credentials-config.png

Update a credential

To update a credential, you simply can click on the Credential name in the Credentials list page:

../_images/credentials-edit.png

You obtain the same form as for creation. And from here, you can:

  1. Rename the credential

  2. Update any credential setting

  3. Click on Update to save your changes

  4. Click on Go back to list or on Credentials in the navigation bar to return to the list.

Delete a credential

For credential deletion, from the Credentials list, you have to click on the related checkbox, and click on the Delete button.

Warning

Deletion will be forbidden in the case a credential is still in use. If you really need to remove a credential, first remove it from all associated IP ranges.

IP Ranges

Initially, the IP ranges page will show you it found no IP range:

../_images/ip_ranges.png

So it essentially gives you access to the Add new IP range button.

Create an IP range

You can quickly create a new IP range after you have clicked on the Add new IP range button on the IP range list page:

../_images/ip_ranges-new.png

You have then a simple form permitting you to first set:

  1. the IP range Name

  2. the IP range start

  3. the IP range end

These fields are all mandatory to define an IP range.

The name format is free and will be used as a key name to associate it to an inventory job. So choose it carefully to be meaningful for you.

You can also define a description for this IP range if this can help you to manage them. It is not used by GLPI Agent and it's up to you to use it.

Note

If you only need to scan one IP, just use this ip as first and end ip of the range.

Also you should use an explicit name which will permit you to identify this ip range as targetting only one IP.

You would like also to associate one or more credentials to this new IP range. In ToolBox, an IP range without at least one credential will be useless during netscan, so you should at least have created a first credential before.

When you click on Add IP range, the agent will check few fields and will add it to the list unless something is wrong:

../_images/ip_ranges-added.png

From the IP Ranges list, you'll always have the option to edit or delete an IP range. But you'll also have a mass action to add or remove one credential to your IP ranges. This is handy when you want to quickly update a lot of IP ranges.

You also can move you mouse pointer other the credentials column to check related associated credential details. Passwords won't be shown:

../_images/ip_ranges-credential-details.png

Update an IP range

To update an IP range, you simply can click on the IP range name in the IP Ranges list page:

../_images/ip_ranges-edit.png

You obtain the same form as for ip range creation. And from here, you can:

  1. Rename the IP range

  2. Change the start and the end of the IP range

  3. Unselect any associated credential

  4. Associate another credential, only if another credential is available

  5. Click on Update to save your changes

  6. Click on Go back to list or on IP Ranges in the navigation bar to return to the list.

Delete an IP range

For IP range deletion, from the IP Ranges list, you have to click on the related checkbox, and click on the Delete button.

Warning

Deletion will be forbidden in the case an IP range is still in use. If you really need to remove an IP range, first remove it from all associated netscan inventory tasks.

Scheduling

Initially, the scheduling page will show you it found no scheduling:

../_images/scheduling.png

So it essentially gives you access to the Add new scheduling button.

Create a scheduling

You can quickly create a new scheduling after you have clicked on the Add new scheduling button on the Scheduling list page:

../_images/scheduling-new.png

You have then a simple form permitting you to first set:

  1. the scheduling Name

  2. the Type

  3. the delay configuration or timeslot configuration

The name remains mandatory to define a scheduling.

The name format is free and will be used as a key name to associate it to an inventory job. So choose it carefully to be meaningful for you.

You can also define a description for this scheduling if this can help you to manage them. It is not used by GLPI Agent and it's up to you to use it.

When you click on Add, the agent will check few fields and will add it to the list unless something is wrong:

../_images/scheduling-added.png

From the Scheduling list, you'll always have the option to edit or delete a scheduling. The scheduling details are shown in the configuration column.

Create a delay scheduling

When you create a scheduling, you have to choose the delay type. You can than configure the delay choosing a number for the delay and select a time unit from the given list:

../_images/scheduling-delay-configuration.png

Create a timeslot scheduling

When you create a scheduling, you have to choose the timeslot type. You can than configure the timeslot choosing a week day or all, a day time start hour and minute, a duration number and a time unit for the duration to choose between minute or hour:

../_images/scheduling-timeslot-configuration.png

Update a scheduling

To update a scheduling, you simply can click on the Scheduling name in the Scheduling list page:

../_images/scheduling-edit.png

You obtain the same form as for scheduling creation. And from here, you can:

  1. Rename a scheduling

  2. Update the delay duration or the timeslot configuration

  3. Click on Update to save your changes

  4. Click on Go back to list or on Scheduling in the navigation bar to return to the list.

Delete a scheduling

For scheduling deletion, from the Scheduling list, you have to click on the related checkbox, and click on the Delete button.

Warning

Deletion will be forbidden in the case a scheduling is still in use. If you really need to remove a scheduling, first remove it from all associated inventory tasks.

Inventory tasks

Initially, the inventory page will show you it found no inventory task:

../_images/inventory.png

So it essentially gives you access to the Add new inventory task button.

Create an inventory task

You can quickly create a new inventory task after you have clicked on the Add new inventory task button on the Inventory tasks list page:

../_images/inventory-new.png

You have then a simple form permitting you to first set:

  1. the inventory task Name

  2. the Type between Local inventory and Network scan

  3. a target to choose between Agent folder and the configured ones via server or local parameters

  4. a scheduling type

  5. a delay or one or more timeslots depending on the choosen scheduling type

  6. an optionnal tag to use on computers inventory

  7. an IP range to associate if the task type is Network scan

  8. a threads count if the task type is Network scan and to parallelize the task run

  9. a connection timeout to use during Network scan

The name remains mandatory to define an inventory task.

The name format is free but choose it carefully to be meaningful for your tasks management.

You can also define a description for this inventory task if this can help you to manage them. It is not used by GLPI Agent and it's up to you to use it.

Warning

Local inventory task should not be configured via ToolBox as this remains the first GLPI Agent role when inventory task is not disabled in agent configuration.

This inventory task type should probably only be used for tests or when you need to run it manually from a portable installation, for example using an usb disk on a computer in an isolated networtk.

When you click on Create inventory task, the agent will check fields and will add it to the list unless something is wrong:

../_images/inventory-task-added.png

From the Inventory tasks list, you'll always have the option to edit or delete a task. Some task details are shown in the configuration column. You can now select the task and ask a run. You can also enable or disable the task. The scheduling will only be used when the task is enabled.

Run an inventory task

An inventory task can be run in 2 cases:

  1. manually after it has been selected in the Inventory tasks list and the Run task button is clicked

  2. after the task has been enabled (select the task and click on Enable) and the agent finds the task scheduling configuration triggers the task

../_images/inventory-task-run.png

After a task has been run, you can see a progression bar. You can click on the eye or report icons to develop the task and access more details or features:

../_images/inventory-task-run-details.png

Update an inventory task

To update an inventory task, you simply can click on the Task name in the Inventory task list page.

You obtain the same form as for inventory task creation. And from here, you can:

  1. Rename the inventory task

  2. Change the target

  3. Change the used scheduling

  4. Change the tag

  5. Change the ip range if the task type in Network scan

  6. Click on Update to save your changes

  7. Click on Go back to list or on Inventory tasks in the navigation bar to return to the list.

Delete an inventory task

For inventory task deletion, from the Inventory tasks list, you simply have to click on the related checkbox, and click on the Delete button.

Note

You can also prefer to just disable the task and only delete it after you're sure it won't be used anymore.

Configuration files

There are few files used to configure ToolBox:

  • toolbox-plugin.cfg: This file permits to setup if and how the GLPI-Agent ToolBox plugin integration

  • toolbox.yaml: This YAML file will contains a configuration section to tune your ToolBox experience but it will also contain your inventory, credentials, ip ranges & scheduling configurations. As such this file MUST be secured as much as possible as it will include very sensible data like you defined credentials.

    Note

    The toolbox.yaml file can be backed up when clicking on the Backup YAML button in the ToolBox plugin Configuration page. This eventually creates a backup folder at the same level if it doesn't exist. And it creates a copy renamed with a timestamp in that backup sub-folder.

    A container can also be setup to support Custom Fields but you can also just copy the file downloaded from GLPI Fields plugin and select it in the dedicated Custom fields YAML file entry in configuration page. Be aware, this feature only make sens if you planned to edit locally stored network inventories before injecting it manually to a GLPI server. This feature has been developed to help people needing to scan a private network. It permits to edit manually few custom datas before uploading.

Footnotes