3 Secure connection to the database

Overview

It is possible to configure secure TLS connections to MySQL and PostgreSQL databases from:

  • Zabbix frontend
  • Zabbix server or proxy

See also: Known issues

Frontend configuration

Since Zabbix 5.0.5 TLS encryption parameter names have changed slightly: for better clarity the "Database" prefix has been added. In versions 5.0.0-5.0.4 parameters are named TLS encryption, TLS certificate file, etc.

A secure connection to the database can be configured during frontend installation:

  • Mark the Database TLS encryption checkbox in the Configure DB connection step to enable transport encryption.
  • Mark the Verify database certificate checkbox that appears when TLS encryption field is checked to enable encryption with certificates.

Since Zabbix 5.0.5:
For MySQL, the Database TLS encryption checkbox is disabled, if Database host is set to localhost, because connection that uses a socket file (on Unix) or shared memory (on Windows) cannot be encrypted.
For PostgreSQL, the TLS encryption checkbox is disabled, if the value of the Database host field begins with a slash or the field is empty.

The following parameters are available in the TLS encryption in certificates mode (since Zabbix 5.0.5 the parameters appear only if both checkboxes are marked):

Parameter Description
Database TLS CA file Specify the full path to a valid TLS certificate authority (CA) file.
Database TLS key file Specify the full path to a valid TLS key file.
Database TLS certificate file Specify the full path to a valid TLS certificate file.
Database host verification Mark this checkbox to activate host verification.
Disabled for MYSQL, because PHP MySQL library does not allow to skip the peer certificate validation step.
Database TLS cipher list Specify a custom list of valid ciphers. The format of the cipher list must conform to the OpenSSL standard.
Available for MySQL only.

TLS parameters must point to valid files. If they point to non-existent or invalid files, it will lead to the authorization error.
If certificate files are writable, the frontend generates a warning in the System information report that "TLS certificate files must be read-only." (displayed only if the PHP user is the owner of the certificate).

Certificates protected by passwords are not supported.

Use cases
Configuration Result
None (leave Database TLS encryption unmarked) Connection to the database without encryption.
1. Mark Database TLS encryption only Secure TLS connection to the database.
1. Mark Database TLS encryption
2. Specify TLS certificate authority file
Secure TLS connection to the database;
Database server certificate is verified and verified that it is signed by a trusted center.
1. Mark Database TLS encryption
2. Specify TLS certificate authority file
3. Mark With host verification
4. Specify TLS cipher list (optional)
Secure TLS connection to the database;
Database server certificate is checked by comparing the host name specified in the certificate with the name of the host to which it is connected;
It is verified that the certificate is signed by a trusted authority.
1. Mark Database TLS encryption
2. Specify TLS key file
3. Specify TLS certificate file
4. Specify TLS certificate authority file
5. Mark Database host verification (prior to 5.0.5: With host verification)
6. Specify TLS cipher list (optional)
Secure TLS connections to the database are established with maximum security. The requirement for the client part to present their certificates is configured on the server side.

See also: Configuration examples for MySQL, Configuration examples for PostgreSQL.

Zabbix server/proxy configuration

Secure connections to the database can be configured with the respective parameters in the Zabbix server and/or proxy configuration file.

Configuration Result
None Connection to the database without encryption.
1. Set DBTLSConnect=required Server/proxy make a TLS connection to the database. An unencrypted connection is not allowed.
1. Set DBTLSConnect=verify_ca
2. Set DBTLSCAFile - specify the TLS certificate authority file
Server/proxy make a TLS connection to the database after verifying the database certificate.
1. Set DBTLSConnect=verify_full
2. Set DBTLSCAFile - specify TLS certificate authority file
Server/proxy make a TLS connection to the database after verifying the database certificate and the database host identity.
1. Set DBTLSCAFile - specify TLS certificate authority file
2. Set DBTLSCertFile - specify the client public key certificate file
3. Set DBTLSKeyFile - specify the client private key file
Server/proxy provide a client certificate while connecting to the database.
1. Set DBTLSCipher - the list of encryption ciphers that the client permits for connections using TLS protocols up to TLS 1.2

or DBTLSCipher13 - the list of encryption ciphers that the client permits for connections using TLS 1.3 protocol
(MySQL) TLS connection is made using a cipher from the provided list.
(PostgreSQL) Setting this option will be considered as an error.