Oracle Cloud Infrastructure Documentation

Preparing Your Host for Appliance-based Data Transfers

This topic describes various preparations you must do on your host before running application-based data transfers.

Installing and Using Command Line Utilities

Important

With this release, the Data Transfer Appliance uses the Oracle Cloud Infrastructure command line interface (CLI) for all command line-based tasks. The Data Transfer Utility no longer supports appliance-based transfer jobs. You can still use Data Transfer Utility commands for HDD-based data transfers.

Installation and configuration of the CLIs is described in detail in Command Line Interface (CLI).

Using CLIs

The CLIs must be run as the root user.

You can specify CLI options using the following commands:

  • --option <value> or
  • --option=<value>

The basic CLI syntax is:

oci dts <resource> <action> <options>

This syntax is applied to the following:

  • oci dts is the shortened CLI command name
  • job is an example of a <resource>
  • create is an example of an <action>
  • Other strings are <options>

The following commands to create a transfer job shows a typical CLI command construct.

oci dts job create --compartment-id ocid1.compartment.oc1..<unique_ID> --display-name "mycompany transfer1" ‑‑bucket mybucket --device-type appliance 

Or:

oci dts job create --compartment-id=ocid1.compartment.oc1..<unique_ID> --display-name="mycompany transfer1" ‑‑bucket=mybucket --device-type=appliance 
Note

In the previous examples, provide a friendly name for the transfer job using the ‑‑display‑name option. Avoid entering

Setting Up Terminal Emulation

Appliance-based transfers require you to set up your host for terminal emulation so you can communicate with the appliance device through the appliance's serial console. This communication requires installing serial console terminal emulator software. We recommend using the following:

  • PuTTY for Windows
  • ZOC for OS X
  • PuTTY or Minicom for Linux

Configure the following terminal emulator software settings:

  • Baud Rate: 115200
  • Emulation: VT102
  • Handshaking: Disabled/off
  • RTS/DTS: Disabled/off

Setting Your Host as an NFS Client

Set up your host as an NFS client:

  • For Debian or Ubuntu, install the nfs-common package. For example:
    sudo apt-get install nfs-common
  • For Oracle Linux or Red Hat Linux, install the nfs-utils package. For example:
    sudo yum install nfs-utils

Setting Up an HTTP Proxy Environment

You might need to set up an HTTP proxy environment to allow access to the public internet so the Data Transfer Utility can communicate with the Data Transfer Appliance Management Service and the transfer appliance over a local network connection. If your environment requires internet-aware applications to use network proxies, configure the host to use your environment's network proxies by setting the standard Linux environment variables on your host machine.

Assume that your organization has a corporate internet proxy at http://www-proxy.myorg.com and that the proxy is an HTTP address at port 80. You would set the following environment variable:

export HTTPS_PROXY=http://www-proxy.myorg.com:80

If you configured a proxy on the host machine and the transfer appliance is directly connected to that host, the host machine tries unsuccessfully to communicate with the transfer appliance using a proxy. Set a no_proxy environment variable for the transfer appliance. For example, if the appliance is on a local network at 10.0.0.1, you would set the following environment variable:

export NO_PROXY=10.0.0.1

Preparing Configuration Files

Before using the CLIs for appliance-based data transfers, you must create a base Oracle Cloud Infrastructure directory and two configuration files with the required credentials. One configuration file is for the data transfer administrator, the IAM user with the authorization and permissions to create and manage transfer jobs. The other configuration file is for the data transfer upload user, the temporary IAM user that Oracle uses to upload your data on your behalf.

Base Data Transfer Directory

Create a base Oracle Cloud Infrastructure directory:

mkdir /root/.oci/

Configuration File for the Data Transfer Administrator

Create a data transfer administrator configuration file /root/.oci/config with the following structure:

[DEFAULT]
user=<The OCID for the data transfer administrator>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are: us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>

For example:

[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1

For the data transfer administrator, you can create a single configuration file that contains different profile sections with the credentials for multiple users. Then use the ‑‑profile option to specify which profile to use in the command. Here is an example of a data transfer administrator configuration file with different profile sections:

[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-ashburn-1

Important

Creating an upload user configuration file with multiple profiles is not supported.

By default, the DEFAULT profile is used for all CLI commands. For example:

oci dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name> --device-type <disk_or_appliance>

Instead, you can issue any CLI command with the --profile option to specify a different data transfer administrator profile. For example:

oci dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name> --device-type <disk_or_appliance> --profile <profile_name>

Using the example configuration file above, the <profile_name> would be profile1.

Configuration File for the Data Transfer Upload User

Create a data transfer upload user /root/.oci/config_upload_user configuration file with the following structure:

[DEFAULT]
user=<The OCID for the data transfer upload user>
fingerprint=<The fingerprint of the above user's public key>
key_file=<The _absolute_ path to the above user's private key file on the host machine>
tenancy=<The OCID for the tenancy that owns the data transfer job and bucket>
region=<The region where the transfer job and bucket should exist. Valid values are: us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.>

For example:

[DEFAULT]
user=ocid1.user.oc1..<unique_ID>
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..<unique_ID>.pem
tenancy=ocid1.tenancy.oc1..<unique_ID>
region=us-phoenix-1

Configuration File Entries

The following table lists the basic entries that are required for each configuration file and where to get the information for each entry.

Note

Data Transfer Service does not support passphrases on the key files for both data transfer administrator and data transfer upload user.

Entry Description and Where to Get the Value Required?
user

OCID of the data transfer administrator or the data transfer upload user, depending on which profile you are creating. To get the value, see Required Keys and OCIDs.

Yes
fingerprint

Fingerprint for the key pair being used. To get the value, see Required Keys and OCIDs.

Yes
key_file

Full path and filename of the private key.

Important: The key pair must be in PEM format. For instructions on generating a key pair in PEM format, see Required Keys and OCIDs.

Yes
tenancy

OCID of your tenancy. To get the value, see Required Keys and OCIDs.

Yes
region

An Oracle Cloud Infrastructure region. See Regions and Availability Domains.

Data transfer is supported in us-ashburn-1, us-phoenix-1, eu-frankfurt-1, and uk-london-1.

Yes

You can verify the data transfer upload user credentials using the following command:

oci dts job verify-upload-user-credentials --bucket <bucket_name>

Configuration File Location

The location of the configuration files is /root/.oci/config.

What's Next

You are now ready to perform disk-based data transfers. See Managing Appliance Data Transfers.