DEFINE CONNECTION (Define a cloud connection)

Privilege class

To issue this command, you must have system privilege or unrestricted storage privilege.

Parameters

connection_name (Required)

Specifies the connection to define. This parameter is required. The maximum length of the name is 30 characters.

CLOUDType

Specifies the type of cloud environment for your connection. This parameter is optional. If you do not specify the parameter, the default value, S3, is used.

AZure

Specifies that the connection uses a Microsoft Azure cloud computing system.

GOOGle

Specifies that the connection uses a Google Cloud Storage cloud computing system.

S3

Specifies that the connection uses a cloud computing system with the Simple Storage Service (S3) protocol, such as IBM® Cloud Object Storage or Amazon Web Services (AWS) S3.

Restriction: Swift-based cloud types (SWIFT, V1SWIFT, and IBMCLOUDSWIFT) are deprecated for cloud connections in IBM Spectrum Protect 8.1.13 and later. You cannot specify a Swift-based cloud type for a new connection. However, if you specified a Swift-based cloud type for a cloud-container storage pool in IBM Spectrum Protect 8.1.12 or earlier, the Swift cloud credentials are migrated automatically to the cloud connection for users of IBM Spectrum Protect 8.1.13 or later.

CLOUDUrl

Specifies the URL of the cloud environment connection. If you specified CLOUDTYPE=GOOGLE, do not specify the CLOUDURL parameter. Based on your cloud provider, you can use a blob service endpoint, region endpoint URL, an Accesser® IP address, a public authentication endpoint, or a similar value. Be sure to include the protocol, such as https:// or http://, at the beginning of the URL. The maximum length of the web address is 870 characters.

Tip: For IBM Cloud Object Storage users: To optimize performance, use multiple Accessers. To use more than one IBM Cloud Object Storage Accesser, list the Accesser IP addresses separated by a vertical bar (|), with no spaces, surrounded by quotation marks, as in the following example:

cloudurl="accesser_url1|accesser_url2|accesser_url3"

BUCKETName

If a bucket or vault exists with the name that you specify, that bucket or vault is tested to ensure that the proper permissions are set.

Specifies the name of an AWS S3 or Google Cloud Storage bucket, or an IBM Cloud Object Storage vault to use with this connection. This parameter is required and is valid only if you specify CLOUDTYPE=S3 or CLOUDTYPE=GOOGLE. If you specified CLOUDTYPE=AZURE, do not specify the BUCKETNAME parameter.

If the bucket or vault does not exist, the parameter verifies only that a bucket or vault with that name does not exist. If the command output indicates that the bucket or vault does not exist, work with your cloud service provider to create a bucket or vault with an appropriate name and settings. Permissions are required for reading, writing, listing, and deleting objects. If you cannot change or view the permissions, and data is not yet written to this bucket, use the UPDATE CONNECTION command. In that command, specify the BUCKETNAME parameter to select a bucket or vault in a storage pool that has the required permission.

IDentity

Specifies the user ID for the cloud that is specified in the CLOUDURL parameter. This parameter is required and is valid only if you specify CLOUDTYPE=S3. If you specified CLOUDTYPE=AZURE or CLOUDTYPE=GOOGLE, do not specify the IDENTITY parameter. Based on your cloud provider, you can use an access key ID, a user name, a tenant name and user name, or a similar value. The maximum length of the user ID is 255 characters.

Tip: To specify a tenant name and user name, use the following format:

tenant_name.user_name

PAssword

Specifies the password for the cloud that is specified in the CLOUDURL parameter. If you specified CLOUDTYPE=GOOGLE, do not specify the PASSWORD parameter. Based on your cloud provider, you can use a shared access signature (SAS) token, secret access key, an API key, a password, or a similar value. This parameter is required. The maximum length of the password is 256 characters. The IDENTITY and PASSWORD parameters are not validated until the first backup operation begins.

DESCription

Specifies a description of the connection. The parameter is optional. The maximum length of the description is 255 characters. Enclose the description in quotation marks if it contains blank characters.

KEYLocation

Specifies the name of the file that contains the Google Cloud Storage service account key in JavaScript Object Notation (JSON) format. This parameter is required and is valid only if you specify CLOUDTYPE=GOOGLE. If you specified CLOUDTYPE=AZURE or CLOUDTYPE=S3, do not specify the KEYLOCATION parameter.

The key is uploaded to the database to connect the server to the cloud. The key content is sent to the server only when a DEFINE CONNECTION or UPDATE CONNECTION command is issued.

If the key changes, you must update the connection so that the server can load the new content. To update the key on the server with the key location, issue the UPDATE CONNECTION command and the key will reload. The maximum length of the key location is 256 characters.

Tip: To help ensure that you can restore the database and recover your storage environment after a disaster, save the key file and the path to the key file in a separate and secure location. Avoid moving the key file because the file might be required later to reestablish the connection between IBM Spectrum Protect and the cloud object storage.