MySQL 5.7 Reference Manual Including MySQL NDB Cluster 7.5 and NDB Cluster 7.6 Migrating Keys Between Keyring Keystores

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:

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:

For additional details about the key migration options, see Section, “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:

Example command line for offline key migration:

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf

Example command line for online key migration:

mysqld --defaults-file=/usr/local/mysql/etc/my.cnf

The key migration server performs the migration operation as follows:

  1. (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.

  2. (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.)

  3. Load the source and destination keyring plugins.

  4. Copy keys from the source keyring to the destination keyring.

  5. Unload the keyring plugins.

  6. (Online migration only) Enable keyring_operations on the running server.

  7. (Online migration only) Disconnect from the running server.

  8. 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 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 keyring_operations manually.

After a successful online key migration operation, the running server might need to be restarted:


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:

  1. Connect to each running server manually and set keyring_operations=OFF.

  2. Use the migration server to perform an offline key migration.

  3. Connect to each running server manually and set keyring_operations=ON.

All running servers must support the keyring_operations=ON system variable.