MySQL 5.7 Reference Manual Including MySQL NDB Cluster 7.5 and NDB Cluster 7.6
A keyring migration copies keys from one keystore to another, enabling a DBA to switch a MySQL installation to a different keystore. to another. A successful migration operation has this result:
The destination keystore contains the keys it had prior to the migration, plus the keys from the source keystore.
The source keystore remains 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 following sections discuss the characteristics of offline and online migrations and describe how to perform migrations.
A key migration is either offline or online:
Offline migration: For use when you are sure that no running server on the local host is using the source or destination keystore. In this case, the migration operation can copy keys from the source keystore to the destination without the possibility of a running server modifying keystore content during the operation.
Online migration: For use when a running server on the local host is using the source or destination keystore. In this case, care must be taken to prevent that server from updating keystores during the migration. This involves connecting to the running server and instructing it to pause keyring operations so that keys can be copied safely from the source keystore to the destination. When key copying is complete, the running server is permitted to resume keyring operations.
When you plan a key migration, use these points to decide whether it should be offline or online:
Do not perform offline migration involving a keystore that is in use by a running server.
Pausing keyring operations during an online migration is
accomplished by connecting to the running server and
setting its global
keyring_operations
system
variable to OFF
before key copying and
ON
after key copying. This has several
implications:
keyring_operations
was introduced in MySQL 5.7.21, so online migration is
possible only if the running server is from MySQL
5.7.21 or higher. If the running server is older, you
must stop it, perform an offline migration, and
restart it. All migration instructions elsewhere that
refer to
keyring_operations
are subject to this condition.
The account used to connect to the running server must
have the SUPER
privilege required to modify
keyring_operations
.
For an online migration, the migration operation takes
care of enabling and disabling
keyring_operations
on
the running server. If the migration operation exits
abnormally (for example, if it is forcibly
terminated), it is possible for
keyring_operations
to
remain disabled 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 using this statement:
SET GLOBAL keyring_operations = ON;
Online key migration provides for pausing keyring operations on a single running server. To perform a migration if multiple running servers are using the keystores involved, use the procedure described at Key Migration Involving Multiple Running Servers.
As of MySQL 5.7.21, a MySQL server becomes a migration server if invoked in a special operational mode that supports key migration. A migration server 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).
To perform a key migration operation using a migration server, determine the key migration options required to specify which keyring plugins or components are involved, and whether the migration is offline or online:
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. For key migration operations, both options are mandatory. 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.
For an online migration, some running server currently is using the source or destination keystore. To invoke the migration server, specify additional 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 because the migration server can
migrate keys only between keystores managed by local
plugins.
--keyring-migration-user
,
--keyring-migration-password
:
The account credentials 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.11, “Keyring Command Options”.
Start the migration server with key migration options indicating the source and destination keystores and whether the migration is offline or online, possibly with other options. Keep the following considerations in mind:
Other server options might be required, such as
configuration parameters for the two keyring plugins. For
example, if keyring_file
is the source
or destination, 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.
The migration server expects path name option values to be full paths. Relative path names may not be resolved as you expect.
The user who invokes a server in key-migration mode must
not be the root
operating system user,
unless the --user
option is
specified with a non-root
user name to
run the server as that user.
The user a server in key-migration mode runs as must have permission to read and write any local keyring files, such as the data file for a file-based plugin.
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. Alternatively,
after the migration, examine the keyring-related file
system objects and change their ownership and permissions
if necessary using chown,
chmod, or similar commands, so that the
objects are accessible to the running server.
Example command line for offline migration (enter the command on a single line):
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 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=127.0.0.1 --keyring-migration-user=root --keyring-migration-password=root_password
The key migration server performs a migration operation as follows:
(Online migration only) Connect to the running server using the connection options.
(Online migration only) Disable
keyring_operations
on the
running server.
Load the source and destination keyring plugins.
Copy keys from the source keystore to the destination.
Unload the keyring plugins.
(Online migration only) Enable
keyring_operations
on the
running server.
(Online migration only) Disconnect from the running server.
If an error occurs during key migration, the destination keystore is restored to its premigration state.
For an online migration operation, the migration server
takes care of enabling and disabling
keyring_operations
on the
running server. If the migration server exits abnormally
(for example, if it is forcibly terminated), it is possible
for keyring_operations
to
remain disabled 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
using this statement:
SET GLOBAL keyring_operations = ON;
After a successful online key migration operation, the running server might need to be restarted:
If the running server was using the source keystore before the migration and should continue to use it after the migration, it need not be restarted after the migration.
If the running server was using the destination keystore before the migration and should continue to use it after the migration, it should be restarted after the migration to load all keys migrated into the destination keystore.
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 keystore and restarted. In this case, be aware that although the running server is paused from modifying the source keystore during the migration itself, it is not paused during the interval between the migration and the subsequent restart. Care should be taken that the server does not modify the source keystore during this interval because any such changes will not be reflected in the destination keystore.
Online key migration provides for pausing keyring operations on a single running server. To perform a migration if multiple running servers are using the keystores involved, use this procedure:
Connect to each running server manually and set
keyring_operations=OFF
.
This ensures that no running server is using the source or
destination keystore and satisfies the required condition
for offline migration.
Use a migration server to perform an offline key migration for each paused server.
Connect to each running server manually and set
keyring_operations=ON
.
All running servers must support the
keyring_operations
system
variable. Any server that does not must be stopped before the
migration and restarted after.