Preparing for Appliance Data Transfers

Prepare phase indicator for appliance transfer

This topic describes the tasks associated with preparing for the Appliance-Based Data Import job. The Project Sponsor role typically performs these tasks. See Roles and Responsibilities.

Note

You can only run Oracle Cloud Infrastructure CLI commands from a Linux host. This differs from running CLI commands for other Oracle Cloud Infrastructure Services on a variety of host operating systems. Appliance-based commands require validation that is only available on Linux hosts.

Installing and Using the Oracle Cloud Infrastructure Command Line Interface

The Oracle Cloud Infrastructure Command Line Interface (CLI) provides a set of command line-based tools for configuring and running Appliance-Based Data Import. Use the Oracle Cloud Infrastructure CLI as an alternative to running commands from the Console. Sometimes you must use the CLI to complete certain tasks as there is no Console equivalent.

Minimum Required CLI Version

The minimum CLI version required for Appliance-Based Data Import is 2.12.1.

Determining CLI Versions

Access the following URL to see the currently available version of the CLI:

https://github.com/oracle/oci-cli/blob/master/CHANGELOG.rst

Enter the following command at the prompt to see the version of the CLI currently installed on your machine:

oci --version

If you have a version on your machine older than the version currently available, install the latest version.

Note

Always update to the latest version of the CLI. The CLI is not updated automatically, and you can only access new or updated CLI features by installing the current version.

Installing the CLI

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

Using the CLI

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 command to create a transfer job shows a typical CLI command construct.

oci dts job create --compartment-id ocid1.compartment.oc1..exampleuniqueID --bucket MyBucket --display-name MyApplianceImportJob --device-type appliance
Note

In the previous examples, provide a friendly name for the transfer job using the ‑‑display‑name option. Avoid entering confidential information as part of the display name.

Accessing Command Line Interface Help

All CLI help commands have an associated help component you can access from the command line. To view the help, enter any command followed by the --help or -h option. For example:


oci dts job --help
			
NAME
  dts_job -

DESCRIPTION
  Transfer disk or appliance job operations

AVAILABLE COMMANDS
  o change-compartment
  o close
  o create
  o delete
  o detach-devices-details
  ...

When you run the help option (--help or -h) for a specified command, all the subordinate commands and options for that level of CLI are displayed. If you want to access the CLI help for a specific subordinate command, include it in the CLI string, for example:


oci dts job create --help
			
NAME
  dts_job_create -

DESCRIPTION
  Creates a new transfer disk or appliance job.

USAGE
  oci dts job create [OPTIONS]

REQUIRED PARAMETERS
  --bucket [text]

Upload bucket name

--compartment-id, -c [text]

Compartment OCID

--device-type [text]

Creating the Required IAM Users, Groups, and Policies

Each service in Oracle Cloud Infrastructure integrates with IAM for authentication and authorization.

To use Oracle Cloud Infrastructure, you must be given the required type of access in a policy  written by an administrator, whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you try to perform an action and get a message that you don’t have permission or are unauthorized, confirm with your administrator the type of access you've been granted and which compartment  you should work in.

Access to resources is provided to groups using policies and then inherited by the users that are assigned to those groups. Data transfer requires the creation of two distinct groups:

  • Data transfer administrators who can create and manage transfer jobs.
  • Data transfer upload users who can upload data to Object Storage. For your data security, the permissions for upload users allow Oracle personnel to upload standard and multi-part objects on your behalf and inspect bucket and object metadata. The permissions do not allow Oracle personnel to inspect the actual data.

The Data Administrator is responsible for generating the required RSA keys needed for the temporary upload users. These keys should never be shared between users.

For details on creating groups, see Managing Groups.

An administrator creates these groups with the following policies:

  • The data transfer administrator group requires an authorization policy that includes the following:

    Allow group <group_name> to manage data-transfer-jobs in compartment <compartment_name>
    Allow group <group_name> to manage objects in compartment <compartment_name>
    Allow group <group_name> to manage buckets in compartment <compartment_name>

    Alternatively, you can consolidate the manage buckets and manage objects policies into the following:

    Allow group <group_name> to manage object-family in compartment <compartment_name>
  • The data transfer upload user group requires an authorization policy that includes the following:

    Allow group <group_name> to manage buckets in compartment <compartment_name> where all { request.permission='BUCKET_READ', target.bucket.name='<bucket_name>' }
    Allow group <group_name> to manage objects in compartment <compartment_name> where all { target.bucket.name='<bucket_name>', any { request.permission='OBJECT_CREATE', request.permission='OBJECT_OVERWRITE', request.permission='OBJECT_INSPECT' }}

To enable notifications, add the following policies:

Allow group <group name> to manage ons-topics in tenancy
Allow group <group name> to manage ons-subscriptions in tenancy
Allow group <group name> to manage cloudevents-rules in tenancy
Allow group <group name> to inspect compartments in tenancy

See Notifications Overview and Overview of Events for more information.

The Oracle Cloud Infrastructure administrator then adds a user to each of the data transfer groups created. For details on creating users, see Managing Users.

Important

For security reasons, we recommend that you create a unique IAM data transfer upload user for each transfer job and then delete that user once your data is uploaded to Oracle Cloud Infrastructure.

Requesting Appliance Entitlement

If your tenancy is not entitled to use the Data Transfer Appliance, you must request the Data Transfer Appliance Entitlement before creating an appliance-based transfer job.

Establishing the Data Transfer Appliance Entitlement Policy

Use the following policy to enable users in a specific group to request a Data Transfer Appliance Entitlement in your tenancy.

Allow group <group_name> to {DTA_ENTITLEMENT_CREATE} in tenancy

Entitlement Eligibility

Your request for a Data Transfer Appliance Entitlement in your tenancy may be denied if you are a free trial customer. If your request is denied, upgrade to a full account. You can also contact your Oracle Customer Support Manager or Oracle Support to determine your options for obtaining the entitlement.

Requesting the Appliance Entitlement

To request the Data Transfer Appliance Entitlement using the Console

Open the Transfer Job page and click Request at the top. Otherwise, you are prompted to request the entitlement when attempting to create your first appliance-based transfer job.

Once requested, the status of your request is visible at the top of the Transfer Job page. For example:

Data Transfer Appliance Entitlement: Granted

It can take a while to get the Data Transfer Appliance Entitlement approved. After Oracle receives your request, a Terms and Conditions Agreement is sent to the account owner via DocuSign to use the appliance. The entitlement request is approved once the signature is received. The Data Transfer Appliance Entitlement is a tenancy-wide entitlement that you need to request once for each tenancy.

To request the Data Transfer Appliance Entitlement using the CLI
oci dts appliance request-entitlement --compartment-id <compartment_id> --name <name> --email <email>

<name> is the name of the requester.

<email> is the email address of the requester.

For example:

oci dts appliance request-entitlement --compartment-id ocid.compartment.oc1..exampleuniqueID --name "John Doe" --email jdoe@mycompany.com
					
{
  "data": {
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "creation-time": "2019-12-18T18:29:15+00:00",
	"defined-tags": {},
	"display-name": null,
	"freeform-tags": {},
	"id": "ocid1.datatransferapplianceentitlement.oc1..exampleuniqueID",
	"lifecycle-state": "CREATING",
	"lifecycle-state-details": "REQUESTED",
	"requestor-email": "jdoe@mycompany.com",
	"requestor-name": "John Doe",
    "update-time": "2019-12-20T19:04:09+00:00"
  }
}
To show the status of a Data Transfer Appliance Entitlement request using the CLI
oci dts appliance show-entitlement --compartment-id <compartment_id>

For example:

oci dts appliance show-entitlement --compartment-id ocid.compartment.oc1..exampleuniqueID 
{
  "data": {
    "compartment-id": ""ocid.compartment.oc1..exampleuniqueID",
    "defined-tags": null,
    "display-name": null,
    "freeform-tags": null,
    "id": null,
    "lifecycle-state": "ACTIVE",
    "lifecycle-state-details": "APPROVED",
    "requestor-email": "jdoe@mycompany.com",
    "requestor-name": "John Doe"
  }
}

Creating Object Storage Buckets

The Object Storage service is used to upload your data to Oracle Cloud Infrastructure. Object Storage stores objects in a container called a bucket within a compartment  in your tenancy. For details on creating the bucket to store uploaded data, see Managing Buckets.

Configuring Firewall Settings

Ensure that your local environment's firewall can communicate with the Data Transfer Service running on the IP address ranges: 140.91.0.0/16. You also need to open access to the Object Storage IP address ranges: 134.70.0.0/17.

Creating Transfer Jobs

This section describes how to create a transfer job as part of the preparation for the data transfer. See Transfer Jobs for complete details on all tasks related to transfer jobs.

A transfer job represents the collection of files that you want to transfer and signals the intention to upload those files to Oracle Cloud Infrastructure. Identify which compartment and Object Storage bucket to which Oracle is to upload your data. Create the transfer job in the same compartment as the upload bucket and supply a human-readable name for the transfer job. Avoid entering confidential information when providing transfer job names.

Note

It is recommended that you create a compartment for each transfer job to minimize the required access your tenancy.

Creating a transfer job returns a transfer job ID that you specify in other transfer tasks. For example:

ocid1.datatransferjob.region1.phx..<unique_ID>
To create a transfer job using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and click Data Transfer - Imports.
  2. Select the designated compartment you are to use for data transfers from the list.

    A list of transfer jobs that have already been created is displayed.

  3. Click Create Transfer Job.

    The Create Transfer Job dialog appears.

  4. Enter a Job Name, and select the Upload Bucket from the list.

    Avoid entering confidential information in the transfer job name.

  5. Select Appliance for the Transfer Device Type.
  6. Click Create Transfer Job.
To create a transfer job using the CLI
oci dts job create --bucket <bucket> --compartment-id <compartment_id> --display-name <display_name> --device-type <device_type>
<display_name> is the name of the transfer job. Avoid entering confidential information in your transfer job name. <device_type> should always be appliance for Appliance-Based Data Import jobs.

For example:

oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-name MyApplianceImportJob --device-type appliance
				
{
  "data": {
    "attached-transfer-appliance-labels": [],
    "attached-transfer-device-labels": [],
    "attached-transfer-package-labels": [],
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "creation-time": "2019-12-18T19:43:58+00:00",
    "defined-tags": {},
    "device-type": "APPLIANCE",
    "display-name": "MyApplianceImportJob",
    "freeform-tags": {},
    "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
    "label": "JAKQVAGJF",
    "lifecycle-state": "INITIATED",
    "upload-bucket-name": "MyBucket1"
  },
  "etag": "2--gzip"
}

Optionally, you can specify one or more defined or freeform tags when you create a transfer job. For more information about tagging, see Resource Tags.

Defined Tags

To specify defined tags when creating a job:

oci dts job create --bucket <bucket> --compartment-id <compartment_id> --display-name <display_name> --device-type appliance --defined-tags '{ "<tag_namespace>": { "<tag_key>":"<value>" }}'

For example:

oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-name MyApplianceImportJob --device-type appliance --defined-tags '{"Operations": {"CostCenter": "01"}}'
				
{
"data": {
  "attached-transfer-appliance-labels": [],
  "attached-transfer-device-labels": [],
  "attached-transfer-package-labels": [],
  "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
  "creation-time": "2019-12-18T19:43:58+00:00",
  "defined-tags": {
    "operations": {
      "costcenter": "01"
    }
  },
  "device-type": "APPLIANCE",
  "display-name": "MyApplianceImportJob",
  "freeform-tags": {},
  "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
  "label": "JAKQVAGJF",
  "lifecycle-state": "INITIATED",
  "upload-bucket-name": "MyBucket1"
  },
  "etag": "2--gzip"
}
Freeform Tags

To specify freeform tags when creating a job:

oci dts job create --bucket <bucket> --compartment-id <compartment_id> --display-name <display_name> --device-type appliance --freeform-tags '{ "<tag_key>":"<value>" }'				

For example:

oci dts job create --bucket MyBucket1 --compartment-id ocid.compartment.oc1..exampleuniqueID --display-name MyApplianceImportJob --device-type appliance --freeform-tags '{"Pittsburg_Team":"brochures"}'
				
{
"data": {
  "attached-transfer-appliance-labels": [],
  "attached-transfer-device-labels": [],
  "attached-transfer-package-labels": [],
  "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
  "creation-time": "2019-12-18T19:43:58+00:00",
  "defined-tags": {},
  "device-type": "APPLIANCE",
  "display-name": "MyApplianceImportJob",
  "freeform-tags": {
	"Pittsburg_Team": "brochures"
  },
  "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
  "label": "JAKQVAGJF",
  "lifecycle-state": "INITIATED",
  "upload-bucket-name": "MyBucket1"
  },
  "etag": "2--gzip"
}
Note

Users create tag namespaces and tag keys with the required permissions. These items must exist before you can specify them when creating a job. See Working with Defined Tags for details.
Multiple Tags

To specify multiple tags, comma separate the JSON-formatted key/value pairs:

oci dts job create --bucket <bucket> --compartment-id <compartment_id> --display-name <display_name> --device-type appliance --freeform-tags '{ "<tag_key>":"<value>" }', '{ "<tag_key>":"<value>" }'

Notifications

To include notifications, include the --setup-notifications option. See Setting Up Transfer Job Notifications from the CLI for more information on this feature.

Getting Transfer Job IDs

Each transfer job you create has a unique ID within Oracle Cloud Infrastructure. For example:

ocid1.datatransferjob.oc1.phx.exampleuniqueID

You will need to forward this transfer job ID to the Data Administrator.

To get the transfer job ID using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and click Data Transfer - Imports.
  2. Select the Compartment from the list.

    The transfer jobs in that compartment are displayed.

  3. Click the link under Transfer Jobs for the transfer job whose details you want to view.

    Alternatively, you can click the Actions icon (Actions icon), and then click View Details.

    The Details page for that transfer job appears.

  4. Find the OCID field in the Details page and click Show to display it or Copy to copy it to your computer.

To get the transfer job ID using the CLI
oci dts job list --compartment-id <compartment_id>

For example:

oci dts job list --compartment-id ocid.compartment.oc1..exampleuniqueID
					
{
  "data": [
    {
      "creation-time": "2019-12-18T19:43:58+00:00",
      "defined-tags": {},
      "device-type": "APPLIANCE",
      "display-name": "MyApplianceImportJob",
      "freeform-tags": {},
      "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
      "label": "JAKQVAGJF",
      "lifecycle-state": "INITIATED",
      "upload-bucket-name": "MyBucket1"
    },
    {
      "creation-time": "2019-10-03T16:52:26+00:00",
      "defined-tags": {},
      "device-type": "DISK",
      "display-name": "MyDiskImportJob",
      "freeform-tags": {},
      "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
      "label": "J2AWEOL5T",
      "lifecycle-state": "INITIATED",
      "upload-bucket-name": "MyBucket2"
    }
  ]
}

The ID for each transfer job is included in the return:

"id": "ocid.compartment.oc1..exampleuniqueID"
Tip

When you create a transfer job using the oci dts job create CLI, the transfer job ID is displayed in the CLI's return. You can also run the oci dts job show CLI for that specific job to get the ID.

Setting Up Transfer Job Notifications from the CLI

You can generate notifications that send messages regarding changes to a transfer job by using the setup-notifications command through the CLI. Running this command creates a topic, subscription for a list of email addresses, and a rule that notifies you on all events related to the transfer job's activities and changes in state. This method provides a more convenient way to generate notifications tailored to appliance-based transfer jobs.

Running the CLI command prompts you to enter the email addresses of each notification subscriber as a comma separated list. Each recipient is sent an email with a link to confirm they want to receive the notifications.

You can set up notifications when you create a transfer job using the CLI. You can also set up notifications for existing transfer jobs.

Setting up Notifications for a New Transfer Job

To set up notifications when creating a transfer job, include the --setup-notifications option in the CLI:

oci dts job create --bucket <bucket_name> --compartment-id <compartment_id> --display-name <display_name> --device-type appliance ... --setup-notifications

Setting up Notifications for an Existing Transfer Job

To set up notifications for an existing transfer job, run the job setup-notifications CLI on the job:

oci dts job setup-notifications --job-id <job_id>

You are prompted to enter those email addresses you want included in the notifications, separated by commas (","). When your list is complete, add a colon (":") followed by your own email address: user1@mycompany.com,user2@mycompany.com : myemail@mycompany.com.

For example:

oci dts job setup-notifications --job-id ocid1.datatransferjob.oc1..exampleuniqueID

If the commands fail to run, you can use the OCI CLI to do the setup manually:
oci ons topic create --compartment-id ocid1.tenancy.oc1..exampleuniqueID --name MyImportJob --description "Topic for data transfer service import job with OCID ocid1.datatransferjob.oc1..exampleuniqueID"
oci ons subscription create --protocol EMAIL --compartment-id $ROOT_COMPARTMENT_OCID --topic-id $TOPIC_OCID --subscription_endpoint $EMAIL_ID
oci events rule create --display-name MyImportJob --is-enabled true--compartment-id ocid1.tenancy.oc1..exampleuniqueID --actions '{"actions":[{"actionType":"ONS","topicId":"$TOPIC_OCID","isEnabled":true}]}' --condition '{"eventType":"com.oraclecloud.datatransferservice.*transferjob","data":{"resourceId":"ocid1.datatransferjob.oc1..exampleuniqueID"}}' --description "Rule for data transfer service to send notifications for an import job with OCID ocid1.datatransferjob.oc1..exampleuniqueID"
Creating topic DTSImportJobTopic_2pwaqq

{
  "data": {
    "api-endpoint": "https://cell1.notification.us-phoenix-1.oraclecloud.com",
    "compartment-id": "ocid1.tenancy.oc1..exampleuniqueID",
    "defined-tags": {},
    "description": "Topic for data transfer service import job with OCID ocid1.datatransferjob.oc1..exampleuniqueID",
    "etag": null,
    "freeform-tags": {},
    "lifecycle-state": "ACTIVE",
    "name": "DTSImportJobTopic_2pwaqq",
    "time-created": "2020-07-15T18:26:07.179000+00:00",
    "topic-id": "ocid1.onstopic.oc1..exampleuniqueID"
  },
  "etag": "2e5a567d"
}

Enter email addresses to subscribe to as a comma separated list. Example: jdoe@mycompany.com,rroe@mycompany.com : jsmith@mycompany.com
Creating subscription for jsmith@mycompany.com
{
  "data": {
    "compartment-id": "ocid1.tenancy.oc1..exampleuniqueID",
    "created-time": 1594837577401,
    "defined-tags": {},
    "deliver-policy": "{\"maxReceiveRatePerSecond\":0,\"backoffRetryPolicy\":{\"initialDelayInFailureRetry\":60000,\"maxRetryDuration\":7200000,\"policyType\":\"EXPONENTIAL\"}}",
    "endpoint": "jsmith@mycompany.com",
    "etag": "cac2f405",
    "freeform-tags": {},
    "id": "ocid1.onssubscription.oc1..exampleuniqueID",
    "lifecycle-state": "PENDING",
    "protocol": "EMAIL",
    "topic-id": "ocid1.onstopic.oc1..exampleuniqueID"
  },
  "etag": "cac2f405"
}

Creating rule DTSImportJobRule_2pwaqq
{
  "data": {
    "actions": {
    "actions": [
      {
        "action-type": "ONS",
        "description": null,
        "id": "ocid1.eventaction.oc1..exampleuniqueID",
        "is-enabled": true,
        "lifecycle-message": null,
        "lifecycle-state": "ACTIVE",
        "topic-id": "ocid1.onstopic.oc1..exampleuniqueID"
      }
    ]
  },
    "compartment-id": "ocid1.tenancy.oc1..exampleuniqueID",
    "condition": "{\"eventType\":\"com.oraclecloud.datatransferservice.*transferjob\",\"data\":{\"resourceId\":\"ocid1.datatransferjob.oc1..exampleuniqueID\"}}",
    "defined-tags": {},
    "description": "Rule for data transfer service to send notifications for an import job with OCID ocid1.datatransferjob.oc1..exampleuniqueID",
    "display-name": "DTSImportJobRule_2pwaqq",
    "freeform-tags": {},
    "id": "ocid1.eventrule.oc1..exampleuniqueID",
    "is-enabled": true,
    "lifecycle-message": null,
    "lifecycle-state": "ACTIVE",
    "time-created": "2020-07-15T18:26:18.307000+00:00"
  },
  "etag": "aff873bfb4015b49902b97c7a6cc40588bf89b9e3deeb27b77ecce6d7a99768a"
}

Preparing Upload Configuration Files

The Project Sponsor is responsible for creating or obtaining configuration files that allow the uploading of user data to the import appliance. Send these configuration files to the Data Administrator where they can be placed in the Control Host (if there are separate Control and Data Hosts).The config file is for the data transfer administrator, the IAM user with the authorization and permissions to create and manage transfer jobs. The config_upload_user file is for the data transfer upload user, the temporary IAM user that Oracle uses to upload your data on your behalf.

Create a base Oracle Cloud Infrastructure directory and two configuration files with the required credentials.

Creating the Data Transfer Directory

Create a Oracle Cloud Infrastructure directory (.oci) on the same Control Host machine where the Oracle Cloud Infrastructure CLI is installed. For example:

mkdir /root/.oci/

The two configuration files (config and config_upload_user) are placed in what ever location you choose.

Note

You can store the configuration files anywhere on your Control Host. The root directory is only given as an example.

Creating the Data Transfer Administrator Configuration File

The data transfer administrator configuration file contains the required credentials for working with Oracle Cloud Infrastructure. You can create this file using a setup CLI or manually using a text editor.

Using the Setup CLI

Run the oci setup config command line utility to walk through the first-time setup process. The command prompts you for the information required for the configuration file and the API public/private keys. The setup dialog generates an API key pair and creates the configuration file.

For more information about how to find the required information, see:

Manual Setup

If you want to set up the API public/private keys yourself and write your own configuration file, see SDK and Tool Configuration.

Tip

Use the oci setup keys command to generate a key pair to include in the config file.

Create the 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, and ap-osaka-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..exampleuniqueID.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..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
[PROFILE1]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-ashburn-1

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

oci dts job create --compartment-id ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-name MyDisplay --device-type 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 ocid.compartment.oc1..exampleuniqueID --bucket MyBucket --display-name MyDisplay --device-type appliance --profile MyProfile

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

If you created two separate configuration files, use the following command to specify the configuration file to use:

oci dts job create --compartment-id <compartment_id> --bucket <bucket_name> --display-name <display_name> --config 
                
                

Creating the Data Transfer Upload User Configuration File

The config_upload_user configuration file is for the data transfer upload user, the temporary IAM user that Oracle uses to upload your data on your behalf. Create this 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, and ap-osaka-1.>

Adding Object Storage Endpoints

Include the line endpoint=<url> for the Object Storage API endpoint in the upload user configuration file.

For example:

endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com

Click here to view a list of endpoints.

A complete configuration including the Object Storage endpoint might look like this:

[DEFAULT]
user=ocid1.user.oc1..exampleuniqueID
fingerprint=4c:1a:6f:a1:5b:9e:58:45:f7:53:43:1f:51:0f:d8:45
key_file=/home/user/ocid1.user.oc1..exampleuniqueID.pem
tenancy=ocid1.tenancy.oc1..exampleuniqueID
region=us-phoenix-1
endpoint=https://objectstorage.us-phoenix-1.oraclecloud.com
Important

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

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 East (Ashburn), US West (Phoenix), Germany Central (Frankfurt), and UK South (London).

Yes

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

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

Requesting the Import Appliance

This section describes how to request an import appliance from Oracle for copying your data to Oracle Cloud Infrastructure See Import Appliances for complete details on all tasks related to transfer jobs.

Oracle Cloud Infrastructure customers can use import appliances to migrate data for free. You are only charged for Object Storage usage once the data is successfully transferred to your designated bucket. All appliance requests still require approval from Oracle.

Tip

To save time, identify the data you intend to upload and make data copy preparations before requesting the import appliance.

Creating an appliance request returns an Oracle-assigned appliance label. For example:

XA8XM27EVH
To request an appliance using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and click Data Transfer - Imports.

    Choose the transfer job that for which you want to request an import appliance.

  2. Click Request Transfer Appliance under Transfer Appliances.

    The Request Transfer Appliance dialog appears.

  3. Provide the shipping address details where you want the import appliance sent.

    • Company Name: Required. Specify the name of the company that owns the data being migrated to Oracle Cloud Infrastructure.
    • Recipient Name: Required. Specify the name of the recipient of the import appliance.
    • Recipient Phone Number: Required. Specify the recipient's phone number.
    • Recipient Email Address: Required. Specify the recipient's email address.
    • Care Of: Optional intermediary party responsible for transferring the import appliance shipment from the delivery vendor to the intended recipient.
    • Address Line 1: Required. Specify the street address to where the import appliance is sent.
    • Address Line 2: Optional identifying address details like building, suite, unit, or floor information.
    • City/Locality: Required. Specify the city or locality.
    • State/Province/Region: Required. Specify the state, province, or region.
    • Zip/Postal Code: Specify the zip code or postal code.
    • Country: Required. Select the country.
  4. Click Request Transfer Appliance.
To request an appliance using the CLI
oci dts appliance request --job-id <job_id> --addressee <addressee> --care-of <care_of> --address1 <address_line1> --city-or-locality <city_or_locality> --state-province-region <state_province_region> --country <country> --zip-postal-code <zip_postal_code> --phone-number <phone_number> --email <email> <options>
<options> are:
  • --address2: Optional address of the addressee (line 2).
  • --address3: Optional address of the addressee (line 3).
  • --address4: Optional address of the addressee (line 4).
  • --from-json: Provide input to this command as a JSON document from a file using the file://path-to/file syntax. The --generate-full-command-json-input option can be used to generate a sample JSON file to be used with this command option. The key names are pre-populated and match the command option names (converted to camelCase format, e.g. compartment-id --> compartmentId), while the values of the keys need to be populated by the user before using the sample file as an input to this command. For any command option that accepts multiple values, the value of the key can be a JSON array. Options can still be provided on the command line. If an option exists in both the JSON document and the command line then the command line specified value will be used. For examples on usage of this option, please see our "using CLI with advanced JSON options" link: https://docs.cloud.oracle.com/iaas/Content/API/SDKDocs/cliusing.htm#AdvancedJSONOptions.

For example:

oci dts appliance request --job-id ocid1.datatransferjob.oc1..exampleuniqueID --addressee MyCompany --care-of "John Doe" --address1 "123 Main Street" --city-or-locality Anytown --state-province-region NY --country USA --zip-postal-code 12345 --phone-number 8005551212 --email john.doe@mycompany.com
				
{
  "data": {
    "appliance-delivery-tracking-number": null,
    "appliance-delivery-vendor": null,
    "appliance-return-delivery-tracking-number": null,
    "creation-time": "2020-05-20T22:08:13+00:00",
    "customer-received-time": null,
    "customer-returned-time": null,
    "customer-shipping-address": {
      "address1": "123 Main Street",
      "address2": null,
      "address3": null,
      "address4": null,
      "addressee": "MyCompany",
      "care-of": "John Doe",
      "city-or-locality": "Anytown",
      "country": "USA",
      "email": "john.doe@mycompany.com",
      "phone-number": "3115551212",
      "state-or-region": "NY",
      "zipcode": "12345"
    },
    "delivery-security-tie-id": null,
    "label": "XAKWEGKZ5T",
    "lifecycle-state": "REQUESTED",
    "next-billing-time": null,
    "return-security-tie-id": null,
    "serial-number": null,
    "transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
    "upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
  }
}

When you submit an appliance request, Oracle generates a unique label (label": "XAKWEGKZ5T) to identify the import appliance and your request is sent to Oracle for approval and processing.

Setting Up Import Appliance Request Notifications from the CLI

You can generate notifications that send messages regarding changes to your import appliance request by using the setup-notifications command through the CLI. Running this command creates a topic, subscription for list of email addresses, and also a rule that notifies you on all events related to the import appliance request's activities and changes in state. This method provides a more convenient way to generate notifications tailored to import appliance requests.

Running the CLI command prompts you to enter the email addresses of each notification subscriber as a comma separated list. Each recipient is sent an email with a link to confirm they want to receive the notifications.

Note

Setting up notifications from the CLI affects all import appliances in your tenancy. You cannot specify notifications for individual appliances.

Setting Up Notifications for a New Import Appliance Request

To include job notifications when requesting an import appliance, include the --setup-notifications option in the CLI:

oci dts appliance request --job-id <job_id> --addressee <addressee> --address1 <address_line1> --city-or-locality <city_or_locality> --state-or-region <state_or_region> --country <country> --zip-code <zip> ... --setup-notifications

Setting up Notifications for an Existing Import Appliance Request

To set up notifications for an existing import appliance request, run the appliance setup-notifications CLI on the appliance:

oci dts appliance setup-notifications --appliance-label <appliance_label>

Notifying the Data Administrator

When you have completed all the tasks in this topic, provide the Data Administrator of the following:

  • IAM login credentials
  • Oracle Cloud Infrastructure CLI configuration files
  • Transfer job ID
  • Appliance label