README.md
1# MySQL plugin
2This plugin provides a native solution for monitoring MySQL servers (relational database management system) by Zabbix.
3The plugin can monitor several remote or local MySQL instances simultaneously via Zabbix agent 2. Both TCP and
4Unix-socket connections are supported. Native connection encryption is also supported. The plugin keeps connections
5in the open state to reduce network congestion, latency, CPU, and memory usage. It can be used in conjunction with the official
6[Mysql template.](https://git.zabbix.com/projects/ZBX/repos/zabbix/browse/templates/db/mysql_agent2)
7You can extend it or create your template for your specific needs.
8
9## Requirements
10* Zabbix Agent 2
11* Go >= 1.13 (required only to build from source)
12
13## Supported versions
14* MySQL, version 5.7+
15* Percona, version 8.0+
16* MariaDB, version 10.4+
17
18## Installation
19The plugin is supplied as part of the Zabbix Agent 2 and does not require any special installation steps. Once
20Zabbix Agent 2 is installed, the plugin is ready to work. Now you need to make sure that a MySQL instance is
21available for connection and configure monitoring.
22
23## Configuration
24Open the Zabbix Agent configuration file (zabbix_agent2.conf) and set the required parameters.
25
26**Plugins.Mysql.CallTimeout** — The maximum time in seconds for waiting when a request has to be done.
27*Default value:* equals the global Timeout configuration parameter.
28*Limits:* 1-30
29
30**Plugins.Mysql.Timeout** — The maximum time in seconds for waiting when a connection has to be established.
31*Default value:* equals the global Timeout configuration parameter.
32*Limits:* 1-30
33
34**Plugins.Mysql.KeepAlive** — Sets a time for waiting before unused connections will be closed.
35*Default value:* 300 sec.
36*Limits:* 60-900
37
38**Plugins.Mysql.Sessions.<session_name>.TLSConnect** — Encryption type for MySQL connection. "*" should be replaced with a session name.
39*Default value:*
40*Accepted values:* required, verify_ca, verify_full
41
42**Plugins.Mysql.Sessions.<session_name>.TLSCAFile** — Full pathname of a file containing the top-level CA(s) certificates for mysql
43*Default value:*
44
45**Plugins.Mysql.Sessions.<session_name>.TLSCertFile** — Full pathname of a file containing the mysql certificate or certificate chain.
46*Default value:*
47
48**Plugins.Mysql.Sessions.*.TLSKeyFile** — Full pathname of a file containing the mysql private key.
49*Default value:*
50
51### Configuring connection
52A connection can be configured using either keys' parameters or named sessions.
53
54*Notes*:
55* It is not possible to mix configuration using named sessions and keys' parameters simultaneously.
56* You can leave any connection parameter empty, a default hard-coded value will be used in the such case.
57* TLS information can be passed only with sessions.
58* Embedded URI credentials (userinfo) are forbidden and will be ignored. So, you can't pass the credentials by this:
59
60 mysql.ping[tcp://user:password@127.0.0.1] — WRONG
61
62 The correct way is:
63
64 mysql.ping[tcp://127.0.0.1,user,password]
65
66* The only supported network schemas for a URI are "tcp" and "unix".
67Examples of valid URIs:
68 - tcp://127.0.0.1:3306
69 - tcp://localhost
70 - localhost
71 - unix:/var/run/mysql.sock
72 - /var/run/mysql.sock
73
74#### Using keys' parameters
75The common parameters for all keys are: [ConnString][,User][,Password]
76Where ConnString can be either a URI or a session name.
77ConnString will be treated as a URI if no session with the given name is found.
78If you use ConnString as a session name, just skip the rest of the connection parameters.
79
80#### Using named sessions
81Named sessions allow you to define specific parameters for each Mysql instance. Currently, these are the supported
82parameters: Uri, User, Password, TLSConnect, TLSCAFile, TLSCertFile and TLSKeyFile. It's a bit more secure way to
83store credentials compared to item keys or macros.
84
85E.g: suppose you have two Mysql instances: "Prod" and "Test".
86You should add the following options to the agent configuration file:
87
88 Plugins.Mysql.Sessions.Prod.Uri=tcp://192.168.1.1:3306
89 Plugins.Mysql.Sessions.Prod.User=<UserForProd>
90 Plugins.Mysql.Sessions.Prod.Password=<PasswordForProd>
91 Plugins.Mysql.Sessions.Prod.TLSConnect=verify_full
92 Plugins.Mysql.Sessions.Prod.TLSCAFile=/path/to/ca_file
93 Plugins.Mysql.Sessions.Prod.TLSCertFile=/path/to/cert_file
94 Plugins.Mysql.Sessions.Prod.TLSKeyFile=/path/to/key_file
95
96 Plugins.Mysql.Sessions.Test.Uri=tcp://192.168.0.1:3306
97 Plugins.Mysql.Sessions.Test.User=<UserForTest>
98 Plugins.Mysql.Sessions.Test.Password=<PasswordForTest>
99 Plugins.Mysql.Sessions.Test.TLSConnect=verify_ca
100 Plugins.Mysql.Sessions.Test.TLSCAFile=/path/to/test/ca_file
101 Plugins.Mysql.Sessions.Test.TLSCertFile=/path/to/test/cert_file
102 Plugins.Mysql.Sessions.Test.TLSKeyFile=/path/to/test/key_file
103
104Then you will be able to use these names as the 1st parameter (ConnString) in keys instead of URIs, e.g:
105
106 mysql.ping[Prod]
107 mysql.ping[Test]
108
109*Note*: sessions names are case-sensitive.
110
111## Supported keys
112**mysql.db.discovery[\<commonParams\>]** — Returns list of databases in LLD format.
113
114**mysql.db.size[\<commonParams\>,database]** — Returns size of given database in bytes.
115*Parameters:*
116database (required) — database name.
117
118**mysql.ping[\<commonParams\>]** — Tests if connection is alive or not.
119*Returns:*
120- "1" if the connection is alive.
121- "0" if the connection is broken (returned if there was any error during the test, including AUTH and configuration issues).
122
123**mysql.replication.discovery[\<commonParams\>]** — Returns replication information in LLD format.
124
125**mysql.replication.get_slave_status[\<commonParams\>]** — Returns replication status.
126
127**mysql.get_status_variables[\<commonParams\>]** — Returns values of global status variables.
128
129**mysql.version[\<commonParams\>]** — Returns MySQL version.
130
131## Troubleshooting
132The plugin uses Zabbix agent's logs. You can increase debugging level of Zabbix Agent if you need more details about
133what is happening.
134