1 Preparing to Use the Oracle Storage Cloud File Transfer Manager CLI

You must install Oracle Storage Cloud 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.

System Requirements and Supported Platforms

Supported Platforms

  • Oracle Linux 6.3

  • Oracle Linux 6.5

  • Microsoft Windows 7

  • Ubuntu Desktop 14.04

JRE Requirements

Ensure that one of the following JREs is installed:
  • JRE 7

  • JRE 8

  • OpenJDK 7

  • OpenJDK 8

Obtaining Account Information

Identity Domain Name, User Name, and Password

After Oracle creates your account, you'll receive an email that contains your identity domain name, user name, and password for your Oracle Storage Cloud Service account.

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 API Endpoint URL

  1. Sign in to the Oracle Cloud My Services application. See Signing In to the My Services Application in Managing and Monitoring Oracle Cloud.

    The My Services Dashboard is displayed. It lists the services that are assigned to your account.

  2. Look for Oracle Storage Cloud Service.

  3. From the Actions Select any of the actions displayed to perform the relevant corresponding activity. menu, select View Details. The Service Details page is displayed.

  4. Look at the URL displayed in the REST Endpoint field under Additional Information.

REST Endpoint: https://acme.storage.oraclecloud.com/v1/Storage-acme
  • acme is the identity domain name.

  • v1 is the API version.

  • Storage-acme is the account name.

  • Storage is the service name.

Note:

The full REST API endpoint URL displayed in Oracle Cloud My Services will include the API version and the account name. But in the FTM CLI, use only the endpoint host name for the authentication URL as shown in bold in the prior example (https://acme.storage.oraclecloud.com).

Getting Your Required Roles

Contact your account administrator and get the required roles assigned to your user name in Oracle Cloud My Services.
  • To create, update, and delete the Oracle Compute Cloud Service containers, you must have the Storage_Administrator role.

  • To create, update, and delete the Oracle Compute Cloud Service 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 Storage Cloud Service Roles and Users in Using Oracle Storage Cloud Service.

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 My Services. See Modifying User Roles in Managing and Monitoring Oracle Cloud.

Obtaining the Oracle Storage Cloud File Transfer Manager CLI

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

  1. Download the FTM CLI client ftmcli.jar file from  http://www.oracle.com/technetwork/topics/cloud/downloads/index.html.
  2. 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.
  3. 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 Storage Cloud 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:

  1. Store the following sample configuration file with a suitable name on your local host:
    # url endpoint of the storage service
    auth-url=https://acme.storage.oraclecloud.com
    
    # service name
    service=Storage
    
    #identity domain name or tenent name
    identity-domain=acme
    
    # storage service user
    user=jack.jones@oracle.com
    
    # container for segments, if not specified <container>_segments is used
    segments-container=all_segments
    
    # segment size in MiBs
    segment-size=200
    
    # 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
    
    # Proxy Host
    #https-proxy-host = <proxy_host>
    
    # Proxy Port
    #https-proxy-port = <port_numbrt>
  2. Update the parameters in the configuration file as follows:
    Parameter Description
    auth-url The REST API endpoint URL of your Oracle Storage Cloud Service instance.
    user Your user name.

    Note:

    You must have the appropriate role in Oracle Cloud My Services. See Getting Your Required Roles.

    service The cloud service name.

    The default value is Storage.

    identity-domain The name of your identity domain.
    storage-class The storage class.

    By default, it’s set to Standard, but you can also change it to Archive.

    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.

Note:

To find out your account’s details like user name, password, identity domain, service name, and REST API endpoint URL, follow the instructions at Obtaining Account Information.

Setting Up the Required Environment Variables

To avoid entering the authentication URL, service name, and 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 Storage Cloud 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:

  1. Store the REST API endpoint URL of your Oracle Storage Cloud Service instance in the environment variable FTM_AUTH_URL.
    To find out the REST API endpoint URL of your site, follow the instructions at Obtaining Account Information.
    export FTM_AUTH_URL=https://acme.storage.oraclecloud.com
    
  2. Store your user name in the environment variable FTM_USER.
    export FTM_USER=jack.jones@example.com
    

    Note:

    You must have the appropriate role in Oracle Cloud My Services. See Getting Your Required Roles.
  3. Store the cloud service name in the environment variable FTM_SERVICE.
    export FTM_SERVICE=Storage
    
  4. Store the name of your identity domain in the environment variable FTM_IDOMAIN.
    To find out your account’s identity domain name, follow the instructions at Obtaining Account Information.
    export FTM_IDOMAIN=acme