Command Line Reference

4 Command Line Reference

Topics

Authentication

To authenticate the access to your account on Oracle Cloud Infrastructure Object Storage Classic, you must provide suitable values for the following parameters:

REST Endpoint URL
User name
Password
Authentication URL (Deprecated from FTM CLI 2.4)
Service name (Deprecated from FTM CLI 2.4)
Identity domain (Deprecated from FTM CLI 2.4)

Note:

It’s recommended that you use the REST Endpoint URL parameter to obtain authentication to access your storage account and not the deprecated parameters such as authentication URL, service name, and identity domain.

This table describes the methods that you can use to specify the authentication parameters.

Method Description Priority

Method	Description	Priority
CLI Parameters	In this method, you can pass the values of the authentication parameters on the command line along with the respective command option. See CLI Command Options. You must pass the parameters with every command issued on the CLI. For the exact syntax of the CLI commands, see General Syntax of FTM CLI Commands. Important: If you don’t want to enter the password for every command you run, you can use the `--save-auth-key` command option to encrypt the password that you enter, and save the encrypted password locally in the `ftmcliKeystore` file. The next time you run any command, the FTM CLI decrypts the previously stored password and uses it. You’re not prompted to enter the password.	Highest
Environment Variables	You can set the authentication parameters by defining the environment variables with their respective values once during the current session. See Setting Up the Required Environment Variables. You must set the environment variables again in each new session.	Second
Configuration File	You can set up multiple configuration files with combinations of CLI parameters and authentication parameters; for example, one per Oracle Cloud Infrastructure Object Storage Classic instance or with different CLI parameters. See Setting Up Configuration Files. It’s a good practice to set up the configuration file to simplify the script for the command line. Important: You must use the `--properties-file` command option to point to the configuration file in any of the following scenarios: If the configuration file is in a different directory than the FTM CLI client If the configuration file has a name other than `ftmcli.properties`	Least

CLI Parameters

In this method, you can pass the values of the authentication parameters on the command line along with the respective command option. See CLI Command Options.

You must pass the parameters with every command issued on the CLI. For the exact syntax of the CLI commands, see General Syntax of FTM CLI Commands.

Important:

If you don’t want to enter the password for every command you run, you can use the --save-auth-key command option to encrypt the password that you enter, and save the encrypted password locally in the ftmcliKeystore file. The next time you run any command, the FTM CLI decrypts the previously stored password and uses it. You’re not prompted to enter the password.

Highest

Environment Variables

You can set the authentication parameters by defining the environment variables with their respective values once during the current session. See Setting Up the Required Environment Variables.

You must set the environment variables again in each new session.

Second

Configuration File

You can set up multiple configuration files with combinations of CLI parameters and authentication parameters; for example, one per Oracle Cloud Infrastructure Object Storage Classic instance or with different CLI parameters. See Setting Up Configuration Files.

It’s a good practice to set up the configuration file to simplify the script for the command line.

Important:

You must use the --properties-file command option to point to the configuration file in any of the following scenarios:

If the configuration file is in a different directory than the FTM CLI client
If the configuration file has a name other than ftmcli.properties

Least

Note:

Depending on your requirements, use any combination of the prior methods to set each authentication parameter.

The priority decides the value of the parameter that will be picked up by the FTM CLI client to authenticate the access to your storage account. Therefore, the values of parameters declared on the command line have the highest priority, followed by the values set in the environment variables. The values set in the configuration file get the least priority, but do get picked up by the FTM CLI client if the environment variables haven't been set for the session or the authentication parameters haven't been set on the command line.

Managing the Account

Learn how to manage your account in Oracle Cloud Infrastructure Object Storage Classic using the FTM CLI.

Operations:

Getting Account Metadata

Retrieves metadata of your account in Oracle Cloud Infrastructure Object Storage Classic.

You can retrieve the following information about your account:

Replication policy (X-Account-Meta-Policy-Georeplication) (Georeplication support not available on Oracle Cloud at Customer)
Support for archive containers (X-Account-Meta-Policy-Archive) (Not available on Oracle Cloud at Customer)
Account quota, in bytes (X-Account-Meta-Quota-Bytes)
Total number of objects created in all the containers in the account (X-Account-Object-Count)
Number of containers in the account (X-Account-Container-Count)
Storage space used, in bytes (X-Account-Bytes-Used)
Custom account metadata (X-Account-Meta-Name)

Required Role: Any user within the identity domain can perform this task.

Syntax

java -jar ftmcli.jar describe [optional arguments]

Optional Arguments

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `describe` command along with the optional arguments and usage.
`--replication-policies`	Lists all the replication policies available in the data region of your storage service instance.

When you run a command, you can either pass the authentication parameters with the command, or let the CLI pick up the required parameters from environment variables or the configuration file. See Authentication.

Example (Archive, georeplication, and S3 API support not available on Oracle Cloud at Customer)

To retrieve the metadata of your account:

java -jar ftmcli.jar describe

The following is an example of the output of this command:

                 Name: myservice-bar
      Container Count: 40
         Object Count: 16707
           Bytes Used: 256496723604
          Bytes Quota: -1
       Archive Policy: arch-amsterdam
Georeplication Policy: em2-em3

Custom Metadata
---------------
x-account-meta-temp-url-key: Welcome1*
x-account-meta-s3-secretkey-2: sectret2key!
x-account-meta-s3-secretkey: sectret1key!

Setting Account Metadata

Sets custom metadata for your account in Oracle Cloud Infrastructure Object Storage Classic.

Custom metadata are arbitrary key-value pairs associated with an account. You may create any custom or arbitrary metadata you need.

Required Role: To complete this task, you must have the Storage_Administrator role. If one of these roles isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar set [optional arguments]

Optional Arguments

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `set` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-C` `custom_metadata_name:custom_metadata_value`, `--custom-metadata` `custom_metadata_name:custom_metadata_value`	Sets or updates the custom metadata for the account. You can repeat the use of this option multiple times in a command to set or update multiple custom metadata headers. FTM CLI adds a prefix `X-Account-Meta-` to the custom metadata name.
`-M` `metadata_name:metadata_value`, `--metadata` `metadata_name:metadata_value`	Sets or updates the account metadata. You can repeat the use of this option multiple times in a command to set or update multiple metadata headers. In case the georeplication policy for the account is not set, you can set it using this option.

Note:

For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.

Examples

To set a new custom metadata X-Account-Meta-CoreTest with the value Welcome123:
```
java -jar ftmcli.jar set -C CoreTest:Welcome123
```
To update the existing custom metadata X-Account-Meta-HR-Key with a new value NewKey123:
```
java -jar ftmcli.jar set -C HR-Key:NewKey123
```
To set the georeplication policy for the account with a value us2–us6, where us2 is the primary DC and us6 is the replication DC:
```
java -jar ftmcli.jar set -M X-Account-Meta-Policy-Georeplication:us2-us6
```

Managing Containers

Learn how to manage your containers in Oracle Cloud Infrastructure Object Storage Classic using the FTM CLI.

Operations:

Listing Containers

Lists the containers in Oracle Cloud Infrastructure Object Storage Classic.

Required Role: To complete this task, you must have the Storage_ReadGroup or Storage_ReadWriteGroup or Storage_Administrator role. If one of these roles isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar list [optional arguments]

Optional Arguments

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `list` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-X` `prefix`, `--prefix` `prefix`	Lists the container names that have the specified prefix.
`-D` `delimiter`, `--delimiter` `delimiter`	Lists the containers with names that don’t include the specified character. When FTM CLI encounters a container name that includes the specified character, it returns only the substring of the container name before the specified character. Only unique substrings are returned.
`-M` `marker`, `--marker` `marker`	Lists the containers with names greater than the specified string.
`-E` `end_marker`, `--end-marker` `end_marker`	Lists the containers with names less than the specified string.
`-L` `limit`, `--limit` `limit`	Limits the number of container names listed to the specified value. Default and maximum value: 10000.
`-a`, `--all`	Lists all the container names even if the storage service has to run multiple queries to get more than 10000 containers.

Examples

To list all the containers:

java -jar ftmcli.jar list

Command Output:

Testcontainer
compute_images
compute_images_segments
TestCLI

To specify that the request must be retried 3 times in case of failure:
```
java -jar ftmcli.jar list -R 3
```
To list the container names that have the prefix Test:
```
java -jar ftmcli.jar list -X Test
```
Command Output:
```
Testcontainer
TestCLI
```

To specify the delimiter n:

java -jar ftmcli.jar list -D n

Command Output:

Testcontain
compute_images
compute_images_segmen
TestCLI

If a generic listing query for an account generated the following output:
```
app_serve1
auto_blocks
bandwidth_data
core_FS_backup
device_profile
filesystem_test
testContainer
```
- To list the containers from the above output starting from the container that has the string core as the first part of its name:
```
java -jar ftmcli.jar list -M core
```
  Command output:
```
core_FS_backup
device_profile
filesystem_test
testContainer
```
- To list all the containers till the container that has the string file as the first part of its name:
```
java -jar ftmcli.jar list -E file
```
  Command output:
```
app_serve1
auto_blocks
bandwidth_data
core_FS_backup
device_profile
```
- To list the first 3 container names:
```
java -jar ftmcli.jar list -L 3
```
  Command output:
```
app_serve1
auto_blocks
bandwidth_data
```

Creating a Container

Creates a container in Oracle Cloud Infrastructure Object Storage Classic, and sets the metadata and container-level replication policy for the container.

Required Role: To complete this task, you must have the Storage_ReadWriteGroup or Storage_Administrator role. If one of these roles isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar create-container container [optional arguments]

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container that you’re creating

The following optional arguments are specific to this command:

Argument	Description
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-a`, `--archive`	Sets the storage class of the container to `Archive`. (Archive support not available on Oracle Cloud at Customer)
`-e`, `--server-side-encryption`	Enables server-side encryption for the container by setting the policy to `BASE_ENCRYPTION`. You can enable server-side encryption for a container only at the time of creating it, not later.
`-M` `metadata_name:metadata_value`, `--metadata` `metadata_name:metadata_value`	Sets the container metadata. You can repeat the use of this option multiple times in a command to set or update multiple metadata headers. You can set the container ACLs and quotas using this option.
`-C` `custom_metadata_name:custom_metadata_value`, `--custom-metadata` `custom_metadata_name:custom_metadata_value`	Sets the custom metadata for the container. You can repeat the use of this option multiple times in a command to set or update multiple custom metadata headers. FTM CLI adds a prefix `X-Container-Meta-` to the custom metadata name. You can set the custom metadata headers and CORS headers using this option.
`--source-region` `source_region`	Indicates the primary DC code of your container.
`--target-region` `target_region`	Indicates the replication DC code of the container in the same region. You can repeat the use of this argument multiple times in a command to set multiple replication DCs.
`--ext-source-region-url` `external_target_region_url`	Indicates the URL of the container in an external region from which the objects would be replicated into your container. You can repeat the use of this argument multiple times in a command to set multiple external source DCs.
`--ext-target-region-url` `external_target_region_url`	Indicates the URL of the container in an external region into which the objects in your container must be replicated. You can repeat the use of this argument multiple times in a command to set multiple external target DCs.

Examples

To create the container myTestArchiveContainer of the Archive storage class:
```
java -jar ftmcli.jar create-container myTestArchiveContainer --archive
```

To create the container myTestContainer, and enable server-side encryption:

java -jar ftmcli.jar create-container myTestContainer --server-side-encryption

For the example values of metadata to include the --metadata and --custom-metadata arguments in the command, see Setting Container Metadata.
For the example values to set the container-level replication policy, see Setting a Container-Specific Replication Policy.

Deleting a Container

Deletes the specified container in Oracle Cloud Infrastructure Object Storage Classic.

Required Role: To complete this task, you must have the Storage_Administrator role. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar delete [optional arguments] container

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container that must be deleted.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `delete` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-f`, `--force`	Deletes a container and all its contents.

Examples

To delete the container TestCLI and to specify that the request must be retried 6 times in case of failure:
```
java -jar ftmcli.jar delete -R 6 TestCLI
```
Command Output:
```
Container successfully deleted: TestCLI
```
To delete the container TestCLI and all the objects in it:
```
java -jar ftmcli.jar delete -f TestCLI
```

Getting Container Metadata

Retrieves metadata of the specified container in Oracle Cloud Infrastructure Object Storage Classic.

You can retrieve the following information about your container:

Number of objects in the container (X-Container-Object-Count)
Storage space used by all objects in the container, in bytes (X-Container-Bytes-Used)
Storage class of the container (X-Storage-Class)
Date of creation of the container
Date when the container was last modified
Server-side encryption for the container, if enabled (X-Server-Side-Encryption)
Custom metadata (X-Container-Meta-Name)
Container replication policy details

Syntax

java -jar ftmcli.jar describe [optional arguments] container

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container whose metadata must be retrieved.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `describe` command along with the optional arguments and usage.
`--crp`	Provides the container replication details for the container.

Examples

To retrieve the metadata of the container testStandardContainer that belongs to the standard storage class:

java -jar ftmcli.jar describe testStandardContainer

The following is an example of the output of this command:

                  Name: testStandardContainer
          Object Count: 40
            Bytes Used: 85880410
         Storage Class: Standard
         Creation Date: Thu Mar 16 12:52:59 IST 2017
         Last Modified: Thu Mar 16 20:46:07 IST 2017
Server Side Encryption: BASE_ENCRYPTION

Custom Metadata
---------------
x-container-meta-filesyncpeerversion: 2
x-container-meta-lastlegacybackupversion: 1
x-container-meta-access-control-allow-origin: http://acme-admin.example.com

To retrieve the metadata of the container testArchiveContainer that belongs to the archive storage class (Archive support not available on Oracle Cloud at Customer):

java -jar ftmcli.jar describe testArchiveContainer

The following is an example of the output of this command:

                 Name: testArchiveContainer
         Object Count: 2
           Bytes Used: 165540
        Storage Class: Archive
        Creation Date: Tue Sep 27 14:11:13 IST 2016
        Last Modified: Tue Sep 27 14:11:13 IST 2016

For the example to retrieve the container replication details, see Setting a Container-Specific Replication Policy.

Setting Container Metadata

Sets the metadata for the specified container in Oracle Cloud Infrastructure Object Storage Classic.

You can set or update the following metadata for the container:

Container ACLs: The ability to read and write objects in a container is governed by the Access Control Lists (ACLs) assigned to the container. A container has two ACLs, X-Container-Read and X-Container-Write.
Container Quotas: For each container, you can set quotas for the maximum number of bytes the container can contain (X-Container-Meta-Quota-Bytes) and the maximum number of objects the container can contain (X-Container-Meta-Quota-Count).
Custom Metadata for the Container: Custom metadata are arbitrary key-value pairs associated with a container. You may create any custom or arbitrary metadata you need.
CORS Metadata for the Container: Cross-Origin Resource Sharing (CORS) allows browser-based programs (like JavaScript) to access resources in another domain. This enables web applications to access Oracle Cloud Infrastructure Object Storage Classic, overcoming the Same-Origin policy that’s used by browsers to prevent access to resources in other domains. A container has three CORS metadata headers, X-Container-Meta-Access-Control-Allow-Origin, X-Container-Meta-Access-Control-Max-Age, and X-Container-Meta-Access-Control-Expose-Headers.

For example values to set the metadata, see Setting Container Metadata in Using Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar set [optional arguments] container

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container whose metadata must be set.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `set` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-M` `metadata_name:metadata_value`, `--metadata` `metadata_name:metadata_value`	Sets or updates the container metadata. You can repeat the use of this option multiple times in a command to set or update multiple metadata headers. You can set the container ACLs and quotas using this option.
`-C` `custom_metadata_name:custom_metadata_value`, `--custom-metadata` `custom_metadata_name:custom_metadata_value`	Sets or updates the custom metadata for the container. You can repeat the use of this option multiple times in a command to set or update multiple custom metadata headers. FTM CLI adds a prefix `X-Container-Meta-` to the custom metadata name. You can set the custom metadata headers and CORS headers using this option.

Note:

For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.

Examples

To update the container metadata X-Container-Write with the value myIdentity3.myservice.Storage_ReadWriteGroup for the container testContainer:
```
java -jar ftmcli.jar set -M X-Container-Write:myIdentity3.myservice.Storage_ReadWriteGroup testContainer
```
To set the custom metadata X-Container-Meta-BackupVersion with a value 2 for the container testContainer:
```
java -jar ftmcli.jar set -C BackupVersion:2 testContainer
```

To set or update multiple metadata with the corresponding values in a single command for the container testContainer:

java -jar ftmcli.jar set -M X-Container-Read:myIdentity3.myservice.Storage_ReadGroup -M X-Container-Meta-Quota-Count:100 -C Access-Control-Allow-Origin:http://acme-admin.example.com/ -C Access-Control-Max-Age:10000 testContainer

Setting a Container-Specific Replication Policy

This topic does not apply to Oracle Cloud at Customer.

You can specify a different replication policy for each container than the policy that's defined for your service instance. The container-level policy overrides the policy that’s set for the service instance. This enables you to control, at a more granular level, what data gets replicated to a geographical distant data center (DC).

Required Role: To complete this task, you must have the Storage_Administrator. If this role isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Important:

You can set a container-level georeplication policy for only containers of the Standard storage class.
The container-specific replication policy can be set only at the time of creation of the container or when the container is empty.

Setting the Replication in a Data Center Within the Same Region

You can set your container’s primary DC and georeplication DC to be a subset of that of the service instance. For example, if the primary DC of your service instance is us2 and the georeplication DCs are us6 and uscom-central-1, then the primary DC of your container can be us6, us2, or uscom-central-1. One or both of the remaining DCs can be selected as the replication DC of the container.

To select a replication policy for your service instance or for the list of available data centers and the corresponding codes, first determine the account-level replication policy and the current replication policy of your container using the describe command. See Getting Account Metadata and Getting Container Metadata.

Setting the Replication in a Different Region

You can specify a replication policy for your container by selecting a data center outside the region where the primary DC and georeplication DC of your service instance are located. For example, if the primary DC and georeplication DC of your service instance are us2 and us6 in the US region, then you can select a data center, say em2 that’s located in a non-US region to replicate your container. Specify the external container to which the objects from your container must be replicated by specifying the external container’s URL with the --ext-target-region-url argument in the command. You can specify multiple external replication DCs for your container.

When your container is the destination for the replication of objects from an external container, specify the external container’s URL with the --ext-source-region-url argument in the command. Your container can be the destination for replication of objects from multiple source containers.

Note:

While setting the container’s replication policy in a different region, first set the replication policy of the target region with the --ext-source-region-url argument, and next set the replication of the source region with the --ext-target-region-url argument.

Important:

To set the container’s replication policy in a different region, ensure that the REST endpoint URLs specified in the command are in the GUID format (for example,

https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer

). Do not use the friendly name format (for example, https://acme.storage.oraclecloud.com/v1/Storage-acme/myContainer). The friendly name REST endpoint URLs may change and lead to invalid replication policy.

Syntax

java -jar ftmcli.jar set-crp [optional arguments] container --source-region source_region

Arguments

The following mandatory arguments are specific to set the container-level replication policy using the set-crp command:

Argument	Description
`--source-region` `source_region`	Indicates the primary DC code of your container.

The following optional arguments are specific to set the container-level replication policy using the set-crp command:

Argument	Description
`--target-region` `target_region`	Indicates the replication DC code of the container in the same region. You can repeat the use of this argument multiple times in a command to set multiple replication DCs.
`--ext-source-region-url` `external_target_region_url`	Indicates the URL of the container in an external region from which the objects would be replicated into your container. You can repeat the use of this argument multiple times in a command to set multiple external source DCs.
`--ext-target-region-url` `external_target_region_url`	Indicates the URL of the container in an external region into which the objects in your container must be replicated. You can repeat the use of this argument multiple times in a command to set multiple external target DCs.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.

Examples

To read the replication policy of your service instance:

java -jar ftmcli.jar describe

An example output of the command is:

                 Name: Storage-abc123
      Container Count: 4
         Object Count: 3
           Bytes Used: 359
          Bytes Quota: 1099511627776
       Archive Policy: us2
Georeplication Policy: us2-us6

Custom Metadata
---------------
x-account-meta-owner: jack.jones@example.com

To read the replication policy of your container:

java -jar ftmcli.jar describe testContainer --crp

An example output of the command is:

                  Name: testContainer
          Object Count: 0
            Bytes Used: 0
         Storage Class: Standard
         Creation Date: Mon Jan 15 12:56:16 IST 2018
         Last Modified: Mon Jan 15 12:56:15 IST 2018

Custom Metadata
---------------
x-container-meta-policy-georeplication: container

Container Replication Policy
------------------------------
                   Mode:ACTIVE_PASSIVE
          Source Region:
                        name: us2
                        url: https://us2.storage.oraclecloud.com/v1/Storage-acme/testContainer
         Target Regions:[
                        {name: us6
                        url: https://us6.storage.oraclecloud.com/v1/Storage-acme/testContainer},]
External Target Regions:[ ]
         Target Regions:[ ]

To change the container-level replication policy for the container testContainer in the same data region, where:

Your service instance has us2 primary DC.
Your service instance has us6 replication DC.
Primary DC for your container is us2.
Replication DC for your container is us6 .
Primary DC for your container must be changed to us6.
Replication DC for your container must be changed to us2 .

java -jar ftmcli.jar set testContainer --source-region us6 --target-region us2

To change the container-level replication policy for the container testContainer2 in a different data region, where:

Your service instance has us2 primary DC.
Source DC URL for your container in a different data region must be set to https://<foo1>.storage.oraclecloud.com/v1/Storage-<bar1>/externalSourceContainer1 and https://<foo2>.storage.oraclecloud.com/v1/Storage-<bar2>/externalSourceContainer2.
Target DC URL for your container in a different data region must be set to https://<foo3>.storage.oraclecloud.com/v1/Storage-<bar3>/externalTargetContainer.

Note:

The example demonstrates the use of GUID-based URLs to set the source and target regions. If the GUID-based URL for the container is

https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365/myContainer

, then <fooN> is storage-7b16fede61e1417ab83eb52e06f0e365 and <barN> is 7b16fede61e1417ab83eb52e06f0e365.

java -jar ftmcli.jar set testContainer2 \
--source-region us2 \
--ext-source-region-url https://<foo1>.storage.oraclecloud.com/v1/Storage-<bar1>/externalSourceContainer1 \
--ext-source-region-url https://<foo2>.storage.oraclecloud.com/v1/Storage-<bar2>/externalSourceContainer2 \
--ext-target-region-url https://<foo3>.storage.oraclecloud.com/v1/Storage-<bar3>/externalTargetContainer

Managing Objects

Learn how to manage objects in your containers in Oracle Cloud Infrastructure Object Storage Classic.

Operations:

Listing Objects

Lists the objects in the specified container in Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar list [optional arguments] container

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container in which the objects are located.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `list` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-X` `prefix`, `--prefix` `prefix`	Lists the object names that have the specified prefix.
`-D` `delimiter`, `--delimiter` `delimiter`	Lists the objects with names that don’t include the specified character. When FTM CLI encounters an object name that includes the specified character, it returns only the substring of the object name before the specified character. Only unique substrings are returned.
`-M` `marker`, `--marker` `marker`	Lists the objects with names greater than the specified string.
`-E` `end_marker`, `--end-marker` `end_marker`	Lists the objects with names less than the specified string.
`-L` `limit`, `--limit` `limit`	Limits the number of object names listed to the specified value. Default and maximum value: 10000.
`-a`, `--all`	Lists all the object names even if the storage service has to run multiple queries to get more than 10000 objects.

Examples

To list all the objects in the container Testcontainer:

java -jar ftmcli.jar list Testcontainer

Command Output:

Sample_script_v1.0
Sample_script_V1.3
Scripting_algorithm_v1.0
Scripting_algorithm_v1.3

To specify that the request must be retried 3 times in case of failure:
```
java -jar ftmcli.jar list -R 3 Testcontainer
```
To list the objects in the container Testcontainer with the names that have the prefix Scripting:
```
java -jar ftmcli.jar list -X Scripting Testcontainer
```
Command Output:
```
Scripting_algorithm_v1.0
Scripting_algorithm_v1.3
```

To specify the delimiter v:

java -jar ftmcli.jar list -D v Testcontainer

Command Output:

Sample_script_v
Sample_script_V1.3
Scripting_algorithm_v1

If a generic listing query for a container testCLI generated the following output:
```
analog_io
compare_analytics
debug_data
filesystem_log
performance_tracking
transfer_rate_log
```
- To list the objects from the above output starting from the object that has the string debug as the first part of its name:
```
java -jar ftmcli.jar list -M debug testCLI
```
  Command output:
```
debug_data
filesystem_log
performance_tracking
transfer_rate_log
```
- To list all the objects till the object that has the string perf as the first part of its name:
```
java -jar ftmcli.jar list -E perf testCLI
```
  Command output:
```
analog_io
compare_analytics
debug_data
filesystem_log
```
- To list the first 4 object names in the container testCLI:
```
java -jar ftmcli.jar list -L 4 testCLI
```
  Command output:
```
analog_io
compare_analytics
debug_data
filesystem_log
```

Uploading Files

Uploads files to the specified container in Oracle Cloud Infrastructure Object Storage Classic.

When you upload a file, if it's larger than the specified segment size, the CLI divides the file into segments and then uploads all the segments along with a manifest object. The manifest object enables the proper concatenation of the segments when you download the large object.

Required Role: To complete this task, you must have the Storage_Administrator or Storage_ReadWriteGroup role. If one of these roles isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar upload [optional arguments] container filepath

For the syntax, arguments, and examples to bulk upload the files, see Creating Multiple Objects.

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container to which the object must be uploaded. If the specified container doesn't exist, then it’s created by the CLI.
`filepath`	The path of the file or directory that must be uploaded.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `upload` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-N` `object name`, `--object-name` `object_name`	Indicates the name by which the object must be saved in the container.
`-T` `threads`, `--max-threads` `threads`	Indicates the maximum number of threads to be used in the upload request. Depending on the speed and quality of the network, the CLI client may perform better with a different number of threads. The default number is 15. Choose any number between 1 and 100. You can set the default value in the configuration file by updating the value of the variable `max-threads`. See Setting Up Configuration Files.
`-G` `size`, `--segment-size` `size`	Indicates the segment size in MB. You can set the default value in the configuration file by updating the value of the variable `segment-size`. See Setting Up Configuration Files.
`-C` `segments_container`, `--segments-container` `segments_container`	Indicates the container in which the segments must be stored. You can set the default value in the configuration file by updating the value of the variable `segments-container`. See Setting Up Configuration Files.
`-s` , `--skip`	Skips uploading a file if an object with the same name exists in the destination container. If you don’t specify this option, the object with the same name in the container will be overwritten with the file being uploaded.
`-a` , `--archive`	Indicates that the object must be archived in the specified `Archive` container. Use this option when you want to differentiate between the upload of standard and archive objects. You can set the default storage class in the configuration file by updating the value of the variable `storage-class`. See Setting Up Configuration Files. (Not available on Oracle Cloud at Customer)
`-e` , `--server-side-encryption`	Indicates that the file must be uploaded to a container that has server-side encryption enabled. If the container referenced in the command doesn’t exist, then the container is created with the server-side encryption feature enabled, and the file then uploaded.
`-K` `key_filepath`, `--encryption-key` `key_filepath`	Indicates the master key file that must be used for client-side file encryption. See Generating the Master Key. Note: Use the same master key file to decrypt the object when you download it from cloud storage.

Note:

For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.

Note:

When you upload a directory consisting of multiple files, the objects created on the container will have the full path and name of the directory as the prefix in their file names.

Examples

Note:

The examples shown here are for running the CLI from an Oracle Linux host. When running the CLI on Windows, use \ as the directory separators.

To upload the file /home/jack/FTM_CLI/StandardObject to the container TestCLI and store it with the name StandardObject_1:
```
java -jar ftmcli.jar upload -N StandardObject_1 TestCLI /home/jack/FTM_CLI/StandardObject
```

To upload all the files from the directory /home/jack/FTM_CLI/MultipleObjects to the container TestCLI:

java -jar ftmcli.jar upload TestCLI /home/jack/FTM_CLI/MultipleObjects

The following is the example of the output of this command:

Uploading directory: /home/jack/FTM_CLI/MultipleObjects to container: TestCLI
File uploaded: myFile1.txt
File uploaded: myFile2.txt
File uploaded: myFile3.txt
File uploaded: myFile4.txt
File uploaded: myFile5.txt
File(s) attempted: 5
File(s) succeeded: 5
File(s) skipped: 0
See Log for details
File(s) failed: 0
See Log for details
Estimated Transfer Rate: -- KB/s

The files uploaded to the container TestCLI are stored with the string /home/jack/FTM_CLI/MultipleObjects prefixed to their names. Example, /home/jack/FTM_CLI/MultipleObjects/myFile1.txt.

To upload the file /home/jack/FTM_CLI/StandardObject to the container TestCLI and set the maximum threads to 10:
```
java -jar ftmcli.jar upload -T 10 TestCLI /home/jack/FTM_CLI/StandardObject
```
To upload a 10-MB file /home/jack/FTM_CLI/StandardObject to the container TestCLI in 10 segments of size 1 MB each, and to store the segments in the segments container TestCLI_segments:
```
java -jar ftmcli.jar upload -G 1 -C TestCLI_segments TestCLI /home/jack/FTM_CLI/StandardObject
```
To upload the file /home/jack/FTM_CLI/StandardObject to the container TestCLI but skip the upload if an object with the same name already exists in the container:
```
java -jar ftmcli.jar upload -R 3 -s TestCLI StandardObject
```
To archive the file /home/jack/FTM_CLI/ArchiveObject to the Archive container TestCLI_Archive (Not available on Oracle Cloud at Customer):
```
java -jar ftmcli.jar upload -a TestCLI_Archive /home/jack/FTM_CLI/ArchiveObject
```
To upload a file /home/jack/FTM_CLI/StandardObject to a server-side encryption enabled container SSE_TestCLI:
```
java -jar ftmcli.jar upload -e SSE_TestCLI /home/jack/FTM_CLI/StandardObject
```
To encrypt a file /home/jack/FTM_CLI/StandardObject on the client side using the master key file /home/jack/Encryption_Key.pem, and then upload it to a container TestCLI:
```
java -jar ftmcli.jar upload -K /home/jack/Encryption_Key.pem TestCLI /home/jack/FTM_CLI/StandardObject
```

Copying an Object

Copies the object from the source container to the target container in Oracle Cloud Infrastructure Object Storage Classic.

Archived objects (Not available on Oracle Cloud at Customer): To copy an object from a container of the Archive storage class, restore it first. A copy operation can be performed only when the source object is in the restored state. The target container can be of any storage class, Standard or Archive. See Restoring an Object.

Large Objects: You can perform a copy operation on a static large object but not a dynamic large object.

Syntax

java -jar ftmcli.jar copy [optional arguments] source_container source_object --target-container target_container

Parameters and Arguments

The following parameters are specific to this command:

Parameter	Description
`source_container`	The name of the container from which the object must be copied.
`source_object`	The object that must be copied.

The following argument is specific to this command:

Argument	Description
`--target-container` `target_container`	The name of the target container to which the object must be copied.

The following optional arguments are specific to this command:

Argument	Description
`--target-object` `target_object_name`	Indicates the name by which the object must be stored on the target container after copy.
`-M` `metadata_name:metadata_value`, `--metadata` `metadata_name:metadata_value`	Sets or updates the container metadata. You can repeat the use of this option multiple times in a command to set or update multiple metadata headers. You can set the container ACLs and quotas using this option.
`-C` `custom_metadata_name:custom_metadata_value`, `--custom-metadata` `custom_metadata_name:custom_metadata_value`	Sets or updates the custom metadata for the container. You can repeat the use of this option multiple times in a command to set or update multiple custom metadata headers. FTM CLI adds a prefix `X-Container-Meta-` to the custom metadata name. You can set the custom metadata headers and CORS headers using this option.
`-R`, `--retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-T` `threads`, `--max-threads` `threads`	The maximum number of threads to be used in the download request. Depending on the speed and quality of the network, the CLI client may perform better with a different number of threads. The default number is 15. Any number between 1 and 100 is a valid entry. You can set the default value in the configuration file by updating the value of the variable `max-threads`. See Setting Up Configuration Files.
`--fresh-metadata`	Copy the object without any existing metadata. If you don’t specify this option, FTM CLI copies the object by preserving it’s existing metadata.
`--target-segments-container` `target_segments_container_name`	Indicates the container in which the segments must be stored after copy to the target container. If you don’t specify the name of the target segments container, then the segments are stored in the default segments container `target_container_segments`.

Examples

To copy the large object LargeObject from the container SourceContainer1 to the target container TargetContainer1 and specify the target segments container Common_Segments:
```
java -jar ftmcli.jar copy SourceContainer1 LargeObject --target-container TargetContainer1 --target-segments-container Common_Segments
```
To copy the object StandardObject1 from the container SourceContainer1 to the target container TargetContainer1 and store the object by the name StandardObject2:
```
java -jar ftmcli.jar copy SourceContainer1 StandardObject1 --target-container TargetContainer1 --target-object StandardObject2
```
To copy the object StandardObject from the container SourceContainer1 to the target container TargetContainer1 without any existing metadata:
```
java -jar ftmcli.jar copy SourceContainer1 StandardObject --target-container TargetContainer1 --fresh-metadata
```
To copy the object StandardObject from the container SourceContainer1 to the target container TargetContainer1 without any existing metadata, and then create new custom metadata:
```
java -jar ftmcli.jar copy SourceContainer1 StandardObject --target-container TargetContainer1 --fresh-metadata -C org:b99
```

Downloading an Object

Downloads the object from the specified container in Oracle Cloud Infrastructure Object Storage Classic.

Required Role: To complete this task, you must have the Storage_Administrator, Storage_ReadWriteGroup or Storage_ReadGroup role. If one of these roles isn’t assigned to you or you’re not sure, then ask your system administrator to ensure that the role is assigned to you in Oracle Cloud Infrastructure Classic Console. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Syntax

java -jar ftmcli.jar download [optional arguments] container object

For the syntax, arguments, and examples to bulk download the objects, see Downloading Multiple Objects.

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container from which the object must be downloaded.
`object`	The object that must be downloaded. In case of directory download, this is the prefix in the names of the objects that must be downloaded together.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `download` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-O` `file name`, `--output-file` `file name`	Indicates the name by which the object must be stored on the local host after download.
`-T` `threads`, `--max-threads` `threads`	The maximum number of threads to be used in the download request. Depending on the speed and quality of the network, the CLI client may perform better with a different number of threads. The default number is 15. Any number between 1 and 100 is a valid entry. You can set the default value in the configuration file by updating the value of the variable `max-threads`. See Setting Up Configuration Files.
`--directory`	Downloads a set of objects that have the specified prefix in their names. Specify the prefix in the names of the objects that must be downloaded, in the `object` parameter. The prefix can be the full path and name of the directory that you’d uploaded the files from. To identify the prefix that you must specify in the `download` command with the `object` parameter, run the `list` command before you download. Important: When running the CLI on Windows, you would’ve used `\` as the directory separators for upload. However, match your download prefix to the result of the `list` command.
`-K` `key_filepath`, `--encryption-key` `key_filepath`	Indicates the master key file that must be used to decrypt the object data on the client-side after downloading it from the cloud storage. Note: Use the same master key file that you’d used to encrypt the object data when you’d uploaded it to cloud storage. To decrypt the object data that resides in a container of the `archive` storage class, restore the object first.

Note:

To download the archived objects from the Archive containers, you must first restore the objects. See Restoring an Object. (Not available on Oracle Cloud at Customer)

Examples

To download the object StandardObject from the container TestCLI and specify that the request be retried 3 times in case of failure:
```
java -jar ftmcli.jar download -R 3 TestCLI StandardObject
```
To download the object StandardObject from the container TestCLI and save it on the local host by the name DownloadedObject:
```
java -jar ftmcli.jar download -O DownloadedObject TestCLI StandardObject
```
To download the object StandardObject from the container TestCLI and set the maximum threads to 18:
```
java -jar ftmcli.jar download -T 18 TestCLI StandardObject
```
To download an object ArchiveObject from the Archive container TestCLI_Archive after the object has been restored (Not available on Oracle Cloud at Customer):
```
java -jar ftmcli.jar download TestCLI_Archive ArchiveObject
```
To download objects with the prefix /home/jack/FTM_CLI/MultipleObjects from the container TestCLI:
```
java -jar ftmcli.jar download --directory TestCLI /home/jack/FTM_CLI/MultipleObjects 
```
The following is the example of the output of this command:
```
Downloading files with path: /home/jack/FTM_CLI/MultipleObjects from container: TestCLI
File downloaded: myFile1.txt
File downloaded: myFile2.txt
File downloaded: myFile3.txt
File downloaded: myFile4.txt
File downloaded: myFile5.txt
Files Attempted: 5
Files Downloaded: 5
Files Failed: 0
Estimated Transfer Rate: -- KB/s
```
The downloaded files are stored in the current directory by creating a full path specified. For example, if the CLI is executed at the location /home/jack/ftmcli, then the downloaded files are stored at /home/jack/ftmcli/home/jack/FTM_CLI/MultipleObjects.

Note:
To avoid creating the full path in the current folder, use the -O option to specify the destination directory as illustrated in the later example.
To download an object myEncryptedObject from the TestCLI container and decrypt it using the master key file /home/jack/Encryption_Key.pem:
```
java -jar ftmcli.jar download -K /home/jack/Encryption_Key.pem TestCLI myEncryptedObject
```

Consider the case where multiple files are uploaded to the container TestCLI and contain the prefix Folder1/Folder2/Folder3 when stored on the container.

java -jar ftmcli.jar list TestCLI

The following is the sample output of this command:

/Folder1/Folder2/Folder3/myFile1.txt
/Folder1/Folder2/Folder3/myFile2.txt
/Folder1/Folder2/Folder3/myFile3.txt

Create a local directory TargetFolder where the objects can be downloaded and stored:

mkdir TargetFolder

To download objects with the prefix /Folder1/Folder2 to the local host in the location ./TargetFolder:

java -jar ftmcli.jar download --directory -O ./TargetFolder TestCLI /Folder1/Folder2

The following is the sample output of this command:

Downloading files with path: /Folder1/Folder2 from container: TestCLI
File downloaded: myFile1.txt
File downloaded: myFile2.txt
File downloaded: myFile3.txt
Files Attempted: 3
Files Downloaded: 3
Files Failed: 0
Estimated Transfer Rate: -- KB/s

Verify the download at the location ./TargetFolder.

ls -lR ./TargetFolder/

The following is the sample output of this command:

drwxr-xr-x 1 john Users 0 Mar 6  2018 Folder3

TargetFolder/Folder3:
-rw-r--r-- 1 john Users 111 Mar 6  2018 myFile1.txt
-rw-r--r-- 1 john Users 111 Mar 6  2018 myFile1.txt

The files myFile1.txt, myFile2.txt, and myFile3.txt are downloaded to the location ./TargetFolder/Folder3/.

Restoring an Object

This topic does not apply to Oracle Cloud at Customer.

Restores the object in an Archive container in Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar restore [optional arguments] container object

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the `Archive` container in which the object is located.
`object`	The name of the object that must be restored.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `download` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-s` , `--status-only`	Indicates that the command must return the status of the restore action started earlier, and not initiate a restore.

Note:

You must first restore the archived object before downloading it from the storage account. To download a restored object, see Downloading an Object.

Examples

To restore the object ArchivedObject in the Archive container TestCLI_Archive:
```
java -jar ftmcli.jar restore TestCLI_Archive ArchivedObject
```

To get the status of the restore function initiated earlier for the object ArchivedObject in the Archive container TestCLI_Archive:

java -jar ftmcli.jar restore -s TestCLI_Archive ArchivedObject

Sample Output:

Restoring object: ArchivedObject
Restore Status: PROCESSING Restore Percentage: 15%

Deleting an Object

Deletes the object in the specified container in Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar delete [optional arguments] container object

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container in which the object is located.
`object`	The name of the object that must be deleted.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `delete` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.

Examples

To delete the object Sample-script.txt in the container TestCLI and to specify that the request must be retried 3 times in case of failure:
```
java -jar ftmcli.jar delete -R 3 TestCLI Sample-script.txt
```
Command Output:
```
Object successfully deleted: Sample-script.txt
```

To delete the object Code-Samples/script1 in the container TestCLI:

java -jar ftmcli.jar delete TestCLI Code-Samples/script1

Command Output:

Object successfully deleted: Code-Samples/script1

Getting Object Metadata

Retrieves metadata of the specified object in a container in Oracle Cloud Infrastructure Object Storage Classic.

You can retrieve the following information about your object:

Object type (Content-Type)
Object size (Content-Length)
MD5 checksum value (Etag)
Date when the object was last modified
Segmentation details, in case of large objects

Syntax

java -jar ftmcli.jar describe [optional arguments] container object

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container in which the object is stored.
`object`	The object whose metadata must be retrieved.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `describe` command along with the optional arguments and usage.

Examples

Note:

The examples shown here are for running the CLI from an Oracle Linux host. When running the CLI on Windows, use \ as the directory separators.

To retrieve the metadata of the object myFirstObject stored in the container testContainer:

java -jar ftmcli.jar describe testContainer myFirstObject

The following is an example of the output of this command:

                 Name: myFirstObject
            Container: testContainer
                 Etag: 8035e55f30ae3f8b8a3b3c507e1b6a6c
       Content Length: 10485760
         Content Type: */*; charset=UTF-8
        Last Modified: Thu Mar 16 13:13:32 IST 2017

To retrieve the metadata of the static large object mySecondObject stored in the container testContainer:

java -jar ftmcli.jar describe testContainer mySecondObject

The following is an example of the output of this command:

                 Name: mySecondObject
            Container: testContainer
                 Etag: "841d932827eadec2f2cc101896b07b7d"
       Content Length: 5582966
         Content Type: */*; charset=UTF-8
        Last Modified: Thu Mar 16 13:13:32 IST 2017
                  SLO: True

The line SLO: True in the output shows that mySecondObject is a static large object.

To retrieve the metadata of the dynamic large object myThirdObject stored in the container testContainer:

java -jar ftmcli.jar describe testContainer myThirdObject

The following is an example of the output of this command:

                 Name: myThirdObject
            Container: testContainer
                 Etag: "e35d9ebdbc191e5378b2f21ff2d92e51"
       Content Length: 25698103378
         Content Type: */*; charset=UTF-8
        Last Modified: Thu Mar 16 13:13:32 IST 2017
             Manifest: testContainer_segments/myThirdObject/_segment_/1486973802120

The line Manifest: testContainer_segments/myThirdObject/_segment_/1486973802120 in the output points to the path where the segments of the dynamic large object myThirdObject are stored.

To retrieve the metadata of an encrypted object myEncryptedObject stored in the container testContainer:

java -jar ftmcli.jar describe testContainer myEncryptedObject

The following is an example of the output of this command:

                 Name: myEncryptedObject
            Container: testContainer
                 Etag: "e35d9ebdbc191e5378b2f21ff2d92e81"
       Content Length: 25698103498
         Content Type: */*; charset=UTF-8
        Last Modified: Thu Mar 16 13:13:14 IST 2017
             
			Custom Metadata
			---------------
			x-object-meta-envelopekey2: 9CCB461080A8A4114FA82A9F07378D04A259EBB115218049DB23BECEFA12BF582E892367
			D342E96664A4CC4960FE951BC3877A8DC0ECCDD83A23C2E88ED00A0DC3990BFF2E7FA0FC8761303EB605921A37F897B28AC9
			ABEB774F911B0BD444BC6352D152FA7AFE3E8A54D3069181B0DB1520277CE9BDB017FE88DAEC7F07E94D
			x-object-meta-envelopekey1: A0BB00E318AEEB7D4CA01C75D5CE45AB0B63153E948FF902E58F450DBBBE05E4802ED12C
			2097C2AF509DAD94C182E64041F7B5AD696D1626276D6BEA37CC7BE3342517DAB7A34993A7A981942A7796DE586E5D226FC1
			5C596F4B381CC9CEEF8B98F732D4023A8043CD2325C5F9746D7E8DC12F8BB5C02DE43AA410FB0EB00F11
			x-object-meta-digestkey1: B76A6CB74B1CFCB7C0E1B4BCD77A7DCA5B52817B62E3ACB28B69F7DB6D7DC2A9A9648A7725
			4ED9D83A64F255916860B9D4D95DFE83446D86C3376F4962C0B12D067EA3E84F78FA2B6ABD09CB4E6623E113002F7D85F324
			B6EB8B56D669B4EC8DDE5DDA798441BEB711EBEED0DBBDB83A76786C0F106E5191DF164C18B637181B
			x-object-meta-digestkey2: C3350D9F43318D45EC74993C0A01163C07A784C07A31E2DCCA48A5F691D6B1D59C78D032BD
			D4238DA29AE3DEDF371A4FE6045FD8CE2B6D4BAF49B1E30EDF8AF41461A1E2926EB5456ACA2748A25B38F372869CCA3D3A3E
			0CBD2DCEE10A48AC538C60AD15931151594C92F01FA0A50321AF59980192EFCEDAAD7376F6BFFA8D6A
			x-object-meta-digest: 97316AC4B2460642E603A64350986942642A5FAC78F0059BBBA290C110DEE0C0

Setting Object Metadata

Sets the metadata of the specified object in a container in Oracle Cloud Infrastructure Object Storage Classic.

You can set or update the following metadata for the object:

Custom metadata for the object: Custom metadata are arbitrary key-value pairs. You may create any custom or arbitrary metadata that you need.
Scheduling automatic deletion of objects: You can schedule deletion of objects at a specified time in the future or after a specified period of time has elapsed, by using the X-Delete-After or X-Delete-At header, respectively.
Client-side file encryption: When you enable client-side encryption for a file, the FTM CLI first generates a unique symmetric key, which is used to encrypt the file. Next, the FTM CLI encrypts the symmetric key using the master key that you specified in the upload command. When the symmetric key is encrypted by the FTM CLI, the following metadata is generated:X-Object-Meta-Envelopekey1, X-Object-Meta-Envelopekey2, X-Object-Meta-Digest, X-Object-Meta-Digestkey1, and X-Object-Meta-Digestkey2.
You can rotate the master key that’s used for client-side file encryption with the set command.

For example values to set the metadata, see Updating Object Metadata in Using Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar set [optional arguments] container object

Parameters and Optional Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container in which the object is stored.
`object`	The object whose metadata must be set.

The following optional arguments are specific to this command:

Argument	Description
`-h`, `--help`	Provides a detailed description of the `set` command along with the optional arguments and usage.
`-R` `retries`, `--retries` `retries`	Indicates the number of times that the request must be retried in case of failure. You can set the default value in the configuration file by updating the value of the variable `retries`. See Setting Up Configuration Files.
`-M` `metadata_name:metadata_value`, `--metadata` `metadata_name:metadata_value`	Sets or updates the object metadata. You can repeat the use of this option multiple times in a command to set or update multiple metadata headers. You can schedule automatic deletion of objects using this option.
`-C` `custom_metadata_name:custom_metadata_value`, `--custom-metadata` `custom_metadata_name:custom_metadata_value`	Sets or updates the custom metadata for the object. You can repeat the use of this option multiple times in a command to set or update multiple custom metadata headers. FTM CLI adds a prefix `X-Object-Meta-` to the custom metadata name.
`-K` `key_filepath`, `--encryption-key` `key_filepath`	Indicates the current master key file that’s used for client-side encryption of the object data. See About Client-Side File Encryption Note: The `--encryption-key` and `--new-encryption-key` command options must be used together to rotate master keys.
`-N` `key_filepath`, `--new-encryption-key` `key_filepath`	Indicates the new master key file that must be used for client-side encryption of the object data. Rotating the Master Key Note: The `--encryption-key` and `--new-encryption-key` command options must be used together to rotate master keys.

Note:

For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.

Examples

Note:

The examples shown here are for running the CLI from an Oracle Linux host. When running the CLI on Windows, use \ as the directory separators.

To set the metadata X-Delete-After with the value 86400 for the object myFirstObject in the container testContainer:
```
java -jar ftmcli.jar set -M X-Delete-After:86400 testContainer myFirstObject
```
To set the custom metadata X-Object-Meta-Country with a value US for the object mySecondObject in the container testContainer:
```
java -jar ftmcli.jar set -C Country:US testContainer mySecondObject
```
To set or update multiple metadata in a single command for the object myThirdObject in the container testContainer:
```
java -jar ftmcli.jar set -M X-Delete-At:1490196944 -C Language:english testContainer myThirdObject
```
To rotate the master key used for client-side encryption of the object myEncryptedObject in the container testContainer, provide the current master key file /home/jack/Encryption_Key.pem and the new master key file /home/jack/New_Encryption_Key.pem:
```
java -jar ftmcli.jar set -K /home/jack/Encryption_Key.pem -N /home/jack/New_Encryption_Key.pem testContainer myEncryptedObject
```

About Client-Side File Encryption

The FTM CLI enables client-side encryption of data that you want to store on Oracle Cloud Infrastructure Object Storage Classic. The FTM CLI on the client encrypts files before they are transferred to the cloud service. Files are encrypted when they are transferred to the cloud as well as when they are at rest on the cloud. The FTM CLI allows client-side encryption and decryption of static large objects (SLOs) but not dynamic large objects (DLOs).

Topics

Encrypting a File

To enable client-side encryption for a file when you upload it to the cloud service, provide a master key in the 2048–bit size RSA format, along with the --encryption-key command option, in the upload command. To generate the RSA master key, see Generating the Master Key.

You can upload an encrypted file to a container of the storage class standard or archive. See Uploading Files. (Archive support not available on Oracle Cloud at Customer)

When you enable client-side encryption for a file, the FTM CLI first generates a unique symmetric key in the 128–bit AES format, which is used to encrypt the file. Next, the FTM CLI encrypts the symmetric key using the master key that you specified in the upload command.

Important:

If you have multiple master keys, then maintain a record of the master keys and the corresponding files encrypted using each key. To decrypt the encrypted data, you’ll need the same master key that you’ve used for encryption.
The FTM CLI manages the generation, encryption, decryption, structure, and storage of the symmetric key.

The encrypted copy of the symmetric key is stored alongside the object data on the cloud service in the form of object metadata. When the symmetric key is encrypted by the FTM CLI, the following metadata is generated:

A 256-bit envelope key, which is stored as two 128-bit metadata items X-Object-Meta-Envelopekey1 and X-Object-Meta-Envelopekey2
An HMAC (secure hash) of the object data using HmacSHA256, which is stored as the X-Object-Meta-Digest metadata item
The encrypted form of the HMAC key. This encrypted form of the HMAC key is generated using the master key. The encrypted form of the HMAC key is stored as metadata items X-Object-Meta-Digestkey1 and X-Object-Meta-Digestkey2

Generating the Master Key

To encrypt your files before uploading them to cloud storage, generate a 2048-bit RSA master key to use for encryption and decryption:

To generate the master key and store it in the file Encryption_Key.pem:
```
openssl genrsa -out Encryption_Key.pem 2048
```
Make a note of the path where the key file is stored.

Decrypting an Object

To download an encrypted object, provide the same master key that you’d used for encrypting the file along with the --encryption-key option for the download command. See Downloading an Object.

If the object that you want to download resides in a container of the archive storage class, then you must restore it first. After the object is restored, download it by providing the master key along with the --encryption-key option for the download command. See Downloading an Object from an Archive Container. (Archive support not available on Oracle Cloud at Customer)

After the encrypted object is downloaded from the cloud service, the FTM CLI first decrypts the encrypted copy of the symmetric key using the master key. Next, the FTM CLI uses the decrypted symmetric key to decrypt the object and retrieve the original file content.

Note:

If you provide the wrong master key with the download command, then the FTM CLI gives an IllegalArgument exception, and the object isn’t downloaded.
If you don't provide a master key when you download an encrypted object, then the object is downloaded but not decrypted. To retrieve the original content of the encrypted object, you must provide the right master key with the download command.

Rotating the Master Key

You can change the master key that you’ve used to encrypt a specific file by rotating the key. The following are a few scenarios when such a change may be necessary:

You have a security policy that mandates periodically updating master keys
You suspect that a master key might have been compromised

To rotate the master key, provide the old and new master keys along with the --encryption-key and --new-encryption-key options for the set command. See Setting Object Metadata. The FTM CLI does the following:

Retrieves the encrypted symmetric key from the cloud service
Decrypts the symmetric key using the old master key
Encrypts the symmetric key using the rotated master key
Stores the updated symmetric key as object metadata items

The encrypted object data on the cloud remains undisturbed during the process.

When you download an object using the rotated master key, the FTM CLI does the following::

Downloads the encrypted object
Retrieves the encrypted symmetric key
Decrypts the symmetric key using the rotated master key
Uses the unencrypted symmetric key to decrypt the object

Note:

If you have to manage more than one master key, you can consider using third-party tools for key management. However, Oracle does not certify any such third-party tool for use with the FTM CLI.
The set command is issued for a specific object on the cloud service. Hence, the FTM CLI rotates the master key only for the specific object. Remember to rotate the master key for each object individually, if you plan to rotate the specific master key for several objects.
The FTM CLI manages the decryption, encryption, and storage of the symmetric key when you rotate the master key.

Bulk Operations

Learn how to perform bulk operations in Oracle Cloud Infrastructure Object Storage Classic using the FTM CLI.

Operations:

Creating Multiple Objects

Creates multiple objects in the specified container in Oracle Cloud Infrastructure Object Storage Classic by extracting files from an archive file.

Syntax

java -jar ftmcli.jar upload --extract-archive [optional arguments] container filepath

Parameters and Arguments

The following parameters are specific to this command:

Parameter Description

Parameter	Description
`container`	The name of the container to which the objects must be uploaded. If the specified container doesn't exist, then it’s created by the CLI.
`filepath`	The path of the archive file that must be uploaded. The objects are created by extracting the files from this archive file

container

The name of the container to which the objects must be uploaded. If the specified container doesn't exist, then it’s created by the CLI.

filepath

The path of the archive file that must be uploaded.

The objects are created by extracting the files from this archive file

The following arguments are specific to this command:

Argument Description

Argument	Description
`-x`, `--extract-archive`	Indicates that the objects must be created by extracting the files from the archive file.
`-j` `prefix`, `--object-prefix` `prefix`	(Optional) Provides the prefix that’s appended to the object name while storing it in the container. For example, for the file `myObject` that’s extracted from the archive file `bulkFolder.tar.gz`, when the prefix specified is `large`, the object is stored as `large/bulkFolder/myObject`. Select the prefix to group the objects that might be bulk-downloaded with a single command. See Downloading Multiple Objects.
`-f` `format`, `--file-format` `format`	(Optional) Indicates the format of the archive file to be uploaded. The supported formats are `tar`, `tar.gz`, and `tar.bz2`.

-x, --extract-archive

Indicates that the objects must be created by extracting the files from the archive file.

-j prefix, --object-prefix prefix

(Optional) Provides the prefix that’s appended to the object name while storing it in the container. For example, for the file myObject that’s extracted from the archive file bulkFolder.tar.gz, when the prefix specified is large, the object is stored as large/bulkFolder/myObject.

Select the prefix to group the objects that might be bulk-downloaded with a single command. See Downloading Multiple Objects.

-f format, --file-format format

(Optional) Indicates the format of the archive file to be uploaded. The supported formats are tar, tar.gz, and tar.bz2.

Fro the complete list of optional arguments that you can use with the upload command, see Uploading Files.

Note:

For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.

Note:

When you upload multiple files from an archive file, the objects created on the container will have the name of the archive file as the prefix in their file names. For example, for the file myObject that’s extracted from the archive file bulkFolder.tar.gz, it is stored in the container as bulkFolder/myObject.

Example

To upload the files from the archive file bulkFolder1.tar to the container TestCLI and store it with the prefix downloadThis:

java -jar ftmcli.jar upload --extract-archive --object-prefix downloadThis --file-format tar TestCLI bulkFolder1.tar

To upload another set of files from the archive file bulkFolder2.tar.gz to the container TestCLI and store it with the prefix downloadThis:

java -jar ftmcli.jar upload --extract-archive --object-prefix downloadThis --file-format tar.gz TestCLI bulkFolder2.tar.gz

You can now download the objects that were extracted from the archive files bulkFolder1.tar and bulkFolder2.tar.gz by specifying the prefix downloadThis along with the --directory argument in the download command.

Downloading Multiple Objects

Downloads the objects in bulk from the specified container in Oracle Cloud Infrastructure Object Storage Classic.

Syntax

java -jar ftmcli.jar download --directory [optional arguments] container object

Parameters and Arguments

The following parameters are specific to this command:

Parameter	Description
`container`	The name of the container from which the objects must be downloaded.
`object`	In case of bulk download, this is the prefix in the names of the objects that must be downloaded together.

The following arguments are specific to this command:

Argument Description

Argument	Description
`-O` `file name`, `--output-file` `file name`	(Optional) Indicates the name by which the object must be stored on the local host after download.
`--directory`	Downloads a set of objects that have the specified prefix in their names. Specify the prefix in the names of the objects that must be downloaded, in the `object` parameter. To identify the prefix that you must specify in the `download` command, run the `list` command before you download. Important: When running the CLI on Windows, you would’ve used `\` as the directory separators for upload. However, match your download prefix to the result of the `list` command.

-O file name, --output-file file name

(Optional) Indicates the name by which the object must be stored on the local host after download.

--directory

Downloads a set of objects that have the specified prefix in their names.

Specify the prefix in the names of the objects that must be downloaded, in the object parameter. To identify the prefix that you must specify in the download command, run the list command before you download.

Important:

When running the CLI on Windows, you would’ve used \ as the directory separators for upload. However, match your download prefix to the result of the list command.

For the complete list of arguments available with the download command, see Downloading an Object.

Note:

To download the archived objects from the Archive containers, you must first restore the objects. See Restoring an Object. (Not available on Oracle Cloud at Customer)

Examples

To download objects with the prefix /home/jack/FTM_CLI/MultipleObjects from the container TestCLI:
```
java -jar ftmcli.jar download --directory TestCLI /home/jack/FTM_CLI/MultipleObjects  
```
The following is the example of the output of this command:
```
Downloading files with path: /home/jack/FTM_CLI/MultipleObjects from container: TestCLI
File downloaded: myFile1.txt
File downloaded: myFile2.txt
File downloaded: myFile3.txt
File downloaded: myFile4.txt
File downloaded: myFile5.txt
Files Attempted: 5
Files Downloaded: 5
Files Failed: 0
Estimated Transfer Rate: -- KB/s
```
The downloaded files are stored in the current directory by creating a full path specified. For example, if the CLI is executed at the location /home/jack/ftmcli, then the downloaded files are stored at /home/jack/ftmcli/home/jack/FTM_CLI/MultipleObjects.

Note:
To avoid creating the full path in the current folder, use the -O option to specify the destination directory as illustrated in the following example.

Consider the case where multiple files are uploaded to the container TestCLI .

java -jar ftmcli.jar list TestCLI

The following is the sample output of this command:

/Folder1/Folder2/Folder3/myFile1.txt
/Folder1/Folder2/Folder3/myFile2.txt
/Folder1/Folder2/Folder3/myFile3.txt
/Folder1/Folder2/Folder3/myFile4.txt
/Folder1/Folder2/Folder3/myFile5.txt
/Folder1/Folder2/myFile6.txt
/Folder1/Folder2/myFile7.txt
/Folder1/Folder2/myFile8.txt
/Folder1/Folder2/myFile9.txt
/Folder1/Folder2/myFile10.txt
myFile11.txt
myFile12.txt
myFile13.txt
myFile14.txt
myFile15.txt

To download objects with the prefix /Folder1/Folder2 to the local host in the location ./PlaceHolder:

java -jar ftmcli.jar download --directory -O ./PlaceHolder TestCLI /Folder1/Folder2

As the result, the files myFile1.txt, myFile2.txt, myFile3.txt, myFile4.txt, and myFile5.txt are downloaded to the location ./PlaceHolder/Folder3/. The files myFile6.txt, myFile7.txt, myFile8.txt, myFile9.txt, and myFile10.txt are downloaded to the location ./PlaceHolder.