MySQL 5.7 Reference Manual Including MySQL NDB Cluster 7.5 and NDB Cluster 7.6
MySQL Keyring plugins support the following system variables. Use them to configure keyring plugin operation. These variables are unavailable unless the appropriate keyring plugin is installed (see Section 6.4.4.1, “Keyring Plugin Installation”).
Command-Line Format | --keyring-aws-cmk-id=value |
---|---|
Introduced | 5.7.19 |
System Variable | keyring_aws_cmk_id |
Scope | Global |
Dynamic | Yes |
Type | String |
The customer master key (CMK) ID obtained from the AWS KMS
server and used by the keyring_aws
plugin. This variable is unavailable unless that plugin is
installed.
This variable is mandatory. If not specified,
keyring_aws
initialization fails.
Command-Line Format | --keyring-aws-conf-file=file_name |
---|---|
Introduced | 5.7.19 |
System Variable | keyring_aws_conf_file |
Scope | Global |
Dynamic | No |
Type | File name |
Default Value | platform specific |
The location of the configuration file for the
keyring_aws
plugin. This variable is
unavailable unless that plugin is installed.
At plugin startup, keyring_aws
reads the
AWS secret access key ID and key from the configuration
file. For the keyring_aws
plugin to start
successfully, the configuration file must exist and contain
valid secret access key information, initialized as
described in Section 6.4.4.5, “Using the keyring_aws Amazon Web Services Keyring Plugin”.
The default file name is
keyring_aws_conf
, located in the default
keyring file directory. The location of this default
directory is the same as for the
keyring_file_data
system
variable. See the description of that variable for details,
as well as for considerations to take into account if you
create the directory manually.
Command-Line Format | --keyring-aws-data-file |
---|---|
Introduced | 5.7.19 |
System Variable | keyring_aws_data_file |
Scope | Global |
Dynamic | No |
Type | File name |
Default Value | platform specific |
The location of the storage file for the
keyring_aws
plugin. This variable is
unavailable unless that plugin is installed.
At plugin startup, if the value assigned to
keyring_aws_data_file
specifies a file that does not exist, the
keyring_aws
plugin attempts to create it
(as well as its parent directory, if necessary). If the file
does exist, keyring_aws
reads any
encrypted keys contained in the file into its in-memory
cache. keyring_aws
does not cache
unencrypted keys in memory.
The default file name is
keyring_aws_data
, located in the default
keyring file directory. The location of this default
directory is the same as for the
keyring_file_data
system
variable. See the description of that variable for details,
as well as for considerations to take into account if you
create the directory manually.
Command-Line Format | --keyring-aws-region=value |
---|---|
Introduced | 5.7.19 |
System Variable | keyring_aws_region |
Scope | Global |
Dynamic | Yes |
Type | Enumeration |
Default Value | us-east-1 |
Valid Values |
|
The AWS region for the keyring_aws
plugin. This variable is unavailable unless that plugin is
installed.
Command-Line Format | --keyring-encrypted-file-data=file_name |
---|---|
Introduced | 5.7.21 |
System Variable | keyring_encrypted_file_data |
Scope | Global |
Dynamic | Yes |
Type | File name |
Default Value | platform specific |
The path name of the data file used for secure data storage
by the keyring_encrypted_file
plugin.
This variable is unavailable unless that plugin is
installed. The file location should be in a directory
considered for use only by keyring plugins. For example, do
not locate the file under the data directory.
Keyring operations are transactional: The
keyring_encrypted_file
plugin uses a
backup file during write operations to ensure that it can
roll back to the original file if an operation fails. The
backup file has the same name as the value of the
keyring_encrypted_file_data
system variable with a suffix of
.backup
.
Do not use the same
keyring_encrypted_file
data file for
multiple MySQL instances. Each instance should have its own
unique data file.
The default file name is
keyring_encrypted
, located in a
directory that is platform specific and depends on the value
of the INSTALL_LAYOUT
CMake option, as shown in the following
table. To specify the default directory for the file
explicitly if you are building from source, use the
INSTALL_MYSQLKEYRINGDIR
CMake option.
INSTALL_LAYOUT Value |
Default keyring_encrypted_file_data Value |
---|---|
DEB , RPM , SLES ,
SVR4 |
/var/lib/mysql-keyring/keyring_encrypted |
Otherwise | keyring/keyring_encrypted under the
CMAKE_INSTALL_PREFIX
value |
At plugin startup, if the value assigned to
keyring_encrypted_file_data
specifies a file that does not exist, the
keyring_encrypted_file
plugin attempts to
create it (as well as its parent directory, if necessary).
If you create the directory manually, it should have a
restrictive mode and be accessible only to the account used
to run the MySQL server. For example, on Unix and Unix-like
systems, to use the
/usr/local/mysql/mysql-keyring
directory, the following commands (executed as
root
) create the directory and set its
mode and ownership:
cd /usr/local/mysql mkdir mysql-keyring chmod 750 mysql-keyring chown mysql mysql-keyring chgrp mysql mysql-keyring
If the keyring_encrypted_file
plugin
cannot create or access its data file, it writes an error
message to the error log. If an attempted runtime assignment
to
keyring_encrypted_file_data
results in an error, the variable value remains unchanged.
Once the keyring_encrypted_file
plugin
has created its data file and started to use it, it is
important not to remove the file. Loss of the file causes
data encrypted using its keys to become inaccessible. (It
is permissible to rename or move the file, as long as you
change the value of
keyring_encrypted_file_data
to match.)
keyring_encrypted_file_password
Command-Line Format | --keyring-encrypted-file-password=password |
---|---|
Introduced | 5.7.21 |
System Variable | keyring_encrypted_file_password |
Scope | Global |
Dynamic | Yes |
Type | String |
The password used by the
keyring_encrypted_file
plugin. This
variable is unavailable unless that plugin is installed.
This variable is mandatory. If not specified,
keyring_encrypted_file
initialization
fails.
If this variable is specified in an option file, the file should have a restrictive mode and be accessible only to the account used to run the MySQL server.
Once the
keyring_encrypted_file_password
value has been set, changing it does not rotate the
keyring password and could make the server inaccessible.
If an incorrect password is provided, the
keyring_encrypted_file
plugin cannot
load keys from the encrypted keyring file.
The password value cannot be displayed at runtime with
SHOW VARIABLES
or the
Performance Schema
global_variables
table because
the display value is obfuscated.
Command-Line Format | --keyring-file-data=file_name |
---|---|
Introduced | 5.7.11 |
System Variable | keyring_file_data |
Scope | Global |
Dynamic | Yes |
Type | File name |
Default Value | platform specific |
The path name of the data file used for secure data storage
by the keyring_file
plugin. This variable
is unavailable unless that plugin is installed. The file
location should be in a directory considered for use only by
keyring plugins. For example, do not locate the file under
the data directory.
Keyring operations are transactional: The
keyring_file
plugin uses a backup file
during write operations to ensure that it can roll back to
the original file if an operation fails. The backup file has
the same name as the value of the
keyring_file_data
system
variable with a suffix of .backup
.
Do not use the same keyring_file
data
file for multiple MySQL instances. Each instance should have
its own unique data file.
The default file name is keyring
,
located in a directory that is platform specific and depends
on the value of the
INSTALL_LAYOUT
CMake option, as shown in the following
table. To specify the default directory for the file
explicitly if you are building from source, use the
INSTALL_MYSQLKEYRINGDIR
CMake option.
INSTALL_LAYOUT Value |
Default keyring_file_data Value |
---|---|
DEB , RPM , SLES ,
SVR4 |
/var/lib/mysql-keyring/keyring |
Otherwise | keyring/keyring under the
CMAKE_INSTALL_PREFIX
value |
At plugin startup, if the value assigned to
keyring_file_data
specifies
a file that does not exist, the
keyring_file
plugin attempts to create it
(as well as its parent directory, if necessary).
If you create the directory manually, it should have a
restrictive mode and be accessible only to the account used
to run the MySQL server. For example, on Unix and Unix-like
systems, to use the
/usr/local/mysql/mysql-keyring
directory, the following commands (executed as
root
) create the directory and set its
mode and ownership:
cd /usr/local/mysql mkdir mysql-keyring chmod 750 mysql-keyring chown mysql mysql-keyring chgrp mysql mysql-keyring
If the keyring_file
plugin cannot create
or access its data file, it writes an error message to the
error log. If an attempted runtime assignment to
keyring_file_data
results
in an error, the variable value remains unchanged.
Once the keyring_file
plugin has
created its data file and started to use it, it is
important not to remove the file. For example,
InnoDB
uses the file to store the
master key used to decrypt the data in tables that use
InnoDB
tablespace encryption; see
Section 14.14, “InnoDB Data-at-Rest Encryption”. Loss of the file
causes data in such tables to become inaccessible. (It is
permissible to rename or move the file, as long as you
change the value of
keyring_file_data
to
match.) It is recommended that you create a separate
backup of the keyring data file immediately after you
create the first encrypted table and before and after
master key rotation.
Command-Line Format | --keyring-okv-conf-dir=dir_name |
---|---|
Introduced | 5.7.12 |
System Variable | keyring_okv_conf_dir |
Scope | Global |
Dynamic | Yes |
Type | Directory name |
Default Value | empty string |
The path name of the directory that stores configuration
information used by the keyring_okv
plugin. This variable is unavailable unless that plugin is
installed. The location should be a directory considered for
use only by the keyring_okv
plugin. For
example, do not locate the directory under the data
directory.
The default
keyring_okv_conf_dir
value
is empty. For the keyring_okv
plugin to
be able to access Oracle Key Vault, the value must be set to
a directory that contains Oracle Key Vault configuration and
SSL materials. For instructions on setting up this
directory, see Section 6.4.4.4, “Using the keyring_okv KMIP Plugin”.
The directory should have a restrictive mode and be
accessible only to the account used to run the MySQL server.
For example, on Unix and Unix-like systems, to use the
/usr/local/mysql/mysql-keyring-okv
directory, the following commands (executed as
root
) create the directory and set its
mode and ownership:
cd /usr/local/mysql mkdir mysql-keyring-okv chmod 750 mysql-keyring-okv chown mysql mysql-keyring-okv chgrp mysql mysql-keyring-okv
If the value assigned to
keyring_okv_conf_dir
specifies a directory that does not exist, or that does not
contain configuration information that enables a connection
to Oracle Key Vault to be established,
keyring_okv
writes an error message to
the error log. If an attempted runtime assignment to
keyring_okv_conf_dir
results in an error, the variable value and keyring
operation remain unchanged.
Introduced | 5.7.21 |
---|---|
System Variable | keyring_operations |
Scope | Global |
Dynamic | Yes |
Type | Boolean |
Default Value | ON |
Whether keyring operations are enabled. This variable is used during key migration operations. See Section 6.4.4.7, “Migrating Keys Between Keyring Keystores”.