Table of Contents
6 MongoDB plugin
Overview
The configuration file of Zabbix agent 2 is used to configure plugins. These Zabbix agent 2 configuration parameters are supported for operating the MongoDB plugin.
It is recommended to specify them in their own configuration file (e.g., mongo.conf) and then use the Include directive for adding this file to the Zabbix agent 2 configuration.
The MongoDB plugin is a loadable plugin and is available and fully described in the MongoDB plugin repository.
Note that:
- The default values reflect process defaults, not the values in the shipped configuration files.
- Values support environment variables.
- Zabbix supports configuration files only in UTF-8 encoding without BOM.
- Comments starting with "#" are only supported at the beginning of the line.
Options
| Parameter | Description |
|---|---|
| -V --version | Print the plugin version and license information. |
| -h --help | Print help information (shorthand). |
| -t, --test <item key> | Launch plugin for testing (plugin config ignored). |
Parameters
When connecting to MongoDB, the plugin checks its configuration in a specific order, which determines which value to use. The order, from highest to lowest priority, is as follows:
- Parameters specified in the connection URI (e.g., query parameters defined after
?inPlugins.MongoDB.Sessions.<session_name>.Urihave the highest priority). - Parameters in the Zabbix agent 2 item key (e.g., mongodb.collection.stats).
- Parameters defined in a named session (e.g.,
Plugins.MongoDB.Sessions.<SessionName>.User,Plugins.MongoDB.Sessions.<SessionName>.Password). - Default values (e.g.,
Plugins.MongoDB.Default.User,Plugins.MongoDB.Default.Password).
For example:
- If you specify the database for authenticating a connection to the MongoDB server in the
*.<SessionName>.Uriparameter (e.g.,Plugins.MongoDB.Sessions.<session_name>.Uri=mongodb://user:[email protected]:27017/?authSource=admin), then the plugin will consider the*.<SessionName>.AuthSourceparameter to be set toadmin, even if the*.<SessionName>.AuthSourceparameter is set to a different value. - If you specify the URI in the
*.<SessionName>.Uriparameter (e.g.,Plugins.MongoDB.Sessions.<session_name>.Uri=mongodb://127.0.0.1:27017), but provide the username and the password in the Zabbix agent 2 item key, the plugin will use the username and password from the item key, even ifPlugins.MongoDB.Sessions.<SessionName>.UserandPlugins.MongoDB.Sessions.<SessionName>.Passwordare configured.
If the mongodb+srv:// scheme is used, the URI may retrieve parameters from a DNS TXT record. Parameters obtained from this TXT record override all other configurations, including URI parameters, Zabbix Agent 2 item key parameters, and session parameters.
Only one TXT record may exist for the hostname used in the connection string.
| Parameter | Mandatory | Range | Default | Description |
|---|---|---|---|---|
| Plugins.MongoDB.System.Path | no | Path to the MongoDB plugin executable. Example usage: Plugins.MongoDB.System.Path=/usr/libexec/zabbix/zabbix-agent2-plugin-mongodb |
||
| Plugins.MongoDB.Timeout | no | 1-30 | global timeout | Request execution timeout (the duration, in seconds, to wait for a request to complete before shutting it down). |
| Plugins.MongoDB.KeepAlive | no | 60-900 | 300 | The maximum time of waiting (in seconds) before unused plugin connections are closed. |
| Plugins.MongoDB.Sessions.<SessionName>.Uri | no | tcp://127.0.0.1:27017 |
Connection string of a named session. <SessionName> - define name of a session for using in item keys. Must match the URI format. Supported schemes: mongodb:// and mongodb+srv://; the tcp:// scheme is deprecated and kept for backward compatibility with existing configurations.A port can be omitted (default=27017). Examples: mongodb://127.0.0.1:27017, mongodb+srv://example.com, localhost. |
|
| Plugins.MongoDB.Sessions.<SessionName>.User | no | Named session username. <SessionName> - define name of a session for using in item keys. |
||
| Plugins.MongoDB.Sessions.<SessionName>.Password | no | Named session password. <SessionName> - define name of a session for using in item keys. |
||
| Plugins.MongoDB.Sessions.<SessionName>.Direct | no | false |
Connection method used to determine whether automatic discovery of MongoDB replica set nodes should be enabled or disabled. <SessionName> - define name of a session for using in item keys. Supported values: true - the plugin will connect only to the specified server, ignoring other members of the replica set;false - the plugin will automatically discover all nodes in the replica set.If the tcp:// (deprecated) scheme is used, the parameter is set to true by default. |
|
| Plugins.MongoDB.Sessions.<SessionName>.AuthMechanism | no | Authentication mechanism for connecting to MongoDB server. <SessionName> - define name of a session for using in item keys. Supported values: SCRAM-SHA-1, SCRAM-SHA-256, and MONGODB-X509. |
||
| Plugins.MongoDB.Sessions.<SessionName>.AuthSource | no | admin |
Database for authenticating connection to MongoDB server. <SessionName> - define name of a session for using in item keys. If the MONGODB-X509 authentication mechanism is used, this parameter is automatically set to $external; modifying it to any other value will cause an error when launching. |
|
| Plugins.MongoDB.Sessions.<SessionName>.ReplicaSet | no | Replica set name, used for automatic discovery of MongoDB replica set nodes. <SessionName> - define name of a session for using in item keys. If this parameter is used with the mongodb+srv:// scheme, it will behave as if multiple URLs have been provided; a DNS server may have a TXT record that can override this (or any other) parameter.Unavailable if the Plugins.MongoDB.Sessions.<SessionName>.Direct parameter is set to true, the agent will fail to start. |
||
| Plugins.MongoDB.Sessions.<SessionName>.ReadPreference | no | Order for connecting to MongoDB replica set nodes or fallback. <SessionName> - define name of a session for using in item keys. Supported values: PrimaryMode, PrimaryPreferredMode, SecondaryMode, SecondaryPreferredMode, and NearestMode.Unavailable if the Plugins.MongoDB.Sessions.<SessionName>.Direct parameter is set to true, the agent will fail to start. |
||
| Plugins.MongoDB.Sessions.<SessionName>.TLSConnect | no | Encryption type for communications between Zabbix agent 2 and monitored databases. <SessionName> - define name of a session for using in item keys. Supported values: required - require TLS connection;verify\_ca - verify certificates;verify\_full - verify certificates and IP address.Supported since plugin version 1.2.1. |
||
| Plugins.MongoDB.Sessions.<SessionName>.TLSCAFile | yes, if Plugins.MongoDB.Sessions.<SessionName>.TLSConnect is set to one of: verify_ca, verify_full | Full pathname of a file containing the top-level CA(s) certificates for peer certificate verification, used for encrypted communications between Zabbix agent 2 and monitored databases. <SessionName> - define name of a session for using in item keys. |
||
| Plugins.MongoDB.Sessions.<SessionName>.TLSCertFile | yes, if Plugins.MongoDB.Sessions.<SessionName>.TLSKeyFile is specified | Full pathname of a file containing the agent certificate or certificate chain, used for encrypted communications between Zabbix agent 2 and monitored databases. <SessionName> - define name of a session for using in item keys. |
||
| Plugins.MongoDB.Sessions.<SessionName>.TLSKeyFile | yes, if Plugins.MongoDB.Sessions.<SessionName>.TLSCertFile is specified | Full pathname of a file containing the database private key used for encrypted communications between Zabbix agent 2 and monitored databases. <SessionName> - define name of a session for using in item keys. |
||
| Plugins.MongoDB.Default.Uri | no | tcp://127.0.0.1:27017 |
Default URI for connecting to MongoDB. Must match the URI format. Supported schemes: mongodb:// and mongodb+srv://.Deprecated scheme: tcp:// (used as the default for backward compatibility with existing configurations).A port can be omitted (default=27017). Examples: mongodb://127.0.0.1:27017, mongodb+srv://example.com, localhost. |
|
| Plugins.MongoDB.Default.User | no | Default username for connecting to MongoDB. | ||
| Plugins.MongoDB.Default.Password | no | Default password for connecting to MongoDB. | ||
| Plugins.MongoDB.Default.Direct | no | false |
Default connection method used to determine whether automatic discovery of MongoDB replica set nodes should be enabled or disabled. Supported values: true - the plugin will connect only to the specified server, ignoring other members of the replica set;false - the plugin will automatically discover all nodes in the replica set.If the tcp:// (deprecated) scheme is used, the parameter is set to true by default. |
|
| Plugins.MongoDB.Default.AuthMechanism | no | Default authentication mechanism for connecting to MongoDB server. Supported values: SCRAM-SHA-1, SCRAM-SHA-256, and MONGODB-X509.If no value is specified either here, in an item key, in a named session, or in the URI, a SCRAM-based mechanism is used (if a username is provided; otherwise, no authentication will be used). |
||
| Plugins.MongoDB.Default.AuthSource | no | admin |
Default database for authenticating connection to MongoDB server. If the MONGODB-X509 authentication mechanism is used, this parameter is automatically set to $external; modifying it to any other value will cause an error when launching. |
|
| Plugins.MongoDB.Default.ReplicaSet | no | Default replica set name; used for automatic discovery of MongoDB replica set nodes. If this parameter is used with the mongodb+srv:// scheme, it will behave as if multiple URLs have been provided; a DNS server may have a TXT record that can override this (or any other) parameter.Unavailable if the Plugins.MongoDB.Default.Direct parameter is set to true, the agent will fail to start. |
||
| Plugins.MongoDB.Default.ReadPreference | no | Default order for connecting to MongoDB replica set nodes or fallback. Supported values: PrimaryMode, PrimaryPreferredMode, SecondaryMode, SecondaryPreferredMode, and NearestMode.Unavailable if the Plugins.MongoDB.Default.Direct parameter is set to true, the agent will fail to start. |
||
| Plugins.MongoDB.Default.TLSConnect | no | Default encryption type for communications between Zabbix agent 2 and monitored databases. Supported values: required - requires TLS connection.verify\_ca - verifies certificates.verify\_full - verifies certificates and IP address.If no value is specified either here, in an item key, in a named session, or in the URI, a TLS connection will not be established. |
||
| Plugins.MongoDB.Default.TLSCAFile | no | Default pathname of a file containing the top-level CA(s) certificates for peer certificate verification. Used for encrypted communications between Zabbix agent 2 and monitored databases. | ||
| Plugins.MongoDB.Default.TLSCertFile | no | Default pathname of a file containing the MongoDB client certificate or certificate chain. Used for encrypted communications between Zabbix agent 2 and monitored databases. | ||
| Plugins.MongoDB.Default.TLSKeyFile | no | Default pathname of a file containing the MongoDB client private key used for encrypted communications between Zabbix agent 2 and monitored databases. |
See also:
- Description of general Zabbix agent 2 configuration parameters: Zabbix agent 2 (UNIX) / Zabbix agent 2 (Windows)
- Instructions for configuring plugins