4 Command Line Reference
Authentication
-
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.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 |
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:
|
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
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 |
---|---|
|
Provides a detailed description of the |
|
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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
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 |
|
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.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.
Examples
-
To set a new custom metadata
X-Account-Meta-CoreTest
with the valueWelcome123
:java -jar ftmcli.jar set -C CoreTest:Welcome123
-
To update the existing custom metadata
X-Account-Meta-HR-Key
with a new valueNewKey123
:java -jar ftmcli.jar set -C HR-Key:NewKey123
-
To set the georeplication policy for the account with a value
us2–us6
, whereus2
is the primary DC andus6
is the replication DC:java -jar ftmcli.jar set -M X-Account-Meta-Policy-Georeplication:us2-us6
Managing Containers
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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Lists the container names that have the specified prefix. |
|
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. |
|
Lists the containers with names greater than the specified string. |
|
Lists the containers with names less than the specified string. |
|
Limits the number of container names listed to the specified value. Default and maximum value: 10000. |
|
Lists all the container names even if the storage service has to run multiple queries to get more than 10000 containers. |
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.
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 |
---|---|
|
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 |
|
Sets the storage class of the container to |
|
Enables server-side encryption for the container by setting the policy to You can enable server-side encryption for a container only at the time of creating it, not later. |
|
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. |
|
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 You can set the custom metadata headers and CORS headers using this option. |
|
Indicates the primary DC code of your container. |
|
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. |
|
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. |
|
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. |
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.
Examples
-
To create the container
myTestArchiveContainer
of theArchive
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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Deletes a container and all its contents. |
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.
Examples
-
To delete the container
TestCLI
and to specify that the request must be retried6
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
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 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 |
---|---|
|
Provides a detailed description of the |
|
Provides the container replication details for the container. |
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.
Examples
-
To retrieve the metadata of the container
testStandardContainer
that belongs to thestandard
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 thearchive
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.
- 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
andX-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
, andX-Container-Meta-Access-Control-Expose-Headers
.
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] 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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
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. |
|
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 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.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.
Examples
-
To update the container metadata
X-Container-Write
with the valuemyIdentity3.myservice.Storage_ReadWriteGroup
for the containertestContainer
: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 value2
for the containertestContainer
: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.
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 |
---|---|
|
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 |
---|---|
|
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. |
|
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. |
|
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. |
|
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 |
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.
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
andhttps://<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 ishttps://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
Listing Objects
Lists the objects in the specified container 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] 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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Lists the object names that have the specified prefix. |
|
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. |
|
Lists the objects with names greater than the specified string. |
|
Lists the objects with names less than the specified string. |
|
Limits the number of object names listed to the specified value. Default and maximum value: 10000. |
|
Lists all the object names even if the storage service has to run multiple queries to get more than 10000 objects. |
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.
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 prefixScripting
: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 containertestCLI
: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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Indicates the name by which the object must be saved in the container. |
|
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 |
|
Indicates the segment size in MB. You can set the default value in the configuration file by updating the value of the variable |
|
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 |
|
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. |
|
Indicates that the object must be archived in the specified (Not available on Oracle Cloud at Customer) |
|
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. |
|
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.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.
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 containerTestCLI
and store it with the nameStandardObject_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 containerTestCLI
: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 containerTestCLI
and set the maximum threads to10
: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 containerTestCLI
in 10 segments of size 1 MB each, and to store the segments in the segments containerTestCLI_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 containerTestCLI
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 theArchive
containerTestCLI_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 containerSSE_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 containerTestCLI
: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.
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.
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 |
---|---|
|
The name of the target container to which the object must be copied. |
The following optional arguments are specific to this command:
Argument | Description |
---|---|
|
Indicates the name by which the object must be stored on the target container after copy. |
|
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. |
|
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 You can set the custom metadata headers and CORS headers using this option. |
|
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 |
|
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 |
|
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. |
|
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 |
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.
Examples
-
To copy the large object
LargeObject
from the containerSourceContainer1
to the target containerTargetContainer1
and specify the target segments containerCommon_Segments
:java -jar ftmcli.jar copy SourceContainer1 LargeObject --target-container TargetContainer1 --target-segments-container Common_Segments
-
To copy the object
StandardObject1
from the containerSourceContainer1
to the target containerTargetContainer1
and store the object by the nameStandardObject2
:java -jar ftmcli.jar copy SourceContainer1 StandardObject1 --target-container TargetContainer1 --target-object StandardObject2
-
To copy the object
StandardObject
from the containerSourceContainer1
to the target containerTargetContainer1
without any existing metadata:java -jar ftmcli.jar copy SourceContainer1 StandardObject --target-container TargetContainer1 --fresh-metadata
-
To copy the object
StandardObject
from the containerSourceContainer1
to the target containerTargetContainer1
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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Indicates the name by which the object must be stored on the local host after download. |
|
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 |
|
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 Important: When running the CLI on Windows, you would’ve used |
|
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 |
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.
Note:
To download the archived objects from theArchive
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 containerTestCLI
and specify that the request be retried3
times in case of failure:java -jar ftmcli.jar download -R 3 TestCLI StandardObject
-
To download the object
StandardObject
from the containerTestCLI
and save it on the local host by the nameDownloadedObject
:java -jar ftmcli.jar download -O DownloadedObject TestCLI StandardObject
-
To download the object
StandardObject
from the containerTestCLI
and set the maximum threads to18
:java -jar ftmcli.jar download -T 18 TestCLI StandardObject
-
To download an object
ArchiveObject
from theArchive
containerTestCLI_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 containerTestCLI
: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 theTestCLI
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 prefixFolder1/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
, andmyFile3.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.
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 restore [optional arguments] container object
Parameters and Optional Arguments
The following parameters are specific to this command:
Parameter | Description |
---|---|
container |
The name of the |
object |
The name of the object that must be restored. |
The following optional arguments are specific to this command:
Argument | Description |
---|---|
|
Provides a detailed description of the |
|
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 |
|
Indicates that the command must return the status of the restore action started earlier, and not initiate a restore. |
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.
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 theArchive
containerTestCLI_Archive
:java -jar ftmcli.jar restore TestCLI_Archive ArchivedObject
-
To get the status of the restore function initiated earlier for the object
ArchivedObject
in theArchive
containerTestCLI_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.
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 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 |
---|---|
|
Provides a detailed description of the |
|
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 |
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.
Examples
-
To delete the object
Sample-script.txt
in the containerTestCLI
and to specify that the request must be retried3
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 containerTestCLI
: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
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 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 |
---|---|
|
Provides a detailed description of the |
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.
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 containertestContainer
: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 containertestContainer
: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 thatmySecondObject
is a static large object. -
To retrieve the metadata of the dynamic large object
myThirdObject
stored in the containertestContainer
: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 objectmyThirdObject
are stored. -
To retrieve the metadata of an encrypted object
myEncryptedObject
stored in the containertestContainer
: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.
- 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
orX-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
, andX-Object-Meta-Digestkey2
.You can rotate the master key that’s used for client-side file encryption with the set command.
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] 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 |
---|---|
|
Provides a detailed description of the |
|
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 |
|
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. |
|
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 |
|
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 |
|
Indicates the new master key file that must be used for client-side encryption of the object data. Rotating the Master Key Note: The |
Note:
For the character restrictions applicable when you must select a name or a metadata value, see Character Restrictions.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.
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 value86400
for the objectmyFirstObject
in the containertestContainer
:java -jar ftmcli.jar set -M X-Delete-After:86400 testContainer myFirstObject
-
To set the custom metadata
X-Object-Meta-Country
with a valueUS
for the objectmySecondObject
in the containertestContainer
: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 containertestContainer
: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 containertestContainer
, 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).
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.
-
A 256-bit envelope key, which is stored as two 128-bit metadata items
X-Object-Meta-Envelopekey1
andX-Object-Meta-Envelopekey2
-
An HMAC (secure hash) of the object data using
HmacSHA256
, which is stored as theX-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
andX-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 have a security policy that mandates periodically updating master keys
- You suspect that a master key might have been compromised
--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.
- 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
Creating Multiple Objects
Creates multiple objects in the specified container in Oracle Cloud Infrastructure Object Storage Classic by extracting files from an archive file.
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 --extract-archive [optional arguments] container filepath
Parameters and Arguments
The following parameters are specific to this command:
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 |
The following arguments are specific to this command:
Argument | Description |
---|---|
|
Indicates that the objects must be created by extracting the files from the archive file. |
|
(Optional) Provides the prefix that’s appended to the object name while storing it in the container. For example, for the file Select the prefix to group the objects that might be bulk-downloaded with a single command. See Downloading Multiple Objects. |
|
(Optional) Indicates the format of the archive file to be uploaded. The supported formats are |
Fro the complete list of optional arguments that you can use with the upload command, see Uploading Files.
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.
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 filemyObject
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.
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 --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 |
---|---|
|
(Optional) Indicates the name by which the object must be stored on the local host after download. |
|
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 Important: When running the CLI on Windows, you would’ve used |
For the complete list of arguments available with the download command, see Downloading an Object.
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.
Note:
To download the archived objects from theArchive
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 containerTestCLI
: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
, andmyFile5.txt
are downloaded to the location./PlaceHolder/Folder3/
. The filesmyFile6.txt
,myFile7.txt
,myFile8.txt
,myFile9.txt
, andmyFile10.txt
are downloaded to the location./PlaceHolder
.