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.
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.
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.
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
|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)
|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||
|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.
|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
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".
- 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.|
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.
Some plugins need to be able to pull up performance data that Nagios can use.
These data must be aggregated in pairs (
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.
|Argument - Type||Argument - Background|