As of MySQL 5.7.21, the MySQL server supports an operational mode that enables migration of keys between underlying keyring keystores. This enables 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
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:
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.Warning
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-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 188.8.131.52, “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_fileis one of the plugins, you must set the
keyring_file_datasystem 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-fileto 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
mysqloperating system user, but you invoke the migration server while logged in as
isabel. Any new directories or files created by the migration server will be owned by
isabel. Subsequent startup will fail when a server run as the
mysqloperating system user attempts to access file system objects owned by
To avoid this issue, start the migration server as the
rootoperating system user and provide a
user_nameis 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
SUPERprivilege required to modify the global
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_operationson the running server.
(Online migration only) Disconnect from the running server.
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 will not
have been 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
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 will continue 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:
All running servers must support the