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 or later

  • Oracle Linux 7.0 or later

  • Microsoft Windows 7

  • Microsoft Windows 10

  • 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

  • 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 the identity domain, your user name, and password for your Oracle Storage Cloud Service instance.

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://foo.storage.oraclecloud.com/v1/myservice-bar
  • Note that foo and bar can be the same or different values, and they can include one or more hyphens.

  • v1 is the API version.

  • myservice-bar is the service instance ID.

  • myservice is the service name. The service name is the character string after v1/ in the REST endpoint URL, up to (but excluding) the first hyphen.

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://foo.storage.oraclecloud.com).

Constructing the user Parameter

To obtain authentication to access Oracle Storage Cloud Service, you must construct the user parameter using the user name and the REST API endpoint URL.

Append the user name that you obtained from the account creation email to the service instance ID that you obtained from the REST API endpoint URL to construct the user parameter.

For example, say the REST API endpoint URL for you service instance is https://foo.storage.oraclecloud.com/v1/myservice-bar and the user name is jack.jones@examples.com, then the user parameter would be:

user=myservice-bar: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 My Services.
  • To create, update, and delete the Oracle Storage Cloud Service containers, you must have the Storage_Administrator role.

  • To create, update, and delete the Oracle Storage 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://foo.storage.oraclecloud.com
    
    # service name
    service=myservice
    
    #identity domain name or tenant name
    identity-domain=myIdentity3
    
    # storage service user
    user=myservice-bar:jack.jones@example.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 The user parameter 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 My Services. See Getting Your Required Roles.

    service The cloud service name.
    identity-domain The identity domain of your service instance.
    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 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 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 REST API Endpoint URL.
    export FTM_AUTH_URL=https://foo.storage.oraclecloud.com
    
  2. Store your user parameter in the environment variable FTM_USER.
    To construct your user paramater, follow the instructions at Constructing the user Parameter.
    export FTM_USER=myservice-bar: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.
    To find out the service name of your Oracle Storage Cloud Service instance, follow the instructions at REST API Endpoint URL.
    export FTM_SERVICE=myservice
    
  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