Documentations

Integrating client plugins into ServiceNav

On the page

Need some help?

Disclaimer

Scope of application

This documentation applies only to ServiceNav platforms in dedicated mode. This feature is not present for use of ServiceNav in SaaS mode. For any request for a new plugin on an installation in SaaS mode, please contact Coservit support.

Limitations of liability

The integration of new plugins outside of the ServiceNav product upgrades is carried out under the Customer's responsibility. Coservit can provide methodological or technical support within the framework of a project, the terms and conditions of which are to be defined between the Customer and Coservit.

Coservit cannot be held responsible for a malfunction of the ServiceNav product if the cause is the integration (including a new plugin out of the catalogue), or any other modification made to the product outside of those described in the user documentation. Any intervention by Coservit to diagnose or repair a malfunction caused by any plugin integration (including a new plugin not included in the catalogue) or any modification made to the product outside of those described in the user documentation will be invoiced under the terms of the contract established with the Customer or the order established prior to Coservit's intervention.

Copyright

The installation of any file carried out by the Customer implies his responsibility for the respect of intellectual property in general, and copyright in particular. Coservit cannot be held responsible in the event of legal action for non-respect of intellectual property concerning a file installed by the Customer.

Background

Coservit offers a large catalog of plugins for many needs. For more specific needs, and on a dedicated installation only, it is possible to create your own complementary plugins.

Concepts

The plugin is a program that runs on the ServiceNav Box. It may need software libraries.
This program is defined by :

  • a file or a set of files to be dropped on the ServiceNav Box
  • a command line and arguments
  • any performance data
  • a return code

The order describes the following elements of the plugin :

  • a command line and arguments
  • any performance data

The service model is created from a command, and other metadata: description, dashboard category, etc.

Method of operation

  • Plugin creation and upload to the ServiceNav Box

Install the dependencies on the targeted ServiceNav Box(es).
Install on the targeted ServiceNav Box(es) the plugins in the directory /usr/local/nagios/libexec/client
Test manually under nagios user the correct execution after the installation.

  • Creating the order in ServiceNav

This operation must be carried out with an account having a root role.

In ServiceNav, navigate to the menu Configuration > Commands > Analysis.

A purchase order can be created by selecting an existing purchase order from the list and then clicking on the button Duplicate.

To create a new order, click on Add.

In the "Order" tab

Field Comment Syntax Example
Name The name of the command - must be unique Alphanumeric characters client_check_snmp_process_cpu
Line Command line executed on the ServiceNav Box. Standard Nagios macros can be used. $USER1$ = /usr/local/nagios/libexec.
Arguments are represented as $ARGi$, and usually surrounded by the quote character ().
$USER1$/client/check_snmp_process.pl -H $HOSTADDRESS$ -C '$ARG1$' -F -n '$ARG4$' -u '$ARG5$','$ARG6$' -p '$ARG3$' $ARG2$

Repeat for each argument ("Add Argument" button)

Field Comment Syntax Example
Argument - Wording The name of the argument, which will be visible when configuring the unit service. Alphanumeric characters SNMP Community
Argument - Type Allows to check the syntax when configuring the unit service 2a861946bafc3c44eb92bdefeffb6c92

4fc83a23cc4ee09d3243b1e0c601de07

Community
Argument - Mandatory Yes: the argument is mandatory to configure the unit service Yes / No Yes
Argument - Background The association with a supervision account, which allows you to benefit from the inheritance functionality of the supervision configuration. The context depends on the type. See Annex 1 SNMP
Argument - Description Will be displayed during the configuration of the unit service to guide the user.
Argument - Example Will be displayed during the configuration of the unit service to guide the user.

In the " Metrics " tab »

(Do not complete the Category list in the "General Information" block)

Metrics (performance data) - repeat for each metric
Name Name of the metric. If the metric name or part of the metric name is dynamic, indicate this. Alphanumeric character cpu_usage
Category This category is used for the representation of the category in performance analysis reports.

The metrics of each category with the same unit are grouped together in the same graph.

Otherwise they are presented in separate graphs.

21ad2cd9a46b9e758aada2d27c17f7ed Resource rate used
  • Create the unit service model linked to the order

Follow the documentation available at this address /servicenav/en/documentation/create-a-service-model-unit

Technical elements

Plugin file format

In order to meet ServiceNav's requirements on the plugin file format, files should be produced in the following format :

  • Unix format (end of line character is 'LF')
  • Encoding "UTF-8 without BOM".
  • Owner:nagios
  • Fee: 750 (rwxr-x-)

Return codes - standardization

The interruption of a plugin must imperatively lead to a return code which is an integer value between 0 and 3.

The value returned depends on the execution state of the plugin :

0 (OK) The plugin was able to check the service and it works correctly according to the internal logic of the plugin.
1 (WARNING) The plugin has been able to check the service but either it does not seem to work properly or a warning threshold has been crossed.
2 (CRITICAL) The plugin detected that the service was not working or that a "critical" threshold was crossed.
3 (UNKNOWN) Either incorrect arguments were provided to the plugin, or the plugin was unable to check the status of the given hosts/services.

Output Text

Plugins are designed to feed information back to the ServiceNav web interface: therefore, all outputs must be formatted to be compatible with the supervision system, i.e. in HTML. The limit of output text displayed in ServiceNav is 65535 bytes for both service and device controls.
Beyond this limit the text is truncated.

Performance data

Some plugins need to be able to pull up performance data that Nagios can use.
These data must be aggregated in pairs (=) separated by spaces.
If a unit is not required, it may be omitted.
Thresholds can also be mentioned in the performance data, and separated by semicolons(; ) (=;;)
The performance data is produced as a string of characters concatenated to the output text of the plugin, with the "pipe" character ( | ) as a separator.

The character limit for performance data processed in ServiceNav is 65535 bytes for equipment and service checks.

Beyond this limit performance data will not be processed.

Appendix 1

Argument - Type Argument - Background
Port 28bcbdba5113d06f82cabfd1bb773e34
Login dcfbfeb9b46924fa06a01cc2d0527f9f
Password f3a91fcbcfccf84c203ab9677f5b976b
Domain 2a235b74ce8df92ee1e2074e19226d84
Community (SNMP) eeb25dd278f1ebda42bebd8fbf94de19
Authentication protocol
Encryption password
Encryption protocol
78a68f09ef533f9153410f747d20d890
Equipment 3b2d7751f69e00dde0601587ceb10292

This may also be of interest to you

Adapting templates: creating a unitary service model

How Nagios Thresholds Work

Conducting a census

en_USEnglish
fr_FRFrench en_USEnglish

Welcome to ServiceNav!

Need help? More information about our products? Write to us!
You have taken note of our privacy policy.

[COVID - 19 ] - TELEWORKING, TARGET AVAILABILITY 100% !

While the epidemic lasts, ensure the availability and performance of your IT services for teleworking, with ServiceNav!

Following the government's call to mobilize to help businesses overcome the current health and economic context, we help you, free of charge, to ensure the complete monitoring of your teleworking environments: VPN, VDI, Teams, Skype Enterprise, Citrix... Objectives: collection, availability and usage indicators, dashboards to support your communication.
We use cookies to ensure that you have the best possible experience on our site, and if you continue to use this site, we will assume that you are satisfied with it.

Reserve your place

You have taken note of our privacy policy.