MySQL 5.7 Reference Manual Including MySQL NDB Cluster 7.5 and NDB Cluster 7.6
As of MySQL 5.7.21, the MySQL server supports an operational mode that enables migration of keys between underlying keyring keystores, permitting DBAs to switch a MySQL installation from one keyring plugin to another. A migration server (that is, a server started in key migration mode) does not accept client connections. Instead, it runs only long enough to migrate keys, then exits. A migration server reports errors to the console (the standard error output).
It is possible to perform offline or online key migration:
If you are sure that no running server on the local host is using the source or destination keystore, an offline migration is possible. In this case, the migration server can modify the keystores without possibility of a running server modifying keystore content during the migration.
If a running server on the local host is using the source or destination keystore, an online migration must be performed. In this case, the migration server connects to the running server and instructs it to pause keyring operations while key migration is in progress.
The result of a key migration operation is that the destination keystore contains the keys it had prior to the migration, plus the keys from the source keystore. The source keystore is the same before and after the migration because keys are copied, not moved. If a key to be copied already exists in the destination keystore, an error occurs and the destination keystore is restored to its premigration state.
The user who invokes the server in key-migration mode must not
be the root
operating system user, and must
have permission to read and write the keyring files.
To perform a key migration operation, determine which key migration options are needed. Migration options indicate which keyring plugins are involved, and whether to perform an offline or online migration:
To indicate the source and destination keyring plugins, specify these options:
--keyring-migration-source
:
The source keyring plugin that manages the keys to be
migrated.
--keyring-migration-destination
:
The destination keyring plugin to which the migrated
keys are to be copied.
These options tell the server to run in key migration mode. Both options are mandatory for all key migration operations. The source and destination plugins must differ, and the migration server must support both plugins.
For an offline migration, no additional key migration options are needed.
Do not perform offline migration involving a keystore that is in use by a running server.
For an online migration, some running server currently is using the source or destination keystore. Specify the key migration options that indicate how to connect to the running server. This is necessary so that the migration server can connect to the running server and tell it to pause keyring use during the migration operation.
Use of any of the following options signifies an online migration:
--keyring-migration-host
:
The host where the running server is located. This is
always the local host.
--keyring-migration-user
,
--keyring-migration-password
:
The user name and password for the account to use to
connect to the running server.
--keyring-migration-port
:
For TCP/IP connections, the port number to connect to on
the running server.
--keyring-migration-socket
:
For Unix socket file or Windows named pipe connections,
the socket file or named pipe to connect to on the
running server.
For additional details about the key migration options, see Section 6.4.4.10, “Keyring Command Options”.
Start the migration server with the key migration options determined as just described, possibly with other options. Keep the following considerations in mind:
Other server options might be required, such as other
configuration parameters for the two keyring plugins. For
example, if keyring_file
is one of the
plugins, you must set the
keyring_file_data
system
variable if the keyring data file location is not the
default location. Other non-keyring options may be required
as well. One way to specify these options is by using
--defaults-file
to name an
option file that contains the required options.
If you invoke the migration server from a system account
different from that normally used to run MySQL, it might
create keyring directories or files that are inaccessible to
the server during normal operation. Suppose that
mysqld normally runs as the
mysql
operating system user, but you
invoke the migration server while logged in as
isabel
. Any new directories or files
created by the migration server are owned by
isabel
. Subsequent startup fails when a
server run as the mysql
operating system
user attempts to access file system objects owned by
isabel
.
To avoid this issue, start the migration server as the
root
operating system user and provide a
--user=
option, where user_name
user_name
is the
system account normally used to run MySQL.
The migration server expects path name option values to be full paths. Relative path names may not be resolved as you expect.
Example command line for offline key migration:
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf
--keyring-migration-source=keyring_file.so
--keyring-migration-destination=keyring_encrypted_file.so
--keyring_encrypted_file_password=password
Example command line for online key migration:
mysqld --defaults-file=/usr/local/mysql/etc/my.cnf --keyring-migration-source=keyring_file.so --keyring-migration-destination=keyring_encrypted_file.so --keyring_encrypted_file_password=password
--keyring-migration-host=localhost --keyring-migration-user=root --keyring-migration-password=root_password
The key migration server performs the migration operation as follows:
(Online migration only) Connect to the running server using
the connection options. The account used to connect must
have the SUPER
privilege
required to modify the global
keyring_operations
system
variable.
(Online migration only) Disable
keyring_operations
on the
running server. (The running server must support
keyring_operations
, which
means it must be from MySQL 5.7.21 or higher.)
Load the source and destination keyring plugins.
Copy keys from the source keyring to the destination keyring.
Unload the keyring plugins.
(Online migration only) Enable
keyring_operations
on the
running server.
(Online migration only) Disconnect from the running server.
Exit.
If an error occurs during key migration, any keys that were copied to the destination plugin are removed, leaving the destination keystore unchanged.
For an online migration operation, the migration server takes
care of enabling and disabling
keyring_operations
on the
running server. However, if the migration server exits
abnormally (for example, if someone forcibly terminates it),
it is possible that
keyring_operations
was not
re-enabled on the running server, leaving it unable to perform
keyring operations. In this case, it may be necessary to
connect to the running server and enable
keyring_operations
manually.
After a successful online key migration operation, the running server might need to be restarted:
If the running server was using the source keystore, it need not be restarted after the migration.
If the running server was using the source keystore before the migration but should use the destination keystore after the migration, it must be reconfigured to use the destination keyring plugin and restarted.
If the running server was using the destination keystore and continues to use it, it should be restarted after the migration to load all keys migrated into the destination keystore.
MySQL server key migration mode supports pausing a single running server. To perform a key migration if multiple key servers are using the keystores involved, use this procedure:
Connect to each running server manually and set
keyring_operations=OFF
.
Use the migration server to perform an offline key migration.
Connect to each running server manually and set
keyring_operations=ON
.
All running servers must support the
keyring_operations=ON
system
variable.