Appliance Import Reference

This topic provides complete task details for certain components associated with Appliance-Based Data Imports. Use this topic as a reference to learn and use commands associated with components included in the Appliance-Based Data Import procedure.

Transfer Jobs

A transfer job is the logical representation of a data migration to Oracle Cloud Infrastructure. A transfer job is associated with one or more import appliances.

Note

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

Creating Transfer Jobs

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.

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

ocid1.datatransferjob.oci1..exampleuniqueID
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.

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 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 Disk for the Transfer Device Type.
  6. Click Create Transfer Job.

Listing Transfer Jobs

To display the list of transfer jobs 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.

To display the list of transfer jobs 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"
    }
  ]
}

When you use the CLI to list jobs, tagging details are also included in the output if you specified tags.

Displaying Transfer Job Details

To display the details of 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 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.

To display the details of a transfer job using the CLI
oci dts job show --job-id <job_id>

For example:

oci dts job show --job-id ocid1.datatransferjob.oc1..exampleuniqueID
					
{
  "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"
}

When you use the CLI command to display the details of a job, tagging details are also included in the output if you specified tags.

Editing Transfer Jobs

To edit the name of 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 Compartment from the list.

    The transfer jobs in that compartment are displayed.

  3. Click the link under Transfer Jobs for the transfer job whose name you want to edit.

    The Details page for that transfer job appears.

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

  4. Click Edit in the Details page.

    The Edit Transfer Job dialog appears.

  5. Edit the name of the transfer job.

    Avoid entering confidential information in the transfer job name.

  6. Click Edit Transfer Job.

You are returned to the Details page for that transfer job.

To edit the name of a transfer job using the CLI
oci dts job update --job-id <job_id> --display-name <display_name>

<display_name> is the new name of the transfer job.

For example:

oci dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --display-name MyRenamedJob
				
{
  "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": "MyRenamedJob",
    "freeform-tags": {},
    "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
    "label": "JAKQVAGJF",
    "lifecycle-state": "INITIATED",
    "upload-bucket-name": "MyBucket1"
  },
  "etag": "3"
}

Editing Transfer Job Tags

To edit the tags associated with a transfer job using the CLI

The CLI command replaces any existing tags with the new key/value pairs you specify. For more information about tagging, see Resource Tags.

To edit defined tags, provide the replacement key value pairs:

oci dts job update --job-id <job_id> --defined-tags '{ "<tag_namespace>": { "<tag_key>":"<value>" }}'

For example:

oci dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --defined-tags '{"Operations": {"CostCenter": "42"}}'
				
{
  "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": "42"
    }
  },
  "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"
}

To edit free-form tags, provide the replacement key/value pairs:

oci dts job update --job-id <job_id> --freeform-tags '{ "<tag_key>":"<value>" }'

For example:

oci dts job update --job-id ocid1.datatransferjob.oc1..exampleuniqueID --freeform-tags '{"Chicago_Team":"marketing_videos"}'
				
{
  "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": {
    "Chicago_Team": "marketing_videos"
  },  
  "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
  "label": "JAKQVAGJF",
  "lifecycle-state": "INITIATED",
  "upload-bucket-name": "MyBucket1"
  },
  "etag": "2--gzip"
}

Deleting Transfer Job Tags

To delete the tags associated with a transfer job using the CLI

The CLI command replaces any existing tags with the new key/value pairs you specify. If you want to delete some of the tags, specify a new tag string that does not contain the unwanted key/value pairs.

To delete all free-form tags:

oci dts job update --job-id <job_id> --freeform-tags '{}'

To delete all defined tags:

oci dts job update --job-id <job_id> --defined-tags '{}'

Moving Transfer Jobs Between Compartments

To move transfer job to a different compartment 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 that you want to move.

    The Details page for that transfer job appears.

    Alternatively, you can click the Actions icon (Actions icon), and then click Move Resource.

  4. Click Move Resource in the Details page.

    The Move Resource to a Different Compartment dialog appears.

  5. Choose the compartment you want to which you want to move the transfer job from the list.
  6. Click Move Resource.

You are returned to the Details page for that transfer job.

To move a transfer job to a different compartment using the CLI
oci dts job move --job-id <job_id> compartment-id <compartment_id> <options>

<compartment_id> is the compartment to which the data transfer job is being moved.

<options> are:

  • --if-match: The tag that must be matched for the task to occur for that entity. If set, the update is only successful if the object's tag matches the tag specified in the request.
  • --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 job move --job-id ocid1.datatransferjob.oc1..exampleuniqueID compartment-id ocid.compartment.oc1..exampleuniqueID

To confirm the transfer, display the list of transfer jobs in the new compartment. See Listing Transfer Jobs for more information.

Verifying Upload User Credentials

Note

You can only use the CLI command to verify upload user credentials.

You can verify the current upload user credentials to see whether there are any problems or updates required. If any configuration file is incorrect or invalid, the upload fails.

To verify the upload user credentials using the CLI
oci dts job verify-upload-user-credentials --bucket <bucket>

<bucket> is the upload bucket for the transfer job.

For example:

oci dts job verify-upload-user-credentials --bucket MyBucket1
					
created object BulkDataTransferTestObject in bucket MyBucket1
overwrote object BulkDataTransferTestObject in bucket MyBucket1
inspected object BulkDataTransferTestObject in bucket MyBucket1
read object BulkDataTransferTestObject in bucket MyBucket1

Depending on your user configuration, you may get an error message returned similar to the following:

WARNING: Permissions on /home/user/.oci/config_upload_user are too open. 
To fix this please try executing the following command: 
oci setup repair-file-permissions --file /home/user/.oci/config_upload_user 
Alternatively to hide this warning, you may set the environment variable, OCI_CLI_SUPPRESS_FILE_PERMISSIONS_WARNING: 
export OCI_CLI_SUPPRESS_FILE_PERMISSIONS_WARNING=True

ERROR: The config file at /home/user/.oci/config_upload_user is invalid:

+Config Errors+-----------+----------------------------------------------------------------------------------+
| Key         | Error     | Hint                                                                             |
+-------------+-----------+----------------------------------------------------------------------------------+
| fingerprint | malformed | openssl rsa -pubout -outform DER -in path to your private key | openssl md5 -c   |
+-------------+-----------+----------------------------------------------------------------------------------+

If a user credential issue is identified, fix it and rerun the verify-upload-user-credentials CLI to ensure that all problems are addressed. Then you can proceed with transfer job activities.

Deleting Transfer Jobs

You can delete transfer jobs when they are in the Initiated, Preparing, and Close states.

To delete 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 Compartment from the list.

    The transfer jobs in that compartment are displayed.

  3. Find the data transfer job that you want to delete.
  4. Click the Actions icon (Actions icon), and then click Delete.

    Alternatively, you can delete a transfer job from the View Details page.

  5. Confirm the deletion when prompted.
To delete a transfer job using the CLI
oci dts job delete --job-id <job_id>

For example:

oci dts job delete --job-id ocid1.datatransferjob.oc1..exampleuniqueID

Confirm the deletion when prompted. The transfer job is deleted with no further action or return. To confirm the deletion, display the list of transfer jobs in the compartment. See Listing Transfer Jobs for more information.

Closing Transfer Jobs

Typically, you would close a transfer job when no further transfer job activity is required or possible. Closing a transfer job requires that the status of all associated transfer packages be returned, canceled, or deleted. In addition, the status of all associated transfer disks must be complete, in error, missing, canceled, or deleted.

When you close the transfer job, the status changes to Closed.

To close 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 Compartment from the list.

    The transfer jobs in that compartment are displayed.

  3. Find the data transfer package for which you want to display the details.
  4. Click the Actions icon (Actions icon), and then click View Details.

    Alternatively, click the hyperlinked name of the transfer job.

  5. Click Close Transfer Job.
To close a transfer job using the CLI
oci dts job close --job-id <job_id>

For example:

oci dts job close --job-id ocid1.datatransferjob.oc1..exampleuniqueID
{					
  "data": {
    "attached-transfer-appliance-labels": [],
    "attached-transfer-device-labels": [],
    "attached-transfer-package-labels": [],
    "compartment-id": "ocid.compartment.oc1..exampleuniqueID",
    "creation-time": "2020-05-20T22:00:43+00:00",
    "defined-tags": {},
    "device-type": "APPLIANCE",
    "display-name": "MyApplianceImportJob",
    "freeform-tags": {},
    "id": "ocid1.datatransferjob.oc1..exampleuniqueID",
    "label": "JGX4N1XLI",
    "lifecycle-state": "CLOSED",
    "upload-bucket-name": "MyBucket"
  },
  "etag": "1"
}

Import Appliances

This section describes tasks associated with the Oracle-provided import appliance.

Requesting Appliances

Tip

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

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

XAKWEGKZ5T
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 for which you want to request an import appliance.

  2. Under Transfer Appliances, click Request Transfer Appliance.

    The Request Transfer Appliance dialog appears.

  3. Enter 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 who receives 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 where the import appliance is being 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 CLIs
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.

Monitoring the Appliance Request Status

The time it takes to approve, prepare, and ship your appliance request varies and depends on various factors, including current available inventory. Oracle provides status updates daily throughout the appliance request and ship process.

To monitor the status of your appliance request 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. Find and select the transfer job for which you want to monitor associated appliance requests.
  4. Under Transfer Appliances, find the appliance label Oracle assigned to your appliance request and look at the Status field.

Here are the key status values to look for when monitoring your appliance request:

  • Requested: You successfully completed your request for an import appliance. The status displays Requested until Oracle approves your appliance request.
  • Rejected: Oracle denied your appliance request.
Important

If your appliance request is denied and you have questions, contact your Sales Representative or file a Service Request (SR).
  • Oracle Preparing: Oracle approved your appliance request. The status displays Oracle Preparing until the import appliance is shipped to you.
  • Shipping: Oracle completed the necessary preparations and shipped your import appliance. When the import appliance is shipped, Oracle provides the serial number of the import appliance, the shipping vendor, and the tracking number in the Transfer Appliance Details. The status displays Shipping until the import appliance is delivered to you.
  • Delivered: The shipping vendor delivered your import appliance. When the import appliance is delivered, Oracle provides the date and time the import appliance was received in the Transfer Appliance Details. The status displays Delivered.
To monitor the status of your appliance request using the CLI
oci dts appliance show --job-id <job_id> --appliance-label <appliance label>

For example:

oci dts appliance show --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T
					
{
  "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"
  }
}

The request status is displayed as the value for lifecycle-state.

Displaying the List of Appliances

To display the list of appliances 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. Choose the transfer job for which you want to display the list of associated import appliances.

    The list of import appliances is displayed below the transfer job details.

To display the list of appliances using the CLI
oci dts appliance list --job-id <job_id>

For example:

oci dts appliance list --job-id ocid1.datatransferjob.oc1..exampleuniqueID
{
  "data": {
    "transfer-appliance-objects": [
      {
        "creation-time": "2020-05-20T22:08:13+00:00",
        "label": "XAKWEGKZ5T",
        "lifecycle-state": "PROCESSING",
        "serial-number": null
      }
    ]
  }
}

Displaying Appliance Details

To display the details of an appliance 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. Find the transfer job for which you want to display the details of an associated import appliance.

    The list of appliances is displayed below the transfer job details.

  4. Find the import appliance for which you want to display the details.
  5. Click the Actions icon (Actions icon), and then click View Details.
To display the details of an appliance using the CLI
oci dts appliance show --job-id <job_id> --appliance-label <appliance_label>

For example:

oci dts appliance show --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T
					
{
  "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": "exampleuniqueID",
    "label": "XAKWEGKZ5T",
    "lifecycle-state": "PROCESSING",
    "next-billing-time": null,
    "return-security-tie-id": "exampleuniqueID",
    "serial-number": "exampleuniqueserialnumber",
    "transfer-job-id": "ocid1.datatransferjob.oc1..exampleuniqueID",
    "upload-status-log-uri": "JAKQVAGJF/XAKWEGKZ5T/upload_summary.txt"
  }
}

Editing the Appliance Request Shipping Information

You can only edit the shipping information when the status is Requested.

To edit the appliance request shipping information using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and click Data Transfer - Imports.
  2. Find the Requested import appliance that you want to edit the shipping information.
  3. Click the Actions icon (Actions icon), and then click Edit.
  4. Edit the shipping information for the import appliance.
  5. Click Save.
To edit the appliance request shipping information using the CLI
oci dts appliance update-shipping-address --job-id <job_id> --appliance-label <appliance_label> --addressee <addressee> <changed_fields>

Include the addressee field even if it has not changed.

<changed_fields> represents one or more of the following shipping address fields that you want to update:

--care-of <care_of> --address1 <address> --city <city> --state <addressee> --zip <zip> --country <country> --phone-number <phone_number> email <email>

You only need to include those fields that are being updated. For example:

oci dts appliance update-shipping-address --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T --addressee MyCompany --care-of "Richard Roe" --phone-number 3115559876 --email richard.roe@mycompany.com

Confirm the update of the appliance request shipping information when prompted. The appliance details are displayed with the updated information.


{
  "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": "Richard Roe",
      "city-or-locality": "Anytown",
      "country": "USA",
      "email": "john.doe@oracle.com",
      "phone-number": "3115559876",
      "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"
  }
}

Deleting an Appliance Request

You can delete an appliance request before Oracle approves the request—the status must be Requested. For example, you initiated the transfer by creating a transfer job and requested an appliance, but changed your mind.

To delete an appliance request using the Console
  1. Open the navigation menu. Under Core Infrastructure, go to Object Storage and click Data Transfer - Imports.
  2. Find the data transfer job and appliance request that you want to delete.
  3. Click the Actions icon (Actions icon), and then click Delete.

    Alternatively, you can delete an appliance request from the Transfer Appliance Details page.

  4. Confirm the deletion when prompted.
To delete an appliance request using the CLI
oci dts appliance delete --job-id <job_id> --appliance-label <appliance_label>

For example:

oci dts appliance delete --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T

Confirm the deletion when prompted.

Displaying Registered Appliances

You can display a list of all appliances registered through the initialize authentication command. See Initializing Authentication to the Import Appliance for more information.

Note

You can only use the CLI command to display a list of all appliances registered through the initialize authentication command.
To display the list of all registered appliances using the CLI
oci dts physical-appliance list

For example:

oci dts physical-appliance list
				
{
  "data": [
    {
      "appliance_profile": "DEFAULT", 
      "endpoint": "https://10.20.20.7"
    }
  ]
}
Unregistering Appliances

You can unregister an appliance previously registered through the initialize authentication command. See Initializing Authentication to the Import Appliance for more information.

To unregister an appliance using the CLI

oci dts physical-appliance unregister
Configuring Import Appliance Encryption

Configure the import appliance to use encryption. Oracle Cloud Infrastructure creates a strong passphrase for each appliance. The command securely collects the strong passphrase from Oracle Cloud Infrastructure and sends that passphrase to the Data Transfer service.

If your environment requires Internet-aware applications to use network proxies, ensure that you set up the required Linux environment variables. See for more information.

Important

If you are working with multiple appliances at the same time, be sure the job ID and appliance label you specify in this step matches the physical appliance you are currently working with. You can get the serial number associated with the job ID and appliance label using the Console or the Oracle Cloud Infrastructure CLI. You can find the serial number of the physical appliance on the back of the device on the agency label.
Note

You can only use the Oracle Cloud Infrastructure CLI to configure encryption.

Configuring Appliance Encryption

Note

You can only use the CLI command to configure encryption for appliances.
To configure appliance encryption using the CLI

At the command prompt on the host, run oci dts physical-appliance configure-encryption to configure import appliance encryption.

oci dts physical-appliance configure-encryption --job-id <job_id>--appliance-label <appliance_label>

For example:

oci dts physical-appliance configure-encryption --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T		

Moving the state of the appliance to preparing...
Passphrase being retrieved...
Configuring encryption...
Encryption configured. Getting physical transfer appliance info...
{
  "data": {
    "availableSpaceInBytes": "Unknown", 
    "encryptionConfigured": true, 
    "finalizeStatus": "NA", 
    "lockStatus": "LOCKED", 
    "totalSpaceInBytes": "Unknown"
  }
}
Initializing Authentication to the Appliance
Note

You can only use the Oracle Cloud Infrastructure CLI to initialize authentication.

Initialize authentication to allow the host machine to communicate with the import appliance. Use the values returned from the Configure Networking command. See Configuring the Transfer Appliance Networking for details.

Initializing Authentication

Note

You can only use the CLI command to initialize authentication for appliances.
To initialize authentication using the CLI
oci dts physical-appliance initialize-authentication --job-id <job-id> --appliance-cert-fingerprint <fingerprint> --appliance-ip <ip_address> --appliance-label <appliance-label>

For example:

oci dts physical-appliance initialize-authentication --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-cert-fingerprint F7:1B:D0:45:DA:04:0C:07:1E:B2:23:82:E1:CA:1A:E9 --appliance-ip 10.0.0.1 --appliance-label XAKWEGKZ5T					

Retrieving the Appliance serial id from Oracle Cloud Infrastructure
Access token: 
Registering and initializing the authentication between the CLI and the appliance
{
  "data": {
    "availableSpaceInBytes": "Unknown", 
    "encryptionConfigured": false, 
    "finalizeStatus": "NA", 
    "lockStatus": "NA", 
    "totalSpaceInBytes": "Unknown"
  }
}

When prompted, supply the access token and system. The Control Host can now communicate with the import appliance.

Datasets

A dataset is a collection of files that are treated similarly. You can write up to 100 million files onto the appliance for import. We currently support one dataset per appliance.

Note

You can only use the CLI to run dataset tasks.

Creating the Dataset

Appliance data transfer supports NFS version 3, 4, and 4.1 to write data to the import appliance. In preparation for writing data, create and configure a dataset to write to.

To create a dataset using the CLI
oci dts nfs-dataset create --name <dataset_name>

For example:

oci dts nfs-dataset create --name nfs-ds-1 

Creating dataset with NFS export details nfs-ds-1				
{
  "data": {
    "datasetType": "NFS", 
    "name": "nfs-ds-1", 
    "nfsExportDetails": {
      "exportConfigs": null
    }, 
  "state": "INITIALIZED"
  }
}

Activating the Dataset

Activation creates the NFS export, making the dataset accessible to NFS clients.

To activate the dataset using the CLI
oci dts nfs-dataset activate --name <dataset_name>

For example:

oci dts nfs-dataset activate --name nfs-ds-1
					
Fetching all the datasets
Activating dataset small-files
Dataset nfs-ds-1 activated

Configuring Export Settings on the Dataset

To configure export settings on a dataset using the CLI
oci dts nfs-dataset set-export --name <dataset_name> --rw true --world true

For example:

oci dts nfs-dataset set-export --name nfs-ds-1 --rw true --world true

Settings NFS exports to dataset nfs-ds-1				
{
  "data": {
    "datasetType": "NFS", 
    "name": "nfs-ds-1", 
    "nfsExportDetails": {
      "exportConfigs": [
        {
          "hostname": null, 
          "ipAddress": null, 
          "readWrite": true, 
          "subnetMaskLength": null, 
          "world": true
        }
      ]
    }, 
    "state": "INITIALIZED"
  }
}

Here is another example of creating the export to give read/write access to a subnet:

oci dts nfs-dataset set-export --name nfs-ds-1 --ip 10.0.0.0 --subnet-mask-length 24 --rw true --world false
				
Settings NFS exports to dataset nfs-ds-1			
{
  "data": {
    "datasetType": "NFS", 
    "name": "nfs-ds-1", 
    "nfsExportDetails": {
      "exportConfigs": [
        {
          "hostname": null, 
          "ipAddress": "10.0.0.0", 
          "readWrite": true, 
          "subnetMaskLength": "24", 
          "world": false
        }
      ]
    }, 
    "state": "INITIALIZED"
  }
}

Deactivating the Dataset

Note

Deactivating the dataset is only required if you are running appliance commands using the Data Transfer Utility. If you are using the Oracle Cloud Infrastructure CLI to run your Appliance-Based Data Import, you can skip this step and proceed to Sealing the Dataset.

After you are done writing data, deactivate the dataset. Deactivation removes the NFS export on the dataset, disallowing any further writes.

To deactivate the dataset using the CLI
dts nfs-dataset deactivate --name <dataset_name>

For example:

dts nfs-dataset deactivate --name nfs-ds-1

Sealing the Dataset

Sealing a dataset stops all writes to the dataset. This process can take some time to complete, depending upon the number of files and total amount of data copied to the import appliance.

If you issue the seal command without the --wait option, the seal operation is triggered and runs in the background. You are returned to the command prompt and can use the seal-status command to monitor the sealing status. Running the seal command with the --wait option results in the seal operation being triggered and continues to provide status updates until sealing completion.

Important

You can only copy regular files to transfer appliances. Special files (for example, symbolic links, device special, sockets, and pipes) cannot be copied directly. To transfer special files, create a tar archive of these files and copy the tar archive to the transfer appliance.

The sealing operation generates a manifest across all files in the dataset. The manifest contains an index of the copied files and generated data integrity hashes.

To seal the dataset using the CLI
oci dts nfs-dataset seal --name <dataset_name> [--wait]

For example:

oci dts nfs-dataset seal --name nfs-ds-1

Seal initiated. Please use seal-status command to get progress.

Monitoring the Dataset Sealing Process

To monitor the dataset sealing process using the CLI
oci dts nfs-dataset seal-status --name <dataset_name>

For example:

oci dts nfs-dataset seal-status --name nfs-ds-1
					
{
  "data": { 
    "bytesProcessed": 2803515612507, 
    "bytesToProcess": 2803515612507, 
    "completed": true, 
    "endTimeInMs": 1591990408804, 
    "failureReason": null, 
    "numFilesProcessed": 182, 
    "numFilesToProcess": 182, 
    "startTimeInMs": 1591987136180, 
    "success": true 
  }
}

Downloading the Dataset Seal Manifest

After sealing the dataset, you can optionally download the dataset's seal manifest to a user-specified location. The manifest file contains the checksum details of all the files. The transfer site uploader consults the manifest file to determine the list of files to upload to object storage. For every uploaded file, it validates that the checksum reported by object storage matches the checksum in manifest. This validation ensures that no files got corrupted in transit.

To download the dataset seal manifest file using the CLI
oci dts nfs-dataset get-seal-manifest --name <dataset_name> --output-file <file_path>

For example:

oci dts nfs-dataset get-seal-manifest --name nfs-ds-1 --output-file ~/Downloads/seal-manifest

Reopening a Dataset

If changes are necessary after sealing a dataset or finalizing an import appliance, you must reopen the dataset to modify the contents. Make the required changes and again seal the dataset. Resealing the dataset generates a new manifest.

Note

If an import appliance is rebooted or power cycled, follow the instructions in this topic to reopen the dataset.

Step 1: Unlocking the Appliance

You must unlock the appliance before you can write data to it. Unlocking the appliance requires the strong passphrase that is created by Oracle Cloud Infrastructure for each appliance. Unlocking can be accomplished in two different ways:

  • If you provide the --job-id and --appliance-label when running the unlock command, the data transfer system retrieves the passphrase from Oracle Cloud Infrastructure and sends it to the appliance during the unlock operation.
  • You can query Oracle Cloud Infrastructure for the passphrase and provide that passphrase when prompted during the unlock operation.
To unlock the appliance and send the passphrase to the appliance
oci dts physical-appliance unlock --job-id <job_id> --appliance-label <label>

For example:

oci dts physical-appliance unlock --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T				
Retrieving the passphrase from Oracle Cloud Infrastructure
{
  "data": {
    "availableSpaceInBytes": "64.00GB", 
    "encryptionConfigured": true, 
    "finalizeStatus": "NOT_FINALIZED", 
    "lockStatus": "NOT_LOCKED", 
    "totalSpaceInBytes": "64.00GB"
  }
}
To query Oracle Cloud Infrastructure for the passphrase to provide to unlock the appliance
oci dts appliance get-passphrase --job-id <job_id> --appliance-label <label>

For example:

oci dts appliance get-passphrase --job-id ocid1.datatransferjob.oc1..exampleuniqueID --appliance-label XAKWEGKZ5T
				
{
  "data": {
    "encryption-passphrase": "passphrase"
  }
}

Then, run dts physical-appliance unlock without --job-id and --appliance-label and supply the passphrase when prompted.

oci dts physical-appliance unlock

Step 2: Reopening the Appliance

Reopen the dataset to write data to the import appliance again.

To reopen an NFS dataset
oci dts nfs-dataset reopen --name <dataset_name>

Displaying the List of Datasets

To display the list of datasets using the CLI
oci dts nfs-dataset list

For example:

oci dts nfs-dataset list

Listing NFS datasets					
{
  "data": [
    {
      "datasetType": "NFS", 
      "name": "nfs-ds-1", 
      "nfsExportDetails": {
        "exportConfigs": [
          {
            "hostname": null, 
            "ipAddress": null, 
            "readWrite": true, 
            "subnetMaskLength": null, 
            "world": true
          }
        ]
      }, 
    "state": "ACTIVE"
    }
  ]
}

Displaying Dataset Details

To display the details of a transfer job using the CLI
oci dts nfs-dataset show --name <dataset_name>

For example:

oci dts nfs-dataset show --name MyDataset

{
  "data": {
    "datasetType": "NFS", 
    "name": "nfs-ds-1", 
    "nfsExportDetails": {
      "exportConfigs": [
        {
          "hostname": null, 
          "ipAddress": null, 
          "readWrite": true, 
          "subnetMaskLength": null, 
          "world": true
        }
      ]
    }, 
    "state": "ACTIVE"
  }
}

Deleting a Dataset

To delete a dataset using the CLI
oci dts nfs-dataset delete --name <dataset_name>

For example:

oci dts nfs-dataset delete --name nfs-ds-1

Confirm the deletion when prompted. The dataset is deleted with no further action or return. To confirm the deletion, display the list of datasets. See Displaying the List of Datasets for more information.