Documentation Home
MySQL 8.0 Reference Manual
Related Documentation Download this Manual
PDF (US Ltr) - 46.1Mb
PDF (A4) - 46.1Mb
PDF (RPM) - 41.5Mb
HTML Download (TGZ) - 10.6Mb
HTML Download (Zip) - 10.6Mb
HTML Download (RPM) - 9.1Mb
Man Pages (TGZ) - 220.4Kb
Man Pages (Zip) - 325.8Kb
Info (Gzip) - 4.1Mb
Info (Zip) - 4.1Mb
Excerpts from this Manual

MySQL 8.0 Reference Manual  /  ...  /  Setting Up Replication to Use Encrypted Connections

17.3.9 Setting Up Replication to Use Encrypted Connections

To use an encrypted connection for the transfer of the binary log required during replication, both the master and the slave servers must support encrypted network connections. If either server does not support encrypted connections (because it has not been compiled or configured for them), replication through an encrypted connection is not possible.

Setting up encrypted connections for replication is similar to doing so for client/server connections. You must obtain (or create) a suitable security certificate that you can use on the master, and a similar certificate (from the same certificate authority) on each slave. You must also obtain suitable key files.

For more information on setting up a server and client for encrypted connections, see Section 6.3.1, “Configuring MySQL to Use Encrypted Connections”.

To enable encrypted connections on the master, you must create or obtain suitable certificate and key files, and then add the following configuration options to the master's configuration within the [mysqld] section of the master's my.cnf file, changing the file names as necessary:

[mysqld]
ssl-ca=cacert.pem
ssl-cert=server-cert.pem
ssl-key=server-key.pem

The paths to the files may be relative or absolute; we recommend that you always use complete paths for this purpose.

The options are as follows:

  • --ssl-ca: The path name of the Certificate Authority (CA) certificate file. (--ssl-capath is similar but specifies the path name of a directory of CA certificate files.)

  • --ssl-cert: The path name of the server public key certificate file. This certificate can be sent to the client and authenticated against the CA certificate that it has.

  • --ssl-key: The path name of the server private key file.

To enable encrypted connections on the slave, use the CHANGE MASTER TO statement. You can either name the slave certificate and SSL private key files required for the encrypted connection in the [client] section of the slave's my.cnf file, or you can explicitly specify that information using the CHANGE MASTER TO statement. For more information on the CHANGE MASTER TO statement, see Section 13.4.2.1, “CHANGE MASTER TO Syntax”.

  • To name the slave certificate and key files using an option file, add the following lines to the [client] section of the slave's my.cnf file, changing the file names as necessary:

    [client]
    ssl-ca=cacert.pem
    ssl-cert=client-cert.pem
    ssl-key=client-key.pem
  • Restart the slave server, using the --skip-slave-start option to prevent the slave from connecting to the master. Use CHANGE MASTER TO to specify the master configuration, and add the MASTER_SSL option to connect using encryption:

    mysql> CHANGE MASTER TO
        -> MASTER_HOST='master_hostname',
        -> MASTER_USER='repl',
        -> MASTER_PASSWORD='password',
        -> MASTER_SSL=1;

    Setting MASTER_SSL=1 for a replication connection and then setting no further MASTER_SSL_xxx options corresponds to setting --ssl-mode=REQUIRED for the client, as described in Command Options for Encrypted Connections. With MASTER_SSL=1, the connection attempt only succeeds if an encrypted connection can be established. A replication connection does not fall back to an unencrypted connection, so there is no setting corresponding to the --ssl-mode=PREFERRED setting for replication. If MASTER_SSL=0 is set, this corresponds to --ssl-mode=DISABLED.

  • To name the slave certificate and SSL private key files using the CHANGE MASTER TO statement, if you did not do this in the slave's my.cnf file, add the appropriate MASTER_SSL_xxx options:

        -> MASTER_SSL_CA = 'ca_file_name',
        -> MASTER_SSL_CAPATH = 'ca_directory_name',
        -> MASTER_SSL_CERT = 'cert_file_name',
        -> MASTER_SSL_KEY = 'key_file_name',

    These options correspond to the --ssl-xxx options with the same names, as described in Command Options for Encrypted Connections. For these options to take effect, MASTER_SSL=1 must also be set. For a replication connection, specifying a value for either of MASTER_SSL_CA or MASTER_SSL_CAPATH, or specifying these options in the slave's my.cnf file, corresponds to setting --ssl-mode=VERIFY_CA. The connection attempt only succeeds if a valid matching Certificate Authority (CA) certificate is found using the specified information.

  • To activate host name identity verification, add the MASTER_SSL_VERIFY_SERVER_CERT option:

        -> MASTER_SSL_VERIFY_SERVER_CERT=1,

    This option corresponds to the --ssl-verify-server-cert option, which was deprecated from MySQL 5.7 and removed in MySQL 8.0. For a replication connection, specifying MASTER_SSL_VERIFY_SERVER_CERT=1 corresponds to setting --ssl-mode=VERIFY_IDENTITY, as described in Command Options for Encrypted Connections. For this option to take effect, MASTER_SSL=1 must also be set. Host name identity verification does not work with self-signed certificates.

  • To activate certificate revocation list (CRL) checks, add the MASTER_SSL_CRL or MASTER_SSL_CRLPATH option:

        -> MASTER_SSL_CRL = 'crl_file_name',
        -> MASTER_SSL_CRLPATH = 'crl_directory_name',

    These options correspond to the --ssl-xxx options with the same names, as described in Command Options for Encrypted Connections. If they are not specified, no CRL checking takes place.

  • To specify lists of ciphers and encryption protocols permitted by the slave for the replication connection, add the MASTER_SSL_CIPHER and MASTER_TLS_VERSION options:

        -> MASTER_SSL_CIPHER = 'cipher_list',
        -> MASTER_TLS_VERSION = 'protocol_list',

    The MASTER_SSL_CIPHER option specifies the list of ciphers permitted by the slave for the replication connection, with one or more cipher names separated by colons. The MASTER_TLS_VERSION option specifies the encryption protocols permitted by the slave for the replication connection. The format is like that for the tls_version system variable, with one or more protocol names separated by commas. The protocols and ciphers that you can use in these lists depend on the SSL library used to compile MySQL. For information about the formats and permitted values, see Section 6.3.5, “Encrypted Connection Protocols and Ciphers”.

  • After the master information has been updated, start the slave replication process:

    mysql> START SLAVE;

    You can use the SHOW SLAVE STATUS statement to confirm that an encrypted connection was established successfully.

  • Requiring encrypted connections on the slave does not ensure that the master requires encrypted connections from slaves. If you want to ensure that the master only accepts replication slaves that connect using encrypted connections, create a replication user account on the master using the REQUIRE SSL option, then grant that user the REPLICATION SLAVE privilege. For example:

    mysql> CREATE USER 'repl'@'%.example.com' IDENTIFIED BY 'password'
        -> REQUIRE SSL;
    mysql> GRANT REPLICATION SLAVE ON *.*
        -> TO 'repl'@'%.example.com';

    If you have an existing replication user account on the master, you can add REQUIRE SSL to it with this statement:

    mysql> ALTER USER 'repl'@'%.example.com' REQUIRE SSL;