mmkeyserv command
Manages encryption key servers and clients.
Synopsis
mmkeyserv server {add | update}
ServerName [--port RestPortNumber] [--user-id RestUserID]
[--server-pwd PasswordFile] [--accept] [--kmip-cert CertFilesPrefix]
[--backup ServerName[,ServerName...]] [--distribute | --nodistribute]
[--timeout ConnectionTimeout] [--retry ConnectionAttempts]
[--interval Microseconds]
ormmkeyserv server delete ServerName
ormmkeyserv server show [ServerName] [-Y]
ormmkeyserv tenant add TenantName
--server ServerName [--server-pwd PasswordFile]
ormmkeyserv tenant delete TenantName
--server ServerName [--server-pwd PasswordFile]
ormmkeyserv tenant show [TenantName] [--server ServerName] [-Y]
ormmkeyserv key create --server ServerName [--server-pwd PasswordFile]
--tenant TenantName [--count NumberOfKeys]
ormmkeyserv key delete --server ServerName [--server-pwd PasswordFile]
{--all --tenant TenantName | --file ListOfKeysFile}
ormmkeyserv key show --server ServerName [--server-pwd PasswordFile]
--tenant TenantName
ormmkeyserv client create ClientName
--server ServerName [--server-pwd PasswordFile]
[--cert ClientCertFile --priv ClientPrivateKeyFile
{--ca-cert CACertFilePrefix | --ca-chain CACertChainFile} ]
[--days DaysToExpiration][--keystore-pwd PasswordFile]
ormmkeyserv client delete ClientName
ormmkeyserv client register ClientName
--rkm-id RkmID --tenant TenantName [--server-pwd PasswordFile]
ormmkeyserv client deregister ClientName
--tenant TenantName [--server-pwd PasswordFile]
ormmkeyserv client show [ClientName | --server ServerName] [-Y]
ormmkeyserv client update ClientName [--client NewClientName]
[--cert ClientCertFile --priv ClientPrivateKeyFile
{--ca-cert CACertFilePrefix | --ca-chain CACertChainFile} ]
[--force] [--days DaysToExpiration] [--keystore-pwd PasswordFile]
[--server-pwd PasswordFile]
ormmkeyserv rkm change RkmID {[--rkm-id NewRkmID]
[--backup ServerName[,ServerName...]] [--distribute | --nodistribute]
[--timeout ConnectionTimeout] [--retry ConnectionAttempts]
[--interval Microseconds]}
ormmkeyserv rkm show
Availability
Available with IBM Spectrum Scale Advanced Edition, IBM Spectrum Scale Data Management Edition, IBM Spectrum Scale Developer Edition, or IBM Spectrum Scale Erasure Code Edition.
Description
With the mmkeyserv command, you can configure a cluster and a remote key manager (RKM) server so that nodes in the cluster can retrieve master encryption keys when they need to. You must set up an RKM server before you run this command. The RKM server software must be IBM® Security Key Lifecycle Manager (SKLM). Nodes in the cluster must have direct network access to the RKM server.
With this command you can connect to an RKM server, create GPFS tenants, create encryption keys, and create and register key clients. The command automatically generates and exchanges certificates and sets up a local keystore. You can also use this command to securely delete key clients, encryption keys, and tenants. You can run this command from any node in the cluster. Each node has a configuration file and a copy of the local keystore. Configuration changes affect all nodes in the cluster.
0 to 9
A to Z
a to z
!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
Because the password file is a security-sensitive file, it must have the following characteristics:
- It must be a regular file.
- It must be owned by the root user.
- Only the root user must have permission to read or write it.
- client
or
key client - An entity in the cluster that represents the nodes that access encrypted files. The key client receives master encryption keys from the tenant of the RKM server.
- IBM Security Key Lifecycle Manager (SKLM)
- Required key management server software.
- Master encryption key (MEK)
- A key for encrypting file encryption keys.
- Remote key management (RKM) server
- A server with software that authenticates clients and provides them with master encryption keys.
- RKM.conf file
- A configuration file that the mmkeyserv command maintains. Each node in the cluster has a copy of this file. The full path is /var/mmfs/ssl/keyServ/RKM.conf.
- RKM stanza
- A block of configuration information that describes a registered key client. RKM stanzas are stored in the RKM.conf file.
- RKM ID
- An identifier for an RKM stanza.
- tenant
- A device group in SKLM that contains MEKs for registered key clients.
Parameters
- server
- Manages a connection with an RKM server.
- add
- Adds an RKM server connection to the IBM Spectrum
Scale
cluster. You can adjust the values of some of these options later with the mmkeyserv rkm
change command.
- ServerName
- Specifies the host name or IP address of the RKM server.
- --port RestPortNumber
- Specifies
the port number for the Representational State Transfer (REST) interface on the SKLM server:
- If SKLM is configured to use its default REST port for communications with its clients, you do
not need to specify this parameter. IBM
Spectrum Scale
automatically tries to connect with SKLM through the default REST port number of each of the
supported versions of SKLM serially, starting with the earliest supported version. If IBM
Spectrum Scale successfully connects with SKLM through the
default REST port and successfully retrieves the REST certificates, it stops searching for a port
and uses the successful port number for future communications with SKLM.Note: The default SKLM REST port number depends on the version of SKLM that is installed on the RKM server. For more information, see Firewall recommendations for IBM SKLM.
- If SKLM is not configured to use its default REST port number, you must specify the
--port
parameter with the correct port number so that IBM Spectrum Scale can connect with SKLM. If you do not specify a port number or if you specify the incorrect port number, IBM Spectrum Scale fails to connect with SKLM and displays an error message.
- If SKLM is configured to use its default REST port for communications with its clients, you do
not need to specify this parameter. IBM
Spectrum Scale
automatically tries to connect with SKLM through the default REST port number of each of the
supported versions of SKLM serially, starting with the earliest supported version. If IBM
Spectrum Scale successfully connects with SKLM through the
default REST port and successfully retrieves the REST certificates, it stops searching for a port
and uses the successful port number for future communications with SKLM.
- --user-id RestUserID
- Specifies the user ID for the RKM server. The default value is SKLMAdmin.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- --accept
- Configures the command to automatically accept certificates from the RKM server. The acceptance prompt is suppressed.
- [--kmip-cert CertFilesPrefix]
- Specifies the path and the file name prefix of non-self-signed certificate files in a
certificate chain.Important:For more information about adding certificates of either kind to the configuration, see Simplified setup: Using SKLM with a self-signed certificate.
- You must use this option when the specified key server is using a chain of certificates from a certificate authority (CA) or other non-self-signed certificate chain for communication on the KMIP port.
- If you omit this option, the command assumes that the specified key server is using a self-signed certificate for communication on the KMIP port. The command retrieves the self-signed certificate from the key server automatically.
The certificate files must be formatted as PEM-encoded X.509 certificates. You must manually retrieve the certificate files from the key server. Copy the files to the node on which you are issuing the mmkeyserv command. Rename the files so that the full path and the file name of each file in the chain has the following format:
where:CertFilesPrefix.n.cert
CertFilesPrefix
- Is the full path and the file name prefix of the certificate file.
n
- Is an integer that identifies the place of the certificate in the certificate chain:
0
indicates that the file is the root CA certificate.- An integer in the range
1 - (n-1)
indicates that the file is an intermediate CA certificate. n
indicates that the file is the endpoint certificate.
Note: A valid certificate chain can contain zero or more intermediate certificates. cert
- Is the suffix of the certificate file.
For example, in the following set of certificate files, the CertFilesPrefix is /tmp/certificate/sklmChain:- /tmp/certificate/sklmChain.0.cert contains the root certificate.
- /tmp/certificate/sklmChain.1.cert contains an intermediate certificate.
- /tmp/certificate/sklmChain.2.cert contains the endpoint certificate.
- --backup ServerName[,ServerName...]
- Specifies a comma-separated list of server names that you want to add to the list of backup RKM
servers in the RKM.conf file. If an IBM
Spectrum Scale node cannot retrieve a master encryption key
from its main RKM server, it tries each backup server in the list until it either retrieves a key or
exhausts the list. Note: The mmkeyserv command itself does not attempt to contact backup servers or to replicate client information across background servers. The system administrator is responsible for maintaining replication across backup servers.
- --distribute | --nodistribute
-
- --distribute
- Attempts to arrange the list of RKM server names (main RKM server and backup RKM servers) in the RKM.conf file in a different order on each node so that each node connects with the servers in a different order. This option provides some performance advantage in retrieving MEKs. This option is the default.
- --nodistribute
- Does not attempt to arrange the list of backup RKM server names in the RKM.conf file.
- --timeout ConnectionTimeout
- Sets the connection timeout in seconds for retrieving an MEK from an RKM server. The valid range is 1 - 120 seconds. The default value is 60 seconds.
- --retry ConnectionAttempts
- Sets the number of attempts to retry a connection to an RKM server. The valid range is 1 - 10 retries. The default value is three retries.
- --interval Microseconds
- Specifies the number of microseconds to wait between connection retries. The valid range is 1 - 1000000000. The default value is 10000 (0.1 seconds).
- update
- Updates a connection between an IBM Spectrum
Scale cluster and an RKM server.
- The command always gets a fresh server certificate from the RKM server.
- If you do not specify the --port option, the command first tries to connect with SKLM through the most recently used REST interface port number. If this connection fails, the command tries to connect with SKLM through the default REST interface port number of each of the supported versions of SKLM serially, starting with the earliest supported version. For more information, see the description of the --port option for the mmkeyserv server add command earlier in this topic.
- ServerName
- Specifies the host name or IP address of the RKM server.
- --port RestPortNumber
- Specifies the port number for the Representational State Transfer (REST) interface.
- --user-id RestUserID
- Specifies the user ID for the RKM server. The default value is SKLMAdmin.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password if one is required.
- --accept
- Configures the command to automatically accept certificates from the RKM server. The acceptance prompt is suppressed.
- [--kmip-cert CertFilesPrefix]
- Specifies the path and the file name prefix of non-self-signed certificate files in a
certificate chain.Important:For more information about adding certificates of either kind to the configuration, see Simplified setup: Using SKLM with a self-signed certificate.
- You must use this option when the specified key server is using a chain of certificates from a certificate authority or other non-self-signed certificate chain for communication on the KMIP port.
- If you omit this option, the command assumes that the specified key server is using a self-signed certificate for communication on the KMIP port. The command retrieves the self-signed certificate from the key server automatically.
The certificate files must be formatted as PEM-encoded X.509 certificates. You must manually retrieve the certificate files from the key server. Copy the files to the node on which you are issuing the mmkeyserv command. Rename the files so that the full path and the file name of each file in the chain has the following format:
where:CertFilesPrefix.n.cert
CertFilesPrefix
- Is the full path and the file name prefix of the certificate file.
n
- Is an integer that identifies the place of the certificate in the certificate chain:
0
indicates that the file is the root CA certificate.- An integer in the range
1 - (n-1)
indicates that the file is an intermediate CA certificate. n
indicates that the file is the endpoint certificate.
Note: A valid certificate chain can contain zero or more intermediate certificates. cert
- Is the suffix of the certificate file.
For example, in the following set of certificate files, the CertFilesPrefix is /tmp/certificate/sklmChain:- /tmp/certificate/sklmChain.0.cert contains the root certificate.
- /tmp/certificate/sklmChain.1.cert contains an intermediate certificate.
- /tmp/certificate/sklmChain.2.cert contains the endpoint certificate.
- --backup ServerName[,ServerName...]
- Specifies a comma-separated list of server names that you want to add to the backup RKM servers
that are listed in the RKM.conf file. If an IBM
Spectrum Scale node cannot retrieve a master encryption key
from its main RKM server, it tries each backup server in the list until it either retrieves a key or
exhausts the
list.Important: To remove a backup list, specify delete instead of a list of server names, as in the following example:
mmkeyserv server update ServerName --backup delete
The backup option does not change the RKM.conf file.
Note: The mmkeyserv command itself does not attempt to contact backup servers or to replicate client information across background servers. The system administrator is responsible for maintaining replication across backup servers. - --distribute | --nodistribute
- You must specify one of these two options. There is no default value.
- --distribute
- Attempts to arrange the RKM server names (main RKM server and backup RKM servers) that are listed in the RKM.conf file in a different order on each node so that each node connects with the servers in a different order. This option provides some performance advantage in retrieving MEKs.
- --nodistribute
- Does not attempt to arrange the backup RKM server names that are listed in the RKM.conf file.
Neither option changes the RKM.conf file.
- --timeout ConnectionTimeout
- Sets the connection timeout in seconds for retrieving an MEK from an RKM server. The valid range
is 1 - 120 seconds. To restore the system default value (60 seconds), you can specify either
60
or the keyword default as the ConnectionTimeout value.This option does not change the RKM.conf file.
- --retry ConnectionAttempts
- Sets the number of attempts to retry a connection to an RKM server. The valid range is 1 - 10
retries. To restore the system default value (3 retries), you can specify either
3
or the keyword default as the ConnectionAttempts value.This option does not change the RKM.conf file.
- --interval Microseconds
- Specifies the number of microseconds to wait between connection retries. The valid range is 1 -
1000000000. To restore the system default value (10000, which is 0.1 seconds), you can specify
either
10000
or the keyword default as the Microseconds value.This option does not change the RKM.conf file.
- delete
- Removes a connection with an RKM server from the cluster.
- ServerName
- Specifies the host name or IP address of the RKM server that you want to disconnect from.
- show
- Displays information about RKM servers. The following table shows the display options:
Table 1. mmkeyserv server show Option Displays information about show All servers show ServerName The specified server - ServerName
- Specifies the host name or IP address of an RKM server.
- tenant
- Manages tenants on RKM servers. A tenant is an SKLM device group for holding encryption keys.
- add
- Specifies the name of a tenant to add to the IBM Spectrum
Scale cluster.
- If the tenant is already added to the cluster, the command returns with an error.
- If the tenant exists on the RKM server but is not added to the cluster, the command adds the tenant to the cluster.
- If the tenant does not exist on the RKM server, the command creates the tenant on the server and adds the tenant to the cluster.
- delete
- Deletes a tenant from an RKM server.Note:
- If you delete a tenant that has encryption keys on the key server, the command deletes the tenant from the cluster configuration but not from the key server.
- If you delete a tenant that has no encryption keys on the key server, the command deletes the tenant from both the cluster configuration and the key server.
- TenantName
- Specifies the name of the tenant that you want to delete.
- --server ServerName
- Specifies the name of the RKM server to which the tenant belongs.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- show
- Displays information about tenants and RKM servers. The following table shows the results of
various combinations of options:
Table 2. mmkeyserv tenant show Option Displays information about show All tenants from all RKM servers show TenantName The specified tenant show --server ServerName All tenants from the specified RKM server show TenantName --server ServerName The specified tenant and the specified server - TenantName
- Specifies the name of a tenant.
- --server ServerName
- Specifies the name of an RKM server.
- key
- Manages encryption keys.
- create
- Creates encryption keys in a tenant and displays the key IDs on the console. Note: Make a note of the key IDs. You must specify an encryption key ID and an RKM ID when you write an encryption policy rule.
- --server ServerName
- Specifies the host name or IP address of an RKM server.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- --tenant TenantName
- Specifies the name of the tenant in which you want to create the encryption keys.
- --count NumberOfKeys
- Specifies the number of keys to create. The default value is 1.
- delete
- Deletes encryption keys from a tenant. CAUTION:When you delete an encryption key, any data that was encrypted by that key becomes unrecoverable.
- --server ServerName
- Specifies the host name or IP address of an RKM server.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- --all --tenant TenantName
- Deletes all the encryption keys in the specified tenant.
- --file ListOfKeysFile
- Specifies a file that contains a list of the key IDs of encryption keys that you want to delete, one key per line.
- show
- Displays information about the encryption keys in a tenant.
- --server ServerName
- Specifies the host name or IP address of an RKM server.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- --tenant TenantName
- Specifies the name of the tenant that contains the keys that you want to display.
- client
- Manages key clients. The following facts are important:
- You need only one key client per cluster per RKM server. However, you can create and use multiple key clients on the same RKM server.
- You can register only one key client per tenant per cluster. However, you can register one key client to more than one tenant in the same RKM server.
- create
- Creates a key client to communicate with the RKM server.
- ClientName
- Specifies the name of the key client that you want to create. A key client name must be 1 - 16 characters in length and must be unique within an IBM Spectrum Scale cluster.
- --server ServerName
- Specifies the name of the RKM server to which the key client belongs.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the
requirements for password files in the Description section of this topic. If this option is omitted,
the command prompts for a password.
- [--cert
ClientCertFile
--priv
ClientPrivateKeyFile
{--ca-cert CACertFilePrefix | --ca-chain CACertChainFile} ] - --cert ClientCertFile
- Specifies a file that contains a client certificate from a CA.
- --priv ClientPrivateKeyFile
- Specifies a file that contains a client private key that matches the client certificate.
- --ca-cert CACertFilePrefix
- Specifies the path and file name prefix of the certificates that signed the client certificate.
- --ca-chain CACertChainFile
- Specifies a file that contains the certificates of the CA that signed the client certificate.
Important:For more information, see the following topics:- If you are providing a client certificate from a CA for communicating with the remote key server on the KMIP port, you must specify either the --ca-cert option or the --ca-chain option.
- If you omit the --cert option, the command generates a self-signed client certificate for communicating with the remote key server on the KMIP port.
- Simplified setup: Using SKLM with a self-signed certificate
- Simplified setup: Using SKLM with a certificate chain
- The contents of a private key file must be PEM-encoded and unencrypted.
- The CA certificate chain can be specified either as a certificate chain file that contains all the CA certificates or as a set of files, one file for each CA certificate in the chain.
- If a certificate chain file is used, the certificates in it must be in PEM-encoded x509 format and must be concatenated. The CA root certificate must be first, followed by the intermediate CA certificates in order, followed by the final CA certificate that signed the client certificate.
- If certificate files are used, one file for each certificate, the certificates must be in
PEM-encoded x509 format. Each file must be renamed in the format
<CACertFilesPrefix><n>.cert, where
<CACertFilesPrefix> is the full path prefix for the CA
certificate files, such as /tmp/CA/certfiles, and <n> is
a CA certificate index. The index is 0 for the CA root certificate and n - 1 for
the last intermediate CA certificate that signed the client certificate. In the following example,
the chain consists of a CA root certificate file and two intermediate CA certificate files. The full
path prefix is /tmp/CA/certfiles:
CA root certificate /tmp/CA/certfiles.0.cert First intermediate CA root certificate: /tmp/CA/certfiles.1.cert Second intermediate CA root certificate: /tmp/CA/certfiles.2.cert
- --days DaysToExpiration
- Specifies the number of days until the newly created client certificate expires. The valid range is 1 - 18262. The default value is 1095. This parameter is not available when you specify a CA-signed certificate chain for the client certificate. The certificates in the CA certificate chain specify their expiration dates.
- --keystore-pwd PasswordFile
- Specifies a password file that contains a client keystore password. See the requirements for password files in the Description section of this topic. If this parameter is omitted the command prompts for a keystore password.
- delete
- Deletes a key client.
- ClientName
- Specifies the name of the key client that you want to delete.
- register
- Registers a key client to a tenant.
- ClientName
- Specifies the name of the key client that you want to register.
- --rkm-id RkmID
- Specifies a new RKM ID. An RKM ID must be unique within the cluster, must be 1 - 21 characters in length, and can contain only alphanumeric characters or underscore (_). It must begin with a letter or an underscore. An RKM ID identifies an RKM stanza in the RKM.conf file. The stanza contains the information that a node needs to retrieve a master encryption key (MEK) from an RKM.
- --tenant TenantName
- Specifies the name of the tenant to which you want to register the client.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- deregister
- Unregisters a key client from a tenant.
- ClientName
- Specifies the name of the key client that you want to unregister.
- --tenant TenantName
- Specifies the name of the tenant that you want to unregister the key client from.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- show
- Displays information about a key client.
- ClientName
- Specifies the name of the client whose information you want to display.
- --server ServerName
- Specifies the name of the server to which the client belongs.
- update
- Replaces an expired or unexpired client certificate with a new one in the specified key client.
- ClientName
- Specifies the name of the key client that you want to update.
- --client NewClientName
- Specifies a new name for client. A key client name must be 1 - 16 characters in length and must
be unique within an IBM Spectrum
Scale cluster. If this option is omitted, the client name is not changed.
- [--cert
ClientCertFile
--priv
ClientPrivateKeyFile
{--ca-cert CACertFilePrefix | --ca-chain CACertChainFile} ] - --cert ClientCertFile
- Specifies a file that contains a client certificate from a CA.
- --priv ClientPrivateKeyFile
- Specifies a file that contains a client private key that matches the client certificate.
- --ca-cert CACertFilePrefix
- Specifies the path and file name prefix of the certificates that signed the client certificate.
- --ca-chain CACertChainFile
- Specifies a file that contains the certificates of the CA that signed the client certificate.
- --force
- Generates a self-signed client certificate for the key client. This option is required only if
both the following conditions are true:
- You want the key client to have a self-signed client certificate.
- The key client was created with or was previously updated with a client CA-signed certificate and chain.
- You want to replace a self-signed certificate with a CA-signed certificate and chain.
- You want to replace a CA-signed certificate and chain with another CA-signed certificate and chain.
- --days DaysToExpiration
- Specifies the number of days until the new client certificate expires. The valid range is 1 - 18262. If this option is omitted, the new client certificate expires in 1095 days. This parameter is not available when you specify a CA-signed certificate chain for the client certificate. The certificates in the CA certificate chain specify their expiration dates.
- --keystore-pwd PasswordFile
- Specifies a password file that contains a client keystore password. See the requirements for password files in the Description section of this topic. If this option is omitted, the current password is not changed.
- --server-pwd PasswordFile
- Specifies a password file that contains a password for accessing the RKM server. See the requirements for password files in the Description section of this topic. If this option is omitted, the command prompts for a password.
- rkm
-
- change
- Changes the properties of an RKM stanza. For more information about an RKM stanza, see the
Description section of this topic.
- RkmID
- Specifies the RKM ID of the stanza whose properties you want to change.
- --rkm-id RkmID
- Specifies a new RKM ID. An RKM ID must be unique within the cluster, must be 1 - 21 characters in length, and can contain only alphanumeric characters or underscore (_). It must begin with a letter or an underscore. An RKM ID identifies an RKM stanza in the RKM.conf file. The stanza contains the information that a node needs to retrieve a master encryption key (MEK) from an RKM.
- --backup ServerName[,ServerName...]
- Specifies a comma-separated list of server names that you want to add to the backup RKM servers
that are listed in the RKM.conf file. If an IBM
Spectrum Scale node cannot retrieve a master encryption key
from its main RKM server, it tries each backup server in the list until it either retrieves a key or
exhausts the
list.Important: To remove a backup list, specify delete instead of a list of server names, as in the following example:
mmkeyserv rkm change RkmID --backup delete
The backup option does not change the RKM.conf file.
Note: The mmkeyserv command itself does not attempt to contact backup servers or to replicate client information across background servers. The system administrator is responsible for maintaining replication across backup servers. - --distribute | --nodistribute
-
- --distribute
- Attempts to arrange the list of RKM server names (main RKM server and backup RKM servers) in the RKM.conf file in a different order on each node so that each node connects with the servers in a different order. This option provides some performance advantage in retrieving MEKs.
- --nodistribute
- Does not attempt to arrange the list of backup RKM server names in the RKM.conf file.
- --timeout ConnectionTimeout
- Sets the connection timeout in seconds for retrieving an MEK from an RKM server. The valid range
is 1 - 120 seconds. To restore the system default value (60 seconds), you can specify either
60
or the keyword default as the ConnectionTimeout value.This option does not change the RKM.conf file.
- --retry ConnectionAttempts
- Sets the number of attempts to retry a connection to an RKM server. The valid range is 1 - 10
retries. To restore the system default value (3 retries), you can specify either
3
or the keyword default as the ConnectionAttempts value.This option does not change the RKM.conf file.
- --interval Microseconds
- Specifies the number of microseconds to wait between connection retries. The valid range is 1 -
1000000000. To restore the system default value (10000, which is 0.1 seconds), you can specify
either
10000
or the keyword default as the Microseconds value.This option does not change the RKM.conf file.
- show
- Displays information about all the RKM stanzas in the RKM.conf file of the node.
- -Y
- Displays the command output in a parseable format with a colon (:) as a field delimiter. Each
column is described by a header.Note: Fields that have a colon (:) are encoded to prevent confusion. For the set of characters that might be encoded, see the command documentation of mmclidecode. Use the mmclidecode command to decode the field.
Exit status
- 0
- Successful completion.
- Nonzero
- A failure occurred.
Security
You must have root authority to run the mmkeyserv command.
The node on which you enter the command must be able to execute remote shell commands on any other administration node in the cluster. It must be able to do so without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.
Examples
Examples 1 - 5 illustrate the steps in configuring an RKM server and a key client and generating an encryption key:- The following command makes an RKM server known to an IBM
Spectrum Scale cluster. The name
keyserver01
is the host name of the SKLM server:
The following command displays information about all RKM servers that are known to the cluster. At the moment, the only one is# mmkeyserv server add keyserver01 Enter password for the RKM server keyserver01: The security certificate(s) from keyserver01.gpfs.net must be accepted to continue. View the certificate(s) to determine whether you want to trust the certifying authority. Do you want to view or trust the certificate(s)? (view/yes/no) view Serial number: 01022a8adf20f3 SHA-256 digest: 2ca4a48a3038f37d430162be8827d91eb584e98f5b3809047ef4a1c72e15fc4c Signature: 7f0312e7be18efd72c9d8f37dbb832724859ba4bb5827c230e2161473e0753b367ed49d9935 05bd23858541475de8e021e0930725abbd3d25b71edc8fc3de20b7c2db5cd4e865f41c7c410c1d710acf222e1c45189108e 40568ddcbeb21094264da60a1d96711015a7951eb2655363309d790ab44ee7b26adf8385e2c210b8268c5aede5f82f26855 4a6fc22ece6efeee2a6264706e71416a0dbe8c39ceacd86054d7cc34dda4fffea4605c037d32129055610821af85dd9819a 4d7e4baa70c51addcda720d33bc9f8bbde6d292c028b2f525a0275ebea968c26f8f0c4b604719ae3b04e71ed7a8188cd6ad f68764374b29c91df3d101a941bf8b7189485ad72 Signature algorithm: SHA256WithRSASignature Key size: 2048 Issuer: C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net Subject: C=US, O=IBM, OU=SKLMNode, SKLMCell, CN=c40bbc1xn3.gpfs.net Serial number: 01022a24475466 SHA-256 digest: 077c3b53c5046aa893b760c11cca3a993efbc729479771e03791f9ed4f716879 Signature: 227b5befe89f2e55ef628da6b50db1ab842095a54e1505655e3d95fee753a7f7554868aa79b 294c503dc34562cf69c2a20128796758838968565c0812c4aedbb0543d396646a269c02bf4c5ce5acba4409a10effbd47ca 38ce492698e2dcdc8390b9ae3f4a47c23ee3045ff0145218668f35a63edac68201789ed0db6e5c170f5c6db49769f0b4c9a 5f208746e4342294c447793ed087fa0ac762588faf420febeb3fca411e4e725bd46476e1f9f44759a696573af5dbbc95532 18c7083c80440f2e542bf56cc5cc18156cce05efd6c2e5fea2b886c5c1e262c10af18b13ccf38c3533ba025b97bbe62f271 545b2ab5c1f50c1dca45ce504dfcfc257362e9b43 Signature algorithm: SHA256WithRSASignature Key size: 2048 Issuer: C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net Subject: C=US, O=IBM, OU=SKLMNode, SKLMCell, Root Certificate, CN=c40bbc1xn3.gpfs.net Do you trust the certificate(s) above? (yes/no) yes To display all RKM servers information, enter: c34f2n03:~ # mmkeyserv server show keyserver01 Type: SKLM Hostname: keyserver01.gpfs.net User ID: SKLMAdmin REST port: 9080 Label: 1_keyserver01 NIST: on FIPS1402: off Backup Key Servers: Distribute: yes Retrieval Timeout: 120 Retrieval Retry: 3 Retrieval Interval: 10000 REST Certificate Expiration: 2030-12-22 21:48:53 (-0500) KMIP Certificate Expiration: 2021-11-02 13:03:52 (-0400)
keyserver01
:# mmkeyserv server show keyserver01 Type: SKLM Hostname: keyserver01.gpfs.net User ID: SKLMAdmin REST port: 9080 Label: 1_keyserver01 NIST: on FIPS1402: off Backup Key Servers: Distribute: yes Retrieval Timeout: 120 Retrieval Retry: 3 Retrieval Interval: 10000 REST Certificate Expiration: 2030-12-22 21:48:53 (-0500) KMIP Certificate Expiration: 2021-11-02 13:03:52 (-0400)
- The following command creates a tenant in the server that you defined in Example 1,
keyserver01
. The name of the tenant isdevG1
:
The following command displays all the current tenants of# mmkeyserv tenant add devG1 --server keyserver01 Enter password for the RKM server keyserver01:
keyserver01
:# mmkeyserv tenant show devG1 Key Server: keyserver01.gpfs.net Registered Client: (none)
- The following command adds a key client to the tenant that you created in Example 2. The command
does not specify password files for the server and the new keystore, so the command prompts for the
passwords. The name of the key client is
c34f2n03Client1
:
The following command displays information about all the key clients on the RKM server:# mmkeyserv client create c34f2n03Client1 --server keyserver01 Enter password for the RKM server keyserver01: Create a pass phrase for keystore: Confirm your pass phrase:
# mmkeyserv client show c34f2n03Client1 Label: c34f2n03Client1 Key Server: keyserver01.gpfs.net Tenants: (none) Certificate Expiration: 2021-08-20 14:20:46 (-0400)
- The following command registers the key client from Example 3 to the tenant from Example 2. To
ensure uniqueness in RKM IDs, it is a good practice to create the RKM ID name by combining the names
of the RKM server and the tenant. However, the RKM ID cannot be longer than 21 characters. In this
example the RKM ID is
keyserver01_devG1
:
The following two commands now show that key client c34f2n03Client1 is registered to tenant devG1:# mmkeyserv client register c34f2n03Client1 --tenant devG1 --rkm-id keyserver01_devG1 Enter password for the RKM server : mmkeyserv: [I] Client currently does not have access to the key. Continue the registration process ... mmkeyserv: Successfully accepted client certificate
The following command shows the contents of the new RKM stanza that was added to the RKM.conf file:# mmkeyserv tenant show devG1 Key Server: keyserver01.gpfs.net Registered Client: c34f2n03Client1 RKM ID: keyserver01_devG1 # mmkeyserv client show c34f2n03Client1 Label: c34f2n03Client1 Key Server: keyserver01.gpfs.net Tenants: devG1 Certificate Expiration: 2021-08-20 14:20:46 (-0400)
You can also show the contents of the RKM.conf file by routing the contents of the file to the console:# mmkeyserv rkm show keyserver01_devG1 { type = SKLM kmipServerUri = tls://192.0.2.59:5696 keyStore = /var/mmfs/ssl/keyServ/serverKmip.1_keyserver01.c34f2n03Client1.1.p12 passphrase = pw4c34f2n03Client1 clientCertLabel = c34f2n03Client1 tenantName = devG1 }
# cat /var/mmfs/ssl/keyServ/RKM.conf keyserver01_devG1 { type = SKLM kmipServerUri = tls://192.0.2.59:5696 keyStore = /var/mmfs/ssl/keyServ/serverKmip.1_keyserver01.c34f2n03Client1.1.p12 passphrase = pw4c34f2n03Client1 clientCertLabel = c34f2n03Client1 tenantName = devG1 }
- The following example creates an encryption key in the tenant from Example 4. In the third line,
the command displays the new encryption key
(
KEY-d4e83148-e827-4f54-8e5b-5e1b5cc66de1
):# mmkeyserv key create --server keyserver01.gpfs.net --tenant devG1 Enter password for the RKM server keyserver01.gpfs.net: KEY-d4e83148-e827-4f54-8e5b-5e1b5cc66de1
- In
the following example, assume that client certificate c6f2bc3n9client expires in a few days. The
system administrator issues the mmkeyserv client update command to replace
the old certificate with a new one that expires in 90 days.Note: Notice that this command also updates the keystore password. If the --keystore-pwd parameter is omitted, the keystore password remains the same.
# mmkeyserv client update c6f2bc3n9client --server-pwd /u/admin/README/sklm/c6f2bc3n9.pw --days 90 --keystore-pwd /u/admin/README/sklm/client.pw mmkeyserv: [I] Client currently does not have access to the key. Continue the registration process ... mmkeyserv: Successfully accepted client certificate mmkeyserv: Propagating the cluster configuration data to all affected nodes. This is an asynchronous process. mmkeyserv: Deleting the following KMIP certificate with label: 2454534160085868372_vut_1578295912 Mon Jan 6 12:06:33 EST 2020: mmcommon pushSdr_async: mmsdrfs propagation started (12:06:35) c9f1u19p1:~ # Mon Jan 6 12:06:36 EST 2020: mmcommon pushSdr_async: mmsdrfs propagation completed; mmdsh rc=0
Location
/usr/lpp/mmfs/bin