MySQL Bugs: #44198: Setting Up Replication Using SSL Docs Incorrect

Bug #44198	Setting Up Replication Using SSL Docs Incorrect
Submitted:	9 Apr 2009 23:51	Modified:	8 Apr 2010 12:15
Reporter:	Donna Harmon	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:	5.1	OS:	MacOS
Assigned to:	Jon Stephens	CPU Architecture:	Any

Description:
http://dev.mysql.com/doc/refman/5.1/en/replication-solutions-ssl.html

Adding certificate information to the [client] section of the slave's my.cnf file does not work. Also, full path name in CHANGE MASTER TO statement was required for ssl options.

Also, in setting up SSL on master, the full path was NOT required for ssl options in the master's my.cnf file as is currently stated in the "Note" section. In testing this the certificates were located in a directory under the basedir so only specifying that directory was necessary.

How to repeat:
Follow instructions for adding ssl options to slave's my.cnf file in "Setting Up Replication Using SSL"

Suggested fix:
Change documentation to the following:

To use SSL for encrypting the transfer of the binary log required during replication you must first set up the master to support SSL network connections. If the master does not support SSL connections (because it has not been compiled or configured for SSL), then replication through an SSL connection will not be possible.

For more information on setting up a server and client for SSL connectivity, see Section 5.5.7.2, “Using SSL Connections”.

To enable SSL on the master you will need to create or obtain suitable certificates and then add the following configuration options to the master's configuration within the mysqld section:

ssl-ca=cert_dir/ca-cert.pem
ssl-cert=cert_dir/server-cert.pem
ssl-key=cert_dir/server-key.pem

Note

You may need to use the full path to specify the location of your certificate files.

The options are as follows:

* ssl-ca identifies the Certificate Authority (CA) certificate.
* ssl-cert identifies the server public key. This can be sent to the client and authenticated against the CA certificate that it has.
* ssl-key identifies the server private key.

On the slave, you must specify the master's SSL information using the CHANGE MASTER TO statement as follows:

Restart the slave server, using the --skip-slave option to prevent the slave from connecting to the master. Use CHANGE MASTER TO to specify the master's configuration, using the MASTER_SSL option to enable SSL connectivity:

CHANGE MASTER TO \
MASTER_HOST='master_hostname', \
MASTER_USER='replicate', \
MASTER_PASSWORD='password', \
MASTER_SSL=1, \
MASTER_SSL_CA = 'full_path_to_file_on_master/ca_file_name', \
MASTER_SSL_CAPATH = 'ca_directory_name', \
MASTER_SSL_CERT = 'full_path_to_file_on_master/cert_file_name', \
MASTER_SSL_KEY = 'full_path_to_file_on_master/key_file_name';

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

mysql> START SLAVE;

You can use the SHOW SLAVE STATUS to confirm that SSL connection has been completed.

For more information on the CHANGE MASTER TO syntax, see Section 12.6.2.1, “CHANGE MASTER TO Syntax”.

If you want to enforce SSL connections to be used during replication, then create a user with the REPLICATION SLAVE privilege and use the REQUIRE_SSL option for that user. For example:

mysql> GRANT REPLICATION SLAVE ON *.*
-> TO 'repl'@'%.mydomain.com' IDENTIFIED BY 'slavepass' REQUIRE SSL;

Set status to Verified, assigned to myself, since this concerns Replication docs.

There are other apparently problems with our SSL documentation; see BUG#45280.

Ignore previous comment; the referenced bug is not directly related.

Donna,

We don't just document that something was observed to work in such-and-such a fashion. We document the following:

A. Intended behaviour.
B. Cases where the actual behaviour was observed to vary from the intended behaviour, and the behaviour has been fixed to match what's intended (bugfixes).
C. Cases where the actual behaviour varies from the intended behaviour, and these variances are critical for users to know about and/or it will take some time to fix them (known issues).

Here's the issues you've raised, as I understand them:

1. SSL options for CHANGE MASTER TO that refer to files require absolute paths, although we don't say this in the documentation.

a. Is this by design?
b. Has this always been the case?
c. Is it possible that the intended behaviour changed at some point?  If so, in what version(s) of the server did this happen?

2. The slave ignores certificate info written in the [client] section of my.cnf, although we claim otherwise in the docs.

a. Is this by design?
b. Has this always been the case?
c. Is it possible that the intended behaviour changed at some point? If so, in what version(s) of the server did this happen?

3. The master does not require full paths for options pointing to files in the [ssl] section of its my.cnf.
a. What the Note says is, "You should use full path to specify the location of your certificate files." We say "should" (= recommendation), not "must" (= requirement).

Thanks!

Hi,

I need a developer and/or the submitter to answer the questions I raised above.

Once this is done, please change back to Docs/Verified and set the Lead/Asignee back to Stefan/me.

Thanks!

Hi Jon,

My answers to your questions above:

1.
a. As I tested (5.1 5.5), SSL options for CHANGE MASTER does not require to be absolute paths, they can be relative paths to datadir.
b. Always allow both absolute and relative paths
c. n/a

2. 
a. Yes, I think this is by design because slave is also a server, not client, so it will not honor options specified in [client]
b. Yes
c. n/a

3.
a. I'd suggest to use 'recommended' to make it clear.

Changed category/assignee/lead back to original values.

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.