CATALOG STORAGE ACCESS command

The CATALOG STORAGE ACCESS command creates an alias for accessing remote storage on IBM® Cloud Object Storage or Amazon Simple Storage Service (S3). The alias can be used on the INGEST,LOAD, BACKUP DATABASE, or RESTORE DATABASE commands, as well as the logarchmeth1 and logarchmeth2 database configuration parameters. When you create a storage access alias, your remote storage account credentials are safely stored in an encrypted keystore.

Note: Storage access aliases and remote storage are supported under Linux only; refer to Remote storage requirements for details.

Authorization

One of the following authorities:

SYSADM
SYSCTRL

Required connection

None

Command syntax

Command parameters

ALIAS alias-name

Specifies the new alias name.

VENDOR ( SOFTLAYER | S3 )

Specifies the type of the remote storage. Valid values include:

SOFTLAYER - for IBM Cloud Object Storage
S3 - for Amazon S3

SERVER ( DEFAULT | endpoint )

Specifies the Authentication Endpoint of the remote storage. Valid values include:

DEFAULT - to use the SoftLayer endpoint in Dallas
endpoint - to use the endpoint you choose

Only private endpoints are supported with the CATALOG STORAGE ACCESS command.

Important: While some old endpoints are still using Open Stack Swift, all new SoftLayer endpoints are using Amazon Web Service (AWS) S3 protocol. Only VENDOR S3 option should be used for cataloging access to the new SoftLayer endpoints.

USER storage-user-ID

Specifies the SoftLayer Username or S3 Access Key ID of the remote storage account.

PASSWORD storage-password

Specifies the SoftLayer API key or S3 Secret Access Key of the remote storage account credentials.

CONTAINER container-or-bucket

[Optional] Specifies a SoftLayer container or an S3 bucket.

OBJECT object

[Optional] Specifies the name of the object (file) on the remote storage.

If you specify a file name with the OBJECT parameter when you issue the CATALOG STORAGE ALIAS command, then you don't need to specify the file name with the DB2REMOTE identifier when you use the alias in the BACKUP, RESTORE, LOAD, or INGEST command.

DBGROUP group-ID

[Optional] Specifies the user group that may access the alias. For more information about users and groups see: Db2® users and groups

If neither DBUSER nor DBGROUP is specified, only users with SYSADM authority may use the alias.

DBUSER user-ID

[Optional] Specifies the user ID that may access the alias.

If neither DBUSER nor DBGROUP is specified, only users with SYSADM authority may use the alias.

Example

Create an alias called "coss3us" for a bucket "ibmusr1.ibmcoss3us" in the US East region:


CATALOG STORAGE ACCESS ALIAS coss3us VENDOR S3 
SERVER a4b.us-east-1.amazonaws.com
USER <Access Key ID> PASSWORD <Secret Access Key ID>
CONTAINER ibmusr1.ibmcoss3us;

Using the alias created above and the following remote storage format:

DB2REMOTE://<alias>/<container>/<object>

A backup to the database can be created in one of the following ways:

backup db testdb to DB2REMOTE://coss3us//bkupDir11/1453245697

backup db testdb to DB2REMOTE://coss3us/container1/bkupDir11/1453245697

Usage notes

Keystore required

When you issue the CATALOG STORAGE ACCESS command, remote storage account credentials are stored in a keystore:

If the Db2 instance is already configured to store master keys in a keystore for Db2 native encryption, then the same keystore will be used to store the remote storage account credentials.
If the instance is not configured for Db2 native encryption, then you must create a keystore for the remote storage account credentials before you can create storage access aliases:
1. Create a local keystore
2. Configure the Db2 instance to use the keystore

Looking up remote storage details

You can look up the SoftLayer account credentials and Authentication Endpoint by logging in to the SoftLayer Customer Portal, selecting "Object Storage" from the Storage drop-down menu, navigating to the container in the Object Storage page, and then clicking the "View Credentials" link.
You can look up Amazon S3 Account Key IDs by logging in to the AWS Management Console, selecting "S3", selecting the "IAM" option in the "Security & Identity" section of the "Security" drop-down menu, selecting "Users" from the navigation menu, and then clicking on the "Security Credentials" tab. However, although Secret Access Key information is available when you create a new user, you cannot retrieve Secret Access Keys for an existing user. For more information see: Managing Access Keys for IAM Users.
You can look up the endpoint for an S3 bucket by logging in to the AWS Management Console, selecting "S3", selecting the bucket, clicking on the "Properties" button to see the Region, and then looking up that Region in the following "Amazon Simple Storage Service (Amazon S3)" table on this web page: AWS Regions and Endpoints.

Managing storage access aliases

You can manage storage access aliases by using some related commands:

List storage access aliases that you can use:
```
list storage access
```
When members with SYSADM authority issue this command, they can see all storage access aliases even though they can only use storage access aliases created for their group or user ID.

Remove a storage access alias:


uncatalog storage access alias <alias>

Rotate the master key in the keystore:
```
rotate master key for storage access
```