7 Configuration parameters of plugins

See configuration parameters for Zabbix agent 2 plugins:

• Ceph plugin
• Docker plugin
• Ember+ plugin
• Memcached plugin
• Modbus plugin
• MongoDB plugin
• MQTT plugin
• MSSQL plugin
• MySQL plugin
• NVIDIA GPU plugin
• Oracle plugin
• PostgreSQL plugin
• Redis plugin
• S.M.A.R.T. plugin

Plugin configuration principles

This page describes plugin configuration principles and best practices.

All plugins are configured using Plugins.* parameter, which can either be part of the Zabbix agent 2 configuration file or a plugin's own configuration file. If a plugin uses a separate configuration file, path to this file should be specified in the Include parameter of Zabbix agent 2 configuration file.

A typical plugin parameter has the following structure:

Plugins.<PluginName>.<Parameter>=<Value>

Additionally, there are two specific groups of parameters:

• Plugins.<PluginName>.Default.<Parameter>=<Value> used for defining default parameter values.

• Plugins.<PluginName>.<SessionName>.<Parameter>=<Value> used for defining separate sets of parameters for different monitoring targets via named sessions.

All parameter names should adhere to the following requirements:

• it is recommended to capitalize the names of your plugins
• the parameter should be capitalized
• special characters are not allowed
• nesting isn't limited by a maximum level
• the number of parameters is not limited

For example, to perform active checks that do not have Scheduling update interval immediately after the agent restart only for the Uptime plugin, set Plugins.Uptime.System.ForceActiveChecksOnStart=1 in the configuration file. Similarly, to set custom limit for concurrent checks for the CPU plugin, set the Plugins.CPU.System.Capacity=N in the configuration file.

Default values

You can set default values for the connection-related parameters (URI, username, password, etc.) in the configuration file in the format:

Plugins.<PluginName>.Default.<Parameter>=<Value>

For example, Plugins.Mysql.Default.Username=zabbix, Plugins.MongoDB.Default.Uri=tcp://127.0.0.1:27017, etc.

If a value for such parameter is not provided in an item key or in the named session parameters, the plugin will use the default value. If a default parameter is also undefined, hardcoded defaults will be used.

Named sessions

Named sessions represent an additional level of plugin parameters and can be used to specify separate sets of authentication parameters for each of the instances being monitored. Each named session parameter should have the following structure:

Plugins.<PluginName>.Sessions.<SessionName>.<Parameter>=<Value>

A session name can be used as a connString item key parameter instead of specifying a URI, username, and/or password separately.

In item keys, the first parameter can be either a connString or a URI. If the first key parameter doesn't match any session name, it will be treated as a URI. Note that passing embedded URI credentials in the item key is not supported, use named session parameters instead.

The list of available named session parameters depends on the plugin.

It is possible to override session parameters by specifying new values in the item key parameters (see example).

If a parameter is not defined for the named session, Zabbix agent 2 will use the value defined in the default plugin parameter.

Parameter priority

Zabbix agent 2 plugins search for connection-related parameter values in the following order:

1. The first item key parameter is compared to session names. If no match is found, it is treated as an actual value; in this case, step 3 will be skipped. If a match is found, the parameter value (usually, a URI) must be defined in the named session.
2. Other parameters will be taken from the item key if defined.
3. If an item key parameter (for example, password) is empty, plugin will look for the corresponding named session parameter.
4. If the session parameter is also not specified, the value defined in the corresponding default parameter will be used.
5. If all else fails, the plugin will use the hardcoded default value.

Example 1

Monitoring of two instances “MySQL1” and “MySQL2”.

Configuration parameters:

Plugins.Mysql.Sessions.MySQL1.Uri=tcp://127.0.0.1:3306
Plugins.Mysql.Sessions.MySQL1.User=mysql1_user
Plugins.Mysql.Sessions.MySQL1.Password=unique_password
Plugins.Mysql.Sessions.MySQL2.Uri=tcp://192.0.2.0:3306
Plugins.Mysql.Sessions.MySQL2.User=mysql2_user
Plugins.Mysql.Sessions.MySQL2.Password=different_password

As a result of this configuration, each session name may be used as a connString in an item key, e.g., mysql.ping[MySQL1] or mysql.ping[MySQL2].

Example 2

Providing some of the parameters in the item key.

Configuration parameters:

Plugins.PostgreSQL.Sessions.Session1.Uri=tcp://192.0.2.234:5432
Plugins.PostgreSQL.Sessions.Session1.User=old_username
Plugins.PostgreSQL.Sessions.Session1.Password=session_password

Item key: pgsql.ping[session1,new_username,,postgres]

As a result of this configuration, the agent will connect to PostgreSQL using the following parameters:

• URI from session parameter: 192.0.2.234:5432
• Username from the item key: new_username
• Password from session parameter (since it is omitted in the item key): session_password
• Database name from the item key: postgres

Example 3

Collecting a metric using default configuration parameters.

Configuration parameters:

Plugins.PostgreSQL.Default.Uri=tcp://192.0.2.234:5432
Plugins.PostgreSQL.Default.User=zabbix
Plugins.PostgreSQL.Default.Password=password

Item key: pgsql.ping[,,,postgres]

As a result of this configuration, the agent will connect to PostgreSQL using the parameters:

• Default URI: 192.0.2.234:5432
• Default username: zabbix
• Default password: password
• Database name from the item key: postgres

Connections

Some plugins support gathering metrics from multiple instances simultaneously. Both local and remote instances can be monitored. TCP and Unix-socket connections are supported.

It is recommended to configure plugins to keep connections to instances in an open state. The benefits are reduced network congestion, latency, and CPU and memory usage due to the lower number of connections. The client library takes care of this.