mmauth command

Manages secure access to GPFS file systems.

Synopsis

mmauth genkey {new [--force] | commit | 
               propagate [-N {Node[,Node...] | NodeFile | NodeClass}]}

mmauth add RemoteClusterName -k KeyFile [-l CipherList]

mmauth update RemoteClusterName {[-C NewClusterName] [-k KeyFile] [-l CipherList]}

mmauth delete {RemoteClusterName | all}

mmauth grant {RemoteClusterName | all} 
    -f {all | Device[:FilesetList | --fileset FilesetList | -F FilesetFile]} 
    [-a {rw | ro | none}] [-r {uid:gid | no}]

mmauth deny {RemoteClusterName | all}
    -f {all | Device[:FilesetList | --fileset FilesetList | -F FilesetFile]}

mmauth show ciphers [-Y]

mmauth show [RemoteClusterName | all] [-Y]
            [--show-allowed-fsets | --noshow-allowed-fsets]

mmauth gencert --cname CanonicalName --cert ServerCertificateFile --out OutputKeystoreFile
               --label ClientCertificateLabel [--pwd-file KeystorePasswordFile]

Availability

Available on all IBM Storage Scale editions.

Description

The mmauth command prepares a cluster to grant secure access to file systems owned locally. The mmauth command also prepares a cluster to receive secure access to file systems owned by another cluster. Use the mmauth command to generate a public/private key pair for the local cluster. A public/private key pair must be generated on both the cluster owning the file system and the cluster desiring access to the file system. The administrators of the clusters are responsible for exchanging the public portion of the public/private key pair. Use the mmauth command to add or delete permission for a cluster to mount file systems owned by the local cluster.

When a cluster generates a new public/private key pair, administrators of clusters participating in remote file system mounts are responsible for exchanging their respective public key file /var/mmfs/ssl/id_rsa.pub generated by this command.

The administrator of a cluster desiring to mount a file system from another cluster must provide the received key file as input to the mmremotecluster command. The administrator of a cluster allowing another cluster to mount a file system must provide the received key file to the mmauth command.

The keyword appearing after mmauth determines which action is performed:

add

Adds a cluster and its associated public key to the list of clusters authorized to connect to this cluster for the purpose of mounting file systems owned by this cluster.

delete

Deletes a cluster and its associated public key from the list of clusters authorized to mount file systems owned by this cluster.

deny

Denies a cluster the authority to mount a specific file system owned by this cluster. It also removes filesets from the allowed list of filesets that can be accessed on a remote cluster.

gencert

Creates a client keystore with the keys and certificates required to communicate with the ISKLM key server.

genkey

Controls the generation and propagation of the OpenSSL key files:

new

Generates a new public/private key pair for this cluster. The key pair is placed in /var/mmfs/ssl. This must be done at least once before cipherList, the GPFS configuration parameter that enables GPFS with OpenSSL, is set.

The new key is in addition to the currently in effect committed key. Both keys are accepted until the administrator runs mmauth genkey commit.

--force: This option is used with mmauth genkey new to instruct the command to continue generating a new public/private key pair without lock protection. This option should be used only when the CCR service is not working properly due to expired cluster keys.

commit

Commits the new public/private key pair for this cluster. Once mmauth genkey commit is run, the old key pair will no longer be accepted, and remote clusters that have not updated their keys (by running mmauth update or mmremotecluster update) will be disconnected.

propagate

Ensures that the currently in effect key files are placed in /var/mmfs/ssl on the nodes specified with the -N parameter. This may be necessary if the key files are lost and adminMode central is in effect for the cluster.

grant

Allows a cluster to mount a specific file system owned by this cluster. It also adds filesets to the allowed list of filesets that can be accessed on a remote cluster. When the allowed list is created, the filesets that are not in that list cannot be accessed from the authorized remote clusters. The filesets not included in the allowed list are also not displayed in the output of mmlsfileset or mmlssnapshot commands.

show

Shows the list of clusters authorized to mount file system owned by this cluster.

update

Updates the public key and other information associated with a cluster authorized to mount file systems owned by this cluster.

When the local cluster name (or '.') is specified, mmauth update -l can be used to set the cipherList value for the local cluster. Note that you cannot use this command to change the name of the local cluster. Use the mmchcluster command for this purpose.

Note: Access controls such as grant and deny do not apply on the remote nodes that have the specified file system currently mounted. The new access control will be applied on the next mount of the file system.

Parameters

-N {Node[,Node...] | NodeFile | NodeClass}

Specifies the nodes on which the key files should be restored. The default is -N all.

For general information on how to specify node names, see Specifying nodes as input to GPFS commands.

This command does not support a NodeClass of mount.

RemoteClusterName

Specifies the remote cluster name requesting access to local GPFS file systems.

all

Indicates all remote clusters defined to the local cluster.

ciphers

Shows the supported ciphers.

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

Options

-a {rw | ro | none}

Specifies the type of access allowed:

ro: Specifies read-only access.
rw: Specifies read/write access. This is the default.
none: Specifies no access.

Note: This option can be applied only at the file system level.

-C NewClusterName

Specifies a new, fully-qualified cluster name for the already-defined cluster RemoteClusterName.

-f {Device | all}

Specifies the device name for a file system owned by this cluster. The Device argument is required. If all is specified, the command applies to all file systems owned by this cluster at the time that the command is issued.

-k KeyFile

Specifies the public key file generated by the mmauth command in the cluster requesting to remotely mount the local GPFS file system.

-l CipherList

Sets the security mode for communications between the current cluster and the remote cluster that is specified in the RemoteClusterName parameter. There are three security modes:

EMPTY: The sending node and the receiving node do not authenticate each other, do not encrypt transmitted data, and do not check data integrity.
AUTHONLY: The sending and receiving nodes authenticate each other, but they do not encrypt transmitted data and do not check data integrity. This mode is the default in IBM Storage Scale V4.2 or later.
Cipher: The sending and receiving nodes authenticate each other, encrypt transmitted data, and check data integrity. To set this mode, you must specify the name of a supported cipher, such as AES128-GCM-SHA256.

For more information about the security mode and supported ciphers, see Security mode.

-r {uid:gid | no}

Specifies a root credentials remapping (root squash) option. The UID and GID of all processes with root credentials from the remote cluster will be remapped to the specified values. The default is not to remap the root UID and GID. The uid and gid must be specified as unsigned integers or as symbolic names that can be resolved by the operating system to a valid UID and GID. Specifying no, off, or DEFAULT turns off the remapping.

For more information, see the IBM Storage Scale: Administration Guide and search on root squash.

Note: This option can be applied only at the file system level.

--cname CanonicalName

Specifies the canonical name of the client used in the certificate.

--cert ServerCertificateFile

Specifies the path name to a file containing an ISKLM certificate.

--fileset FilesetList

Specifies a comma separated list of filesets to be added to or removed from the list of filesets that are allowed to be accessed on remote cluster nodes. This attribute is available for both mmauth grant and mmauth deny actions. In the mmauth grant action, the root fileset must be included in the FilesetList when the allowed list is created for the first time. In the mmauth deny action, the root fileset cannot be removed from the allowed list and hence it must not be included in the FilesetList.

When the allowed list is created, the filesets that are not in that list cannot be accessed from the authorized remote clusters. The filesets not included in the allowed list are also not displayed in the output of mmlsfileset or mmlssnapshot commands.

Note: You cannot specify the -f all option with the FilesetList attribute. The --fileset FilesetList feature is available only with IBM Storage Scale version 5.1.4 or later, when file system format version is 28:00 or later, and file system original format version is 11:02 or later.

-F FilesetFile

Specifies the file that comprises the names of the filesets that can be added to or removed from the list of filesets that are allowed to be accessed on remote cluster nodes. Each line in the file must contain the name of a single fileset. This attribute is available for both mmauth grant and mmauth deny actions.

Note: You cannot specify the -f all option with the FilesetFile attribute. The -F FilesetFile feature is available only with IBM Storage Scale version 5.1.4 or later, when file system format version is 28:00 or later, and file system original format version is 11:02 or later.

--out OutputKeystoreFile

Specifies the path name for the file that will contain the keystore.

--pwd-file KeystorePasswordFile

Specifies the keystore password file. If omitted, you will be prompted to enter the keystore password. A maximum of 20 characters are allowed. Only the following characters are allowed in the password:

0 to 9

A to Z

a to z

!"#$%&'()*+,-./:;<=>?@[\]^_`{|}~

The --pwd KeystorePassword option is considered deprecated and may be removed in a future release.

--label ClientCertificateLabel

Specifies the label of the client certificate within the keystore. A maximum of 20 characters are allowed.

--show-allowed-fsets

If the option is used, the mmauth show command shows the list of allowed filesets. This is the default behavior if the RemoteClusterName argument is specified.

--noshow-allowed-fsets

If the option is used, the mmauth show command does not show the list of allowed filesets. This is the default behavior if the RemoteClusterName argument is omitted or the all keyword is specified.

Exit status

0: Successful completion. After a successful completion of the mmauth command, the configuration change request will have been propagated to all nodes in the cluster.
nonzero: A failure has occurred.

Security

You must have root authority to run the mmauth command.

The node on which the command is issued must be able to execute remote shell commands on any other node in the cluster without the use of a password and without producing any extraneous messages. For more information, see Requirements for administering a GPFS file system.