#### 6.4.4.2 Keyring Component Installation

[]()[]()[]()[]()

 Keyring service consumers require that a keyring component or plugin be installed:

* To use a keyring component, begin with the instructions here.

* To use a keyring plugin instead, begin with [Section 6.4.4.3, “Keyring Plugin Installation”](keyring-plugin-installation.html).

* If you intend to use keyring functions in conjunction with the chosen keyring component or plugin, install the functions after installing that component or plugin, using the instructions in [Section 6.4.4.14, “General-Purpose Keyring Key-Management Functions”](keyring-functions-general-purpose.html).

Note

 Only one keyring component or plugin should be enabled at a time. Enabling multiple keyring components or plugins is unsupported and results may not be as anticipated.

 MySQL provides these keyring component choices:

* `component_keyring_file`: Stores keyring data in a file local to the server host. Available in MySQL Community Edition and MySQL Enterprise Edition distributions.

* `component_keyring_encrypted_file`: Stores keyring data in an encrypted, password-protected file local to the server host. Available in MySQL Enterprise Edition distributions.

 To be usable by the server, the component library file must be located in the MySQL plugin directory (the directory named by the [`plugin_dir`](server-system-variables.html#sysvar_plugin_dir) system variable). If necessary, configure the plugin directory location by setting the value of [`plugin_dir`](server-system-variables.html#sysvar_plugin_dir) at server startup.

 A keyring component or plugin must be loaded early during the server startup sequence so that other components can access it as necessary during their own initialization. For example, the `InnoDB` storage engine uses the keyring for tablespace encryption, so a keyring component or plugin must be loaded and available prior to `InnoDB` initialization.

 Unlike keyring plugins, keyring components are not loaded using the [`--early-plugin-load`](server-options.html#option_mysqld_early-plugin-load) server option or configured using system variables. Instead, the server determines which keyring component to load during startup using a manifest, and the loaded component consults its own configuration file when it initializes. Therefore, to install a keyring component, you must:

1. Write a manifest that tells the server which keyring component to load.

2. Write a configuration file for that keyring component.

 The first step in installing a keyring component is writing a manifest that indicates which component to load. During startup, the server reads either a global manifest file, or a global manifest file paired with a local manifest file:

* The server attempts to read its global manifest file from the directory where the server is installed.

* If the global manifest file indicates use of a local manifest file, the server attempts to read its local manifest file from the data directory.

* Although global and local manifest files are located in different directories, the file name is `mysqld.my` in both locations.

* It is not an error for a manifest file not to exist. In this case, the server attempts no component loading associated with the file.

 Local manifest files permit setting up component loading for multiple instances of the server, such that loading instructions for each server instance are specific to a given data directory instance. This enables different MySQL instances to use different keyring components.

 Server manifest files have these properties:

* A manifest file must be in valid JSON format.

* A manifest file permits these items:

  * `"read_local_manifest"`: This item is permitted only in the global manifest file. If the item is not present, the server uses only the global manifest file. If the item is present, its value is `true` or `false`, indicating whether the server should read component-loading information from the local manifest file.

     If the `"read_local_manifest"` item is present in the global manifest file along with other items, the server checks the `"read_local_manifest"` item value first:

    * If the value is `false`, the server processes the other items in the global manifest file and ignores the local manifest file.

    * If the value is `true`, the server ignores the other items in the global manifest file and attempts to read the local manifest file.

  * `"components"`: This item indicates which component to load. The item value is a string that specifies a valid component URN, such as `"file://component_keyring_file"`. A component URN begins with `file://` and indicates the base name of the library file located in the MySQL plugin directory that implements the component.

* Server access to a manifest file should be read only. For example, a `mysqld.my` server manifest file may be owned by `root` and be read/write to `root`, but should be read only to the account used to run the MySQL server. If the manifest file is found during startup to be read/write to that account, the server writes a warning to the error log suggesting that the file be made read only.

* The database administrator has the responsibility for creating any manifest files to be used, and for ensuring that their access mode and contents are correct. If an error occurs, server startup fails and the administrator must correct any issues indicated by diagnostics in the server error log.

 Given the preceding manifest file properties, to configure the server to load `component_keyring_file`, create a global manifest file named `mysqld.my` in the [**mysqld**](mysqld.html) installation directory, and optionally create a local manifest file, also named `mysqld.my`, in the data directory. The following instructions describe how to load `component_keyring_file`. To load a different keyring component, substitute its name for `component_keyring_file`.

* To use a global manifest file only, the file contents look like this:

  ```
  {
    "components": "file://component_keyring_file"
  }
  ```

   Create this file in the directory where [**mysqld**](mysqld.html) is installed.

* Alternatively, to use a global and local manifest file pair, the global file looks like this:

  ```
  {
    "read_local_manifest": true
  }
  ```

   Create this file in the directory where [**mysqld**](mysqld.html) is installed.

   The local file looks like this:

  ```
  {
    "components": "file://component_keyring_file"
  }
  ```

   Create this file in the data directory.

 With the manifest in place, proceed to configuring the keyring component. To do this, check the notes for your chosen keyring component for configuration instructions specific to that component:

* `component_keyring_file`: [Section 6.4.4.4, “Using the component\_keyring\_file File-Based Keyring Component”](keyring-file-component.html).

* `component_keyring_encrypted_file`: [Section 6.4.4.5, “Using the component\_keyring\_encrypted\_file Encrypted File-Based Keyring Component”](keyring-encrypted-file-component.html).

 After performing any component-specific configuration, start the server. Verify component installation by examining the Performance Schema [`keyring_component_status`](performance-schema-keyring-component-status-table.html) table:

```
mysql> SELECT * FROM performance_schema.keyring_component_status;
+---------------------+-------------------------------------------------+
| STATUS_KEY          | STATUS_VALUE                                    |
+---------------------+-------------------------------------------------+
| Component_name      | component_keyring_file                          |
| Author              | Oracle Corporation                              |
| License             | GPL                                             |
| Implementation_name | component_keyring_file                          |
| Version             | 1.0                                             |
| Component_status    | Active                                          |
| Data_file           | /usr/local/mysql/keyring/component_keyring_file |
| Read_only           | No                                              |
+---------------------+-------------------------------------------------+
```

 A `Component_status` value of `Active` indicates that the component initialized successfully.

 If the component cannot be loaded, server startup fails. Check the server error log for diagnostic messages. If the component loads but fails to initialize due to configuration problems, the server starts but the `Component_status` value is `Disabled`. Check the server error log, correct the configuration issues, and use the [`ALTER INSTANCE RELOAD KEYRING`](alter-instance.html#alter-instance-reload-keyring) statement to reload the configuration.

 Keyring components should be loaded only by using a manifest file, not by using the [`INSTALL COMPONENT`](install-component.html) statement. Keyring components loaded using that statement may be available too late in the server startup sequence for certain components that use the keyring, such as `InnoDB`, because they are registered in the `mysql.component` system table and loaded automatically for subsequent server restarts. But `mysql.component` is an `InnoDB` table, so any components named in it can be loaded during startup only after `InnoDB` initialization.

 If no keyring component or plugin is available when a component tries to access the keyring service, the service cannot be used by that component. As a result, the component may fail to initialize or may initialize with limited functionality. For example, if `InnoDB` finds that there are encrypted tablespaces when it initializes, it attempts to access the keyring. If the keyring is unavailable, `InnoDB` can access only unencrypted tablespaces.

