mmafmcoskeys command

Manages an access key and a secret key to access a bucket on a cloud object storage.

Synopsis

mmafmcoskeys bucket[:{[Region@]Server | ExportMap}] 
            {set {akey skey | --keyfile filePath} | get | delete}

mmafmcoskeys all get --report

Availability

Available on all IBM Storage Scale editions.

Description

This command manages an access key and a secret key to access a bucket on a cloud object storage for data synchronization. This command can set, get, delete, and report the access key and the secret key credentials. The keys that are stored for a bucket by AFM have a unique identity across the cluster. If a bucket name is common across multiple cloud object storage servers, the keys can be set along with the server name.

The keys can either be specified by using the command line or can be provided as an input key file in the format of colon delimiter in each line for akey and skey. A report can be displayed to list all access keys or secret keys that are stored for a bucket. This report has a list of all keys across the cluster.

Parameters

bucket

Identifies a unique bucket on a cloud object storage. AFM will use this bucket as a target for a fileset and it will synchronize data between the bucket and the fileset by using the keys that are provided.

Note:

Ensure that the name of bucket is as per the support of the cloud object storage. You need to check the cloud object storage for bucket names guidelines.
A duplicate combination of a bucket name and a server name is not allowed.

Region

Specifies a geographical region of a bucket. Provide the region if the bucket is hosted on a server in a non-default region. You need not to set a region for a default bucket region.

If region is not specified during the creation of a cloud object storage fileset, AFM tries to access a bucket on a server in the default region.

You must set a region if a bucket is hosted on a server in a non-default region.

Server

If the same bucket exists on multiple cloud object storage, the bucket credentials can be stored by providing the bucket:serverName format. The combination of a bucket name and a server name will uniquely identify the keys of the bucket across the cluster. AFM shows a reject message if you try to store duplicate bucket name.

ExportMap

When the parallel reads operation is used for an AFM to cloud object storage fileset, an export map is created by using the mmafmconfig command. If you are using an ExportMap, then the Server parameter can be avoided to configure parallel data read operations by using the mapped gateways. For more information, see the mmafmconfig command. End of change

set

Stores the bucket credentials, which are an access key and a secrete key, with AFM. AFM stores this credential for communication with a cloud object storage. Wrong credentials are validated only at the time of communication.

Access and secret keys can be provided to AFM either by using command line where you can use a space separated word or by using a key file, which has separate lines for akey:AccessKey and skey:SecretKey.

This command can be used to modify the stored credentials that are used for next communication with a cloud object storage. It is recommended to modify credentials when the communication between AFM and a cloud object storage is stopped.

You must store credentials of a bucket before you create an AFM fileset that has a cloud object storage as a target.

get

Retrieves the stored credentials that were set for the bucket and server combination. AFM shows an error if the bucket and server name combination does not exist.

delete

Deletes the credentials of the bucket and server name combination that is stored with AFM. The delete operation removes entries of access keys and secret keys of the specified bucket. Before you delete the stored credentials of a bucket, you need to ensure that the bucket is not mentioned as a target on any AFM fileset.

akey

Specifies an access key that belongs to a cloud object storage that is used to access the bucket.

An access key can contain special characters such as hyphen (-) or period (.).

skey

Specifies a secret key that belongs to a cloud object storage that is used to access the bucket.

A secret key can contain special characters such as hyphen (-) or period (.).

--keyfile

Specifies a key file that contains an access key and a secret key. Instead of providing the access key and the secret key on the command line, a key file can be used. The key file must contain two lines for akey and skey separated by a colon. An example of the format of a key file /root/keyfile1 is as follows:

akey:AccessKey
skey:SecretKey

--report

This option generates a report of all buckets and server name combinations that are stored with AFM.

Exit status

0: Successful completion.
nonzero: A failure occurred.

Security

You must have root authority to run the mmafmcoskeys command.

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

Examples

To set an access key and a secret key of a bucket, issue the following the command:
```
# mmafmcoskeys bucket1 set AccessKey SecretKey
```
To set an access key and a secret key of a bucket by using a key file, issue the following command:
An example of a key file in the /root/key file is as follows:
```
akey:AccessKey
skey:SecretKey
```
Note: The key file must not have any other characters such as space and tab.
```
# mmafmcoskeys bucket1 set --keyfile /root/keyfile
```
To set an access key and a secret key of a bucket by using the bucket:serverName combination, issue the following command:
```
# mmafmcoskeys bucket1:serverName1 set AccessKey SecretKey
```
To get an access key and a secret key of a bucket, issue the following command:
```
# mmafmcoskeys bucket1 get
```
To get an access key and a secret key of a bucket by using the bucket:serverName combination, issue the following command:
```
# mmafmcoskeys bucket1:serverName1 get
```
To delete an access key and a secret key of a bucket, issue the following command:
```
# mmafmcoskeys bucket1 delete
```
To delete an access key and a secret key of a bucket by using the bucket:serverName combination, issue the following command:
```
# mmafmcoskeys bucket1:serverName1 delete
```
To set an access key and a secret key of a bucket by using a bucket and a server name combination, issue the following command:
```
# mmafmcoskeys bucket2:us-west-2@ServerName2 set AccessKey SecretKey
```
To get an access key and a secret key of a bucket, issue the following command:
```
# mmafmcoskeys bucket2 get
```
To get and an access key and a secret key of a non-default region bucket, issue the following command:
```
# mmafmcoskeys bucket2:us-west-2@ServerName2 get
```
To generate a report of all buckets and their credentials that are stored, issue the following command:
```
# mmafmcoskeys all get --report
```
To set an access key and a secret key for an Amazon S3 bucket that belongs to different region, issue the following command:
```
# mmafmcoskeys bucketname:ap-northeast-1@s3.ap-northeast-1.amazonaws.com set akey skey
```

Location

/usr/lpp/mmfs/bin