Preparing to Use the FTM CLI

1 Preparing to Use the FTM CLI

You must install Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager command-line interface (FTM CLI) first, and depending on your choice of authentication method, you might have to set up configuration files, or some environment variables.

Topics

System Requirements and Supported Platforms

Supported Platforms

Oracle Linux 6.3 or later
Oracle Linux 7.0 or later
Microsoft Windows 7
Microsoft Windows 10
Microsoft Windows Server 2012
Ubuntu 14.04 LTS
Ubuntu 16.04 LTS
Mac OS X 10.7 or later
Mac OS 10.12 or later

JRE Requirements

Ensure that one of the following JREs is installed:

JRE 7
JRE 8
JRE 9
OpenJDK 7
OpenJDK 8

Important:

For FTM CLI 2.3 or earlier, if you’re using JRE 9, and if one of the below scenarios is applicable,
- You’ve used the —save-auth-key parameter in the command to save the password.
- The command accesses the encrypted password that’s stored in the ftmcliKeystore file.
then use the following general command syntax:
```
java --add-modules java.xml.bind -jar ftmcli.jar command [command_specific_options] target [general_CLI_command_options] -U user -A auth_url -S service -I identity_domain
```
or the following simplified command syntax:
```
java --add-modules java.xml.bind -jar ftmcli.jar command [command_specific_options] target [general_CLI_command_options]
```

If you’re using JRE 8, then for improved performance of FTM CLI 2.4, disable GCM:

Create a file java.security with the following line:
```
jdk.tls.disabledAlgorithms=SSLv3,GCM
```

Start your Java process with the command:

java -Djava.security.properties=/path/to/my/java.security -jar ftmcli.jar command [command_specific_options] target [general_CLI_command_options] -P rest_endpoint -U user

Obtaining Account Information

Identity Domain Name, User Name, and Password

After Oracle creates your account, you'll receive a Welcome email that contains your user name, and password for your Oracle Cloud Infrastructure Object Storage Classic account. Additionally, if your account type is Traditional Account, then the Welcome email also contains the identity domain. To know your account type, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources in Using Oracle Cloud Infrastructure Object Storage Classic.

Account creation email from Oracle contains the name of the identity domain, user name, and password.

If you can't find this email or didn't receive it, then contact your service administrator.

REST Endpoint URL

To find the REST Endpoint URL for your storage account and to know your account type, see About REST URLs for Oracle Cloud Infrastructure Object Storage Classic Resources in Using Oracle Cloud Infrastructure Object Storage Classic.

Depending on the type of your account, you’ll see one or both the REST Endpoints similar to the following example URLs:

REST Endpoint: https://acme.storage.oraclecloud.com/v1/Storage-acme

REST Endpoint (Permanent): https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365

To decide if you must use REST Endpoint or REST Endpoint (Permanent) in the FTM CLI for your use-case, see Finding the REST Endpoint URL for Your Cloud Account in Using Oracle Cloud Infrastructure Object Storage Classic.

Note:

In the above examples, Storage is the service name.
In FTM CLI 2.3 or earlier, for the authentication URL parameter, use only the part of the REST Endpoint URL that you see before the API version /v1. That is, use https://acme.storage.oraclecloud.com from the REST Endpoint or https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com from the REST Endpoint (Permanent) from the above examples for the authentication URL parameter.

Constructing the user Parameter

If you’re using FTM CLI 2.3 or earlier, then to obtain authentication to access Oracle Cloud Infrastructure Object Storage Classic, you must construct the user parameter using the user name and the REST API endpoint URL.

Obtain the part of the REST Endpoint URL after the API version v1/.

For example, select Storage-acme if your REST Endpoint URL is similar to https://acme.storage.oraclecloud.com/v1/Storage-acme. Select Storage-7b16fede61e1417ab83eb52e06f0e365 if your REST Endpoint URL is similar to https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365.
To construct the user parameter, insert a colon (:) after the selected part of the REST Endpoint URL and append the user name to it.
If your user name is jack.jones@examples.com, and your REST Endpoint URL is similar to https://acme.storage.oraclecloud.com/v1/Storage-acme, then the user parameter is
```
user=Storage-acme:jack.jones@example.com
```
If your REST Endpoint URL is similar to https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365, then the user parameter is
```
user=Storage-7b16fede61e1417ab83eb52e06f0e365:jack.jones@example.com
```

Getting Your Required Roles

Contact your account administrator and get the required roles assigned to your user name in Oracle Cloud Infrastructure Classic Console.

To create, update, and delete the Oracle Cloud Infrastructure Object Storage Classic containers, you must have the Storage_Administrator role.
To create, update, and delete the Oracle Cloud Infrastructure Object Storage Classic objects, you must have the Storage_ReadWriteGroup role.
To view or retrieve details of the objects or containers, you must have the Storage_ReadGroup role.

For more information, see About Oracle Cloud Infrastructure Object Storage Classic Roles and Users in Using Oracle Cloud Infrastructure Object Storage Classic.

If the required 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.

Obtaining the FTM CLI

To start using the CLI for the Oracle Cloud Infrastructure Object Storage Classic, download the CLI client and store it at an appropriate location on the host.

Download the FTM CLI client ftmcli.jar file from http://www.oracle.com/technetwork/topics/cloud/downloads/index.html.
Save the file at an appropriate location on the local host, for example, /home/jack/FTM_CLI/ftmcli.jar. Note that when you create the configuration file, you must store it at the same location. The CLI creates the ftmcli.log and ftmcli.trace files at the same location. You can view the contents of these files to debug issues.
Provide Execute permission to the ftmcli.jar file with the chmod command.

Setting Up Configuration Files

To avoid entering the authentication information with every command, setting the environment variables at the start of every session, or updating the configuration file with new set of parameters, you can store combinations of parameters permanently in multiple configuration files. You can also set the default values of some of the parameters associated with the Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager command-line interface (FTM CLI) operation in the configuration file. By using the --properties-file command option on the command-line, you can specify the service instance against which the command must run or the CLI parameters that the command must use by specifying the appropriate configuration file. To create a configuration file on the local host on which you downloaded the FTM CLI client:

Store the following sample configuration file with a suitable name on your local host:


#---------------Account parameters---------------

# Your user name if you're using FTM CLI 2.4.
user=jack.jones@example.com
# In case of FTM CLI 2.3 or earlier, user=Storage-acme:jack.jones@example.com 
# OR similar to user=Storage-7b16fede61e1417ab83eb52e06f0e365:jack.jones@example.com for REST Endpoint (Permanent)

# REST Endpoint URL for your account
# In case of REST Endpoint (Permanent), use similar to https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
rest-endpoint=https://acme.storage.oraclecloud.com/v1/Storage-acme

# Following parameters are deprecated. Supported only for backward compatibility (FTM CLI 2.3 or earlier).
# If rest-endpoint is specified, then the following parameters will be ignored.
# service name (FTM CLI 2.3 or earlier)
#service=Storage

#identity domain name (FTM CLI 2.3 or earlier)
#identity-domain=acme

# Authentication url endpoint of the storage service (FTM CLI 2.3 or earlier)
#auth-url=https://acme.storage.oraclecloud.com

#---------------Other parameters---------------
# segment size in MiBs
segment-size=100

# number of retries
retries=5

# maximum number of threads created to transfer file(s)
max-threads=15

# storage Class (Archive or Standard)
storage-class=Standard

# container for segments, if not specified <container>_segments is used
segments-container=all_segments

# Proxy Host
#https-proxy-host = <proxy_host>

# Proxy Port
#https-proxy-port = <port_numbrt>

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.

Update the parameters in the configuration file as follows:

Parameter	Description
`user`	If you’re using FTM CLI 2.4, then this is your user name to access your storage account. See Obtaining Account Information. If you’re using FTM CLI 2.3 or earlier, then this is the user parameter that you constructed using your user name and REST API endpoint URL. See Constructing the user Parameter. Note: You must have the appropriate role in Oracle Cloud Infrastructure Classic Console. See Getting Your Required Roles.
`rest-endpoint`	The REST Endpoint or the REST Endpoint (Permanent) of your storage account. See REST Endpoint URL.
`auth-url` (Deprecated from FTM CLI 2.4)	The authentication URL that you derived from the REST Endpoint URL of your Oracle Cloud Infrastructure Object Storage Classic instance. See REST Endpoint URL.
`service` (Deprecated from FTM CLI 2.4)	The cloud service name. See REST Endpoint URL.
`identity-domain` (Deprecated from FTM CLI 2.4)	The identity domain of your service instance. See Identity Domain Name, User Name, and Password.
`storage-class`	The storage class. By default, it’s set to `Standard`, but you can also change it to `Archive`. (`Archive` support not available on Oracle Cloud at Customer).
`max-threads`	The maximum number of threads to be used in a request. You can specify any value between 1 and 100. Depending on the speed and quality of the network, the FTM CLI may perform better with a different number of threads. By default, it’s set to 15.
`retries`	The number of times that a request must be retried in case of failure. By default, it’s set to 5.
`segment-size`	The segment size in MB. By default, it’s set to 200 MB.
`segments-container`	The container in which the segments must be stored during the upload process. By default, it’s set to `all_segments`. If the segments container is not specified, then the segments are stored in the container `<container>_segments` where `<container>` is the name of the container specified to store the manifest object.
`https-proxy-host`, `https-proxy-port`	The proxy host and the proxy port. The lines to set these parameters are excluded from execution by default. Include the lines by uncommenting them and set the values of the proxy host and the proxy port if necessary.

Caution:

When you run a CLI command, if you specify the --save-auth-key option, then the key to decrypt your saved password is stored in the configuration file, as the auth-key parameter. Don't remove or edit that parameter.

Setting Up the Required Environment Variables

To avoid entering the authentication URL, service name, and identity domain name with every command, you can store them in the environment variables once at the beginning of the session. The values of the environment variables are lost when the session ends.

The CLI gives higher priority to the environment variables than to the configuration file. The values set in the configuration file get picked up by the Oracle Cloud Infrastructure Object Storage Classic File Transfer Manager command-line interface (FTM CLI) client if the environment variables haven't been set for the session.

To set the required environment variables on the host on which you downloaded the FTM CLI client:

Store the REST Endpoint of your storage account in the FTM_REST_ENDPOINT environment variable. See REST Endpoint URL.
If your REST Endpoint is similar to https://acme.storage.oraclecloud.com/v1/Storage-acme, then
```
export FTM_REST_ENDPOINT=https://acme.storage.oraclecloud.com/v1/Storage-acme
```
If your REST Endpoint is similar to https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365, then
```
export FTM_REST_ENDPOINT=https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365
```
Store your user parameter in the environment variable FTM_USER.
- If you’re using FTM CLI 2.3 or earlier, then to construct your user paramater, follow the instructions at Constructing the user Parameter.
```
export FTM_USER=myservice-bar:jack.jones@example.com
```
- If you’re using FTM CLI 2.4, then the user name for your storage account is the value of your user parameter.
```
export FTM_USER=jack.jones@example.com
```
Note:
You must have the appropriate role in Oracle Cloud Infrastructure Classic Console. See Getting Your Required Roles.
(Deprecated from FTM CLI 2.4) Store the authentication URL in the environment variable FTM_AUTH_URL.
To derive the authentication URL from your REST Endpoint, follow the instructions at REST Endpoint URL.
If your REST Endpoint is similar to https://acme.storage.oraclecloud.com/v1/Storage-acme, then
```
export FTM_AUTH_URL=https://acme.storage.oraclecloud.com
```
If your REST Endpoint is similar to https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com/v1/Storage-7b16fede61e1417ab83eb52e06f0e365, then
```
export FTM_AUTH_URL=https://storage-7b16fede61e1417ab83eb52e06f0e365.storage.oraclecloud.com
```
(Deprecated from FTM CLI 2.4) Store the cloud service name in the environment variable FTM_SERVICE.
To find out the service name of your Oracle Cloud Infrastructure Object Storage Classic instance, see REST Endpoint URL.
```
export FTM_SERVICE=myservice
```
(Deprecated from FTM CLI 2.4) Store the name of your identity domain in the environment variable FTM_IDOMAIN.
To find out the identity domain of your service instance, follow the instructions at Identity Domain Name, User Name, and Password.
```
export FTM_IDOMAIN=myIdentity3
```

Note: