1. User Guide for Release 3.0.1
  2. Object Storage

9 Object Storage

The Object Storage service is a storage platform that offers reliable and cost-efficient data durability.

The Object Storage service stores unstructured data of any content type, including analytic data and rich content, like images and videos.

The data is stored as an object in a bucket. Buckets are associated with a compartment within a tenancy.

An Object Storage namespace serves as the top-level container for all buckets and objects. At account creation time, each tenant is assigned one unique system-generated and immutable Object Storage namespace name. The namespace spans all compartments.

With Object Storage, you can safely and securely store or retrieve data directly from the internet or from within the cloud appliance.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

This chapter provides instructions for managing Object Storage.

Obtaining the Object Storage Namespace

An Object Storage namespace serves as the top-level container for all buckets and objects. Each tenant is assigned one unique system-generated and immutable Object Storage namespace name. The namespace spans all compartments. The namespace name is a required argument for many Object Storage CLI commands.

Note:

Don't use the CLI oci os ns get command to obtain the Object Storage namespace name. The name returned is not the name for your tenancy.

Use this step to view your Object Storage namespace name.

Using the Compute Web UI

  1. Click your user name (upper right corner), and select Tenancy.

    The namespace string is listed under Object Storage Settings.

Managing Object Storage Buckets

A bucket is a container for storing objects in a compartment within an Object Storage namespace.

A bucket is associated with a single compartment. The compartment has policies that indicate what actions you can perform on a bucket and all objects in the bucket.

A bucket cannot contain other buckets.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Listing Buckets

Using the Compute Web UI

  1. In the navigation menu, under Object Storage, click Object Storage.

    A list of the buckets in the compartment you're viewing is displayed.

  2. If you don’t see the bucket you're looking for, ensure that you’re viewing the correct compartment (select from the list at the top of the page).

    The page shows only the resources in that compartment.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os bucket list 
--namespace-name <object_storage_namespace>
--compartment-id <compartment_OCID>

    Example:

    oci os bucket list  \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….uniqueID

{
  "data": [
    {
      "compartment-id": "ocid.compartment.….….….uniqueID",
      "created-by": "ocid1.user.….….….uniqueID",
      "defined-tags": null,
      "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6",
      "freeform-tags": null,
      "name": "MyBucket",
      "namespace": "export/examplenamespace",
      "time-created": "2021-05-04T18:56:39+00:00"
    },
    {
      "compartment-id": "ocid.compartment.….….….uniqueID",
      "created-by": "ocid1.user.….….….uniqueID",
      "defined-tags": null,
      "etag": "aa7642fec45729ce7cb8b321d3ee1463",
      "freeform-tags": null,
      "name": "JoesBucket",
      "namespace": "export/examplenamespace",
      "time-created": "2021-05-04T20:26:33+00:00"
    }
  ]
}

Viewing Bucket Details

Use this task to view bucket details.

Using the Compute Web UI

  1. In the navigation menu, under Object Storage, click Object Storage.

    A list of the buckets in the compartment you are viewing is displayed.

  2. From the list at the top of the page, select the compartment where the bucket resides.

  3. Click the bucket name to display the details.

  4. Click View or Copy.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os bucket get 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name>

    The OCID is identified as id in the output.

    Example:

    oci os bucket get  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  

{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6",
    "freeform-tags": null,
    "id": ocid.bucket.….….….uniqueID,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "MyBucket",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-05-04T18:56:39+00:00",
    "versioning": null
  },
  "etag": "cdb5bc11561e476cb0d8aa5b8f8668f6"
}

Creating a Bucket

Use this procedure to create an Object Storage bucket.

When you create a bucket, the bucket does not provide public access. To make the bucket publicly available, see Using Pre-Authenticated Requests.

Using the Compute Web UI

  1. In the navigation menu, click Object Storage, then click Object Storage.

  2. Click Create Bucket.

  3. Enter the following details:

    • Name: Enter a name for the bucket.

      Specify a name that is unique within your tenancy Object Storage namespace.

    • Create in Compartment: Select the compartment in which to create this bucket.

    • Enable Object Versioning: Optionally, you can enable object versioning.

      For more information, refer to Managing Object Versioning.

    • Tagging: Optionally, add one or more tags to this resource.

      If you are not sure whether to apply tags, skip this option (you can apply tags later).

      For more information about tagging resources, see Working with Resource Tags.

  4. Click Create Bucket.

    The bucket is created immediately and you can start uploading objects. See Uploading an Object.

Using the OCI CLI

  1. Gather the information you need to run the next command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os bucket create
--namespace-name <object_storage_namespace> 
--compartment-id <compartment_OCID>
--name <bucket_name>

    The bucket is created immediately and you can start uploading objects. See Uploading an Object.

    Example:

    oci os bucket create \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….uniqueID    \
--name MyBucket

{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "b78d4193ab3eb2270b1373aa52b443a1",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "MyBucket",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-11T20:11:02+00:00",
    "versioning": null
  },
  "etag": "b78d4193ab3eb2270b1373aa52b443a1"
}

Moving a Bucket to a Different Compartment

You can move a bucket from one compartment to another as long as both the source and target compartments are in the same tenancy. This capability includes moving a bucket from one compartment level down to a sublevel within the source compartment.

Using the OCI CLI

  1. Gather the information you need for the next command.

  2. Run this command to move the bucket.

    Syntax (entered on a single line):

    oci os bucket update
--namespace-name <object_storage_namespace> 
--compartment-id <target_compartment_id> 
--bucket-name <bucket_name>

    Example:

    oci os bucket update \
--namespace-name examplenamespace  \
--compartment-id ocid1.compartment.….….….target-compartmentID   \
--bucket-name MyBucket 
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….target-compartmentID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "5d72fb7ac4385e24f42ac830bc6490ca",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "MyBucket",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-02T20:44:57+00:00",
    "versioning": null
  },
  "etag": "5d72fb7ac4385e24f42ac830bc6490ca"
}

  3. Run this command to verify that the bucket moved to the correct compartment:

    Syntax (entered on a single line):

    oci os bucket list 
--namespace-name <object_storage_namespace>
--compartment-id <target_compartment_OICD>

    Example:

    oci os bucket list  \
--namespace-name examplenamespace  \
--compartment-id ocid1.compartment.….….….target-compartmentID
{
  "data": [
    {
      "compartment-id": "ocid1.compartment.….….….target-compartmentID",
      "created-by": "ocid1.user.….….….uniqueID",
      "defined-tags": null,
      "etag": "5d72fb7ac4385e24f42ac830bc6490ca",
      "freeform-tags": null,
      "name": "MyBucket",
      "namespace": "export/examplenamespace",
      "time-created": "2021-06-02T20:44:57+00:00"
    }

Deleting a Bucket

Caution:

You cannot recover a deleted bucket.

You can permanently delete an empty bucket. You cannot delete a bucket that contains any of the following:

  • Any objects

  • Previous versions of an object

  • A multipart upload in progress

  • A pre-authenticated request

Tip:

When you delete an object in a version-enabled bucket, a previous version of that object is created. Select Show Deleted Objects to display the object versions that might prevent you from deleting the bucket. For more information, see Managing Object Versioning.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os bucket delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

    Example:

    oci os bucket delete   \
--namespace-name examplenamespace  \
--bucket-name MyBucket
Are you sure you want to delete this resource? [y/N]: y

Managing Storage Objects

In the Object Storage service, an object is a file or unstructured data you upload to a bucket within a compartment within an Object Storage namespace.

The object can be any type of data, for example, multimedia files, data backups, static web content, or logs. You can store objects that are up to 10 TiB. Objects are processed as a single entity. You can't edit or append data to an object, but you can replace the entire object.

Object Storage is not tied to any specific compute instance. You can access data from anywhere inside or outside of the Oracle Private Cloud Appliance, as long you have internet connectivity, access to the Object Storage endpoint, and authorization.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Viewing Objects in a Bucket

Using the Compute Web UI

  1. In the navigation menu, under Object Storage, click Object Storage.

  2. Choose the compartment that contains the bucket that contains your object.

    A list of buckets is displayed.

  3. Click the bucket name that contains your object.

  4. Click Objects under Resources.

Using the OCI CLI

  • Listing Objects in a bucket

    1. Gather the information you need to run the command.

    2. Enter this command.

      Syntax (entered on a single line):

      oci os object list 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name>

      Example:

      oci os object list   \
--namespace-name examplenamespace  \
--bucket-name MyBucket

{
  "data": [
    {
      "etag": null,
      "md5": "Ucf+fZbCK/RN5gGsEl7G5w==",
      "name": "eventslogreference.htm",
      "size": 1363,
      "time-created": "2021-06-01T17:57:16+00:00",
      "time-modified": null
    }
  ],
  "prefixes": []
}
  • Listing object details

    1. Gather the information you need to run the command.

    2. Run this command.

      Syntax (entered on a single line):

      oci os object head 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--name <object_name>

      Example:

      oci os object head   \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--name eventslogreference.htm

{
  "access-control-allow-credentials": "true",
  "access-control-allow-methods": "POST,PUT,GET,HEAD,DELETE",
  "access-control-allow-origin": "*",
  "access-control-expose-headers": "Content-Type,Etag,last-modified,Content-MD5,Content-Length,opc-client-request-id,opc-request-id,Access-Control-Allow-Origin,Access-Control-Allow-Methods,Access-Control-Allow-Credentials",
  "connection": "Keep-Alive",
  "content-length": "1363",
  "content-md5": "Ucf+fZbCK/RN5gGsEl7G5w==",
  "content-type": "application/octet-stream",
  "date": "Tue, 01 Jun 2021 18:05:32 GMT",
  "etag": "33ed1aff724eac56f00616552fc61f3e",
  "keep-alive": "timeout=5, max=100",
  "last-modified": "2021-06-01T17:57:16.000Z",
  "opc-client-request-id": "8965F8B5A9B84F00B51D4C965F029230",
  "opc-request-id": "txae7c2c9aa7094f16adee8-0060b676ec",
  "server": "Apache",
  "x-content-type-options": "nosniff"
}

Creating a Folder or SubFolder

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax:

    oci os object put
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name>
--file <file_location> 
--name <object_name>

    Example:

    oci os object put   \
--namespace-name examplenamespace  \
--bucket-name Bucket1_objv-enabl   \
--file /home/log_files/install.log   \
--name /home/log_files/install.log 
    oci os object put   \
--namespace-name examplenamespace  \
--bucket-name Bucket1_objv-enabl   \
--file myfile   \
--name /home/log_files/install.log
    oci os object put   \
--namespace-name examplenamespace  \
--bucket-name Bucket1_objv-enabl   \
--file /home/log_files/install.log   \
--name /home/log_files/install.log  

Uploading object [####################################] 100%
{
  "etag": "bae04836d4ea5d521c23cbee70566cf2",
  "last-modified": "2021-05-13T15:37:18.000Z",
  "opc-content-md5": "GWZbZ8CXPCjLcPxBs6cPCQ=="
}

Uploading an Object

Using the OCI CLI

An object can be uploaded as a single part or as multiple parts. Use the --no-multipart option to upload as a single part. For detailed information on multi-part uploads, see Performing a Multi-Part Upload.

  1. Gather the information you need to run the command.

  2. Run the object put command.

    Syntax (entered on a single line):

    oci os object put
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--file <file_location>

    The value of <file_location> is the full path name of the object being uploaded, such as C:\workspace\Uploads\MyFile.txt or /home/user/Documents/Uploads/MyFile.txt.

    If you specify the --no-multipart option, the file will upload as a single object with the same name as the source file.

    Example:

    oci os object put --namespace-name examplenamespace --bucket-name MyBucket \
--file /home/user/Documents/Uploads/MyFile.txt --no-multipart

Uploading object [####################################] 100%
{
  "etag": "33ed1aff724eac56f00616552fc61f3e",
  "last-modified": "2021-06-01T17:57:16.000Z",
  "opc-content-md5": "Ucf+fZbCK/RN5gGsEl7G5w=="
}

Performing a Multi-Part Upload

With multi-part uploads, individual parts of an object can be uploaded in parallel to reduce the amount of time you spend uploading.

Multi-part uploads accommodate objects that are too large for a single upload operation. Object parts must be no larger than 50 GiB.

You can pause between the uploads of individual parts, and resume the upload when your schedule and resources allow.

Using the OCI CLI

To upload an object, run oci os object put with the --part-size flag. The --part-size value represents the size of each part in mebibytes (MiBs). Object Storage waives the minimum part size restriction for the last uploaded part. The --part-size value must be an integer.

Optionally, you can use the --parallel-upload-count flag to set the maximum number of parallel uploads allowed.

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

    oci os object put
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--file <file_location> 
--parallel-upload-count <maximum_number_parallel_uploads> 
--part-size <upload_part_size_in_MB> 
--force

    Example:

    oci os object put   \
--namespace-name examplenamespace  \
--file /boot/initramfs-0-rescue-e542c19f0fbf4e41a41428d933a7357f.img   \
--parallel-upload-count 5   \
--part-size 15   \
--force

Upload ID: a21bba2c-8922-4b9c-a98a-9ef3569c0138
Split file into 6 parts for upload.
Uploading object [####################################] 100%
{
  "etag": "0964effc8dc4394fd317f03a025ae5d0",
  "last-modified": "2021-05-11T21:35:19",
  "opc-multipart-md5": "UIVRhiwSHY6o0E4pi/yfGg==-6"
}

Listing the Parts of an Unfinished or Failed Multi-part Upload

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os multipart list 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name>

    Example:

    oci os multipart list
--namespace-name examplenamespace  \ 
--bucket-name MyBucket  \
{
  "data": [
    {
      "bucket": "MyBucket",
      "namespace": "examplenamespace",
      "object": "MyObject",
      "time-created": "2019-07-25T21:55:21.973000+00:00",
      "upload-id": "0b7abd48-9ff2-9d5f-2034-63a02fdd7afa"
    },
    {
      "bucket": "MyBucket",
      "namespace": "examplenamespace",
      "object": "MyObject",
      "time-created": "2019-07-25T21:53:09.246000+00:00",
      "upload-id": "1293ac9d-83f8-e055-a5a7-d1e13277b5c0"
    },
    {
      "bucket": "MyBucket",
      "namespace": "examplenamespace",
      "object": "MyObject",
      "time-created": "2019-07-25T21:46:34.981000+00:00",
      "upload-id": "33e7a875-9e94-c3bc-6577-2ee5d8226b53"
    }
...

Canceling a Multi-Part Upload

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os multipart abort
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--object-name <object_name> 
--upload-id <upload_ID>

    Example:

    oci os multipart abort  \
--namespace-name examplenamespace  \
--bucket-name MyBucket    \
--object-name MyObject    \
--upload-id 22d5f6d2-8e03-48ca-8593-0192d25770b8

"data": [
{
"etag": "dd434179cfbc22458a9739096ec43226",
"md5": "PBrT093rZrcSDwQsKh9azQ==",
"part-number": 13,
"size": 15728640
}
],
"opc-next-page": "00013"
}
WARNING: Are you sure you want to permanently remove this incomplete upload? [y/N]: y

Performing a Bulk Object Upload

Bulk operations at a specific level of the hierarchy do not affect objects in any level above.

Using the OCI CLI

  1. Gather the information you need to run the command.

    • Namespace (see Obtaining the Object Storage Namespace)

    • Bucket name (oci os bucket list), see Listing Buckets

    • Source directory location – is the upload directory path, such as C:\workspace\Upload\ or /home/user/Documents/Upload. If your source directory has subdirectories, the subdirectory names are prepended to the names of the files stored in those subdirectories, delimited with a forward slash (/) character. For example, if a file named maple.jpg is stored in the subdirectory trees, when the file is uploaded, Object Storage assigns the name trees/maple.jpg to the object.

  2. Run this command.

    Syntax (entered on a single line):

    oci os object bulk-upload 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--src-dir <source_directory_location>

    Example:

    oci os object bulk-upload
--namespace-name examplenamespace  \ 
--bucket-name MyBucket    \ 
--src-dir /home/log-dir/  

Uploaded Jan-logs [####################################] 100%
Uploaded Feb-logs [####################################] 100%
Uploaded Mar-logs [####################################] 100%
Uploaded Apr-logs [####################################] 100%

{
  "skipped-objects": [],
  "upload-failures": {},
  "uploaded-objects": {
    "Jan-logs": {
      "etag": "33ed1aff724eac56f00616552fc61f3e",
      "last-modified": "2021-06-01T20:42:50.000Z",
      "opc-content-md5": "Ucf+fZbCK/RN5gGsEl7G5w=="
    },
    "Feb-logs": {
      "etag": "e1875449257cc6ac6ab93cc9c7921c87",
      "last-modified": "2021-06-01T20:42:50.000Z",
      "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
    },
    "Mar-logs": {
      "etag": "c784ac5216d889f55138ecfb428eee3c",
      "last-modified": "2021-06-01T20:42:51.000Z",
      "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
    },
    "Apr-logs": {
      "etag": "3b4571c73bdb9e44bec0512a5e48fba7",
      "last-modified": "2021-06-01T20:42:51.000Z",
      "opc-content-md5": "1B2M2Y8AsgTpgAmY7PhCfg=="
    }
  }
}

Copying an Object to a Different Bucket

You can copy an object to a different bucket as long as the target bucket is located in the same Private Cloud Appliance.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os object copy
--namespace-name <object_storage_namespace>   
--bucket-name <source_bucket_name>
--source-object-name <source_object>
--destination-bucket <destination_bucket_name>
--destination-object-name <destination_object_name>

    Example:

    oci os object copy 
--namespace-name examplenamespace 
--bucket-name MyBucket 
--source-object-name Compute_Logs.tar.gz 
--destination-bucket Bucket-log-backups 
--destination-object-name Compute_Logs.tar.gz.backup

    Verify that the copied object is in the bucket.

    oci os object list
--namespace-name examplenamespace 
--bucket-name Bucket-log-backups

{
"data": [
{
"etag": null,
"md5": "XzYkstrjaprhbZyemalRbQ==",
"name": "Compute_Logs.tar.gz.backup",
"size": 132631,
"time-created": "2021-04-01T21:00:55+00:00",
"time-modified": null
}
],
"prefixes": []
}

Downloading an Object

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run this command.

    Syntax (entered on a single line):

    oci os object get 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--name <object_name> 
--file <file_location>

    <file_location> is the destination path for the file being downloaded, such as C:\workspace\Downloads\MyFile.txt or /home/user/Documents/Downloads/MyFile.txt.

    Example:

    oci os object get  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--name photos  \
--file /home/photos_backup

Downloading object [#-----------------------------------] 100%

# ls -l
total 8
-rw-r--r-- 1 root root 1363 Jun 1 17:56 photo1
-rw-r--r-- 1 root root 1363 Jun 1 21:40 photo1_backup
-rw-r--r-- 1 root root 0 Jun 1 20:42 photo2
-rw-r--r-- 1 root root 0 Jun 1 20:42 photo3
-rw-r--r-- 1 root root 0 Jun 1 20:42 photo4

Performing a Multi-Part Download

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

    oci os object get 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--name <object_name> 
--file <file_location> 
--range bytes=<byte_range>

    Example:

    oci os object get    \
--namespace-name examplenamespace  \
--bucket-name MyBucket    \
--name MyObject.mp4    \
--file c:\workspace\Downloads\MyObject.mp4    \
--range bytes=0-50

cusobjstorenamespace --range bytes=0-50
Downloading object [#-----------------------------------] 3%

# ls -l
total 12
-rw-r--r-- 1 root root 1363 Jun 1 17:56 abc.mp41
-rw-r--r-- 1 root root 51 Jun 1 21:50 def.mp4
-rw-r--r-- 1 root root 1363 Jun 1 21:40 ghi.mp4
-rw-r--r-- 1 root root 0 Jun 1 20:42 jkl.mp4
-rw-r--r-- 1 root root 0 Jun 1 20:42 mno.mp4
-rw-r--r-- 1 root root 0 Jun 1 20:42 pqr.mp4

Performing a Bulk Download

Using the OCI CLI

  1. Gather the information you need to run the command.

    • Namespace (see Obtaining the Object Storage Namespace)

    • Bucket name (oci os bucket list), see Listing Buckets

    • Download directory. <download_directory_location> is the destination path for the objects being downloaded, such as C:\workspace\Downloads\ or /home/user/Documents/Downloads/. If the directory does not exist, Object Storage creates the directory when the command runs.

  2. Run the command.

    Syntax (entered on a single line):

    oci os object bulk-download 
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name> 
--download-dir <download_directory_location>

    Example:

    oci os object bulk-download    \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--download-dir c:\workspace\Downloads

Downloaded MyFile.txt [####################################] 100%
Downloaded logFile.log [####################################] 100%

{
  "download-failures": {},
  "skipped-objects": []
}

Deleting an Object

You can permanently delete an object from a bucket or folder. You cannot, however, recover a deleted object unless you have object versioning enabled. See Managing Object Versioning for details.

You cannot delete an object that has an active retention rule. See Defining Retention Rules for details.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax (entered on a single line):

    oci os object delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--object-name <object_name>

    Example:

    oci os object delete    \
--namespace-name examplenamespace  \
--bucket-name MyBucket    \
--object-name MyFile.txt

Are you sure you want to delete this resource? [y/N]: y

Performing a Bulk Delete of All Objects in a Bucket

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. To see a list of the files impacted by a bulk delete command without actually deleting the files, use the --dry-run option.

    Syntax (entered on a single line):

    oci os object bulk-delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--dry-run

    Example:

    oci os object bulk-delete    \
--namespace-name examplenamespace  \
--bucket-name MyBucket    \
--dry-run
{
  "delete-failures": {},
  "deleted-objects": [
    "MyFile.txt",
    "logFile.log"
  ]
}

  3. To perform the bulk deletion:

    Syntax (entered on a single line):

    oci os object bulk-delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

    Example:

    oci os object bulk-delete \
--namespace-name examplenamespace  \
--bucket-name MyBucket

WARNING: This command will delete 2 objects. Are you sure you wish to continue? [y/N]:y

Deleted MyRenamedFile.txt [####################################] 100%
Deleted logFile.log [####################################] 100%

{
  "delete-failures": {},
  "deleted-objects": [
    "MyFile.txt",
    "logFile.log"
  ]
}

Managing Object Versioning

Object versioning provides data protection against accidental or malicious object updates, overwrites, or deletions.

Object versioning is enabled at the bucket level. Versioning directs Object Storage to automatically create an object version each time a new object is uploaded, an existing object is overwritten, or when an object is deleted. You can enable object versioning at bucket creation time or later. A bucket that is versioning-enabled can have many versions of an object. There is always one latest version of the object and zero or more previous versions.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Enabling Versioning During Bucket Creation

Object versioning provides data protection against accidental or malicious object updates and deletions.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax (entered on a single line):

    oci os bucket create
--namespace-name <object_storage_namespace> 
--compartment-id <target_compartment_id> 
--name <bucket_name>
--versioning enabled

    Example:

    oci os bucket create    \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….exampleuniqueID    \
--name MyStandardBucket    \
--versioning enabled

{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "00b4edbb27012ae78a912428ad1e630c",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "bucket-4-versioning",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "NoPublicAccess",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-10T18:39:12+00:00",
    "versioning": "Enabled"
  },
  "etag": "00b4edbb27012ae78a912428ad1e630c"
}

Enabling or Suspending Versioning (After Bucket Creation)

Object versioning provides data protection against accidental or malicious object updates and deletions.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

    oci os bucket update
--namespace-name <object_storage_namespace> 
--compartment-id <target_compartment_id> 
--bucket-name <bucket_name> 
--versioning <enabled | suspended>

    For --versioning, choose one of the options: enabled or suspended.

    Example of enabling object versioning:

    oci os bucket update    \
--namespace-name examplenamespace  \
--compartment-id ocid.compartment.….….….uniqueID    \
--bucket-name MyBucket    \
--versioning Enabled
{
  "data": {
    "approximate-count": null,
    "approximate-size": null,
    "compartment-id": "ocid1.compartment.….….….uniqueID",
    "created-by": "ocid1.user.….….….uniqueID",
    "defined-tags": null,
    "etag": "117f0608bdf83b9c7ea393db556a0ee4",
    "freeform-tags": null,
    "id": null,
    "is-read-only": null,
    "kms-key-id": null,
    "metadata": null,
    "name": "MyBucket",
    "namespace": "export/examplenamespace",
    "object-events-enabled": null,
    "object-lifecycle-policy-etag": null,
    "public-access-type": "ObjectRead",
    "replication-enabled": null,
    "storage-tier": "Standard",
    "time-created": "2021-06-02T17:06:18+00:00",
    "versioning": "Enabled"
  },
  "etag": "117f0608bdf83b9c7ea393db556a0ee4"
}

Viewing Object Versions and Details

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Run the command.

    Syntax (entered on a single line):

    oci os object list-object-versions
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

    Example:

    oci os object list-object-versions    \
--namespace-name examplenamespace  \
--bucket-name MyBucket
{
  "data": [
    {
      "etag": null,
      "is-delete-marker": false,
      "md5": "3DI5GbLmKiRxY/ozWxyXHQ==",
      "name": "bucket-data",
      "size": 103,
      "time-created": "2021-06-02T22:20:25+00:00",
      "time-modified": null,
      "version-id": null
    },
    {
      "etag": null,
      "is-delete-marker": false,
      "md5": "VIic5JncRWwDQj6CnsZ1Ww==",
      "name": "compute.log",
      "size": 4878456,
      "time-created": "2021-06-10T19:03:26+00:00",
      "time-modified": null,
      "version-id": "5f4ce7e8-656f-409a-b70a-ebfedddcfeda"
    }
  ],
  "prefixes": []
}

Deleting the Previous Version of an Object

When versioning is enabled, deleting an object without targeting a specific version creates a delete marker and previous version of the object that can be recovered. However, deleting a previous version of an object is a permanent deletion.

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax:

    Note:

    If an object has a version-id of null, there is only one version of the object. To delete this object, omit the --version-id argument. 

    oci os object delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--version-id <bucket_version_id>
--object-name <object_name>

    Example:

    oci os object delete
--namespace-name examplenamespace  \ 
--bucket-name MyBucket  \
--version-id 7f1f537d-ec9c-4706-867a-b1dae355c263   \
--object-name compute.log

Recovering a Deleted Object Version

Recovering a deleted object version is as simple as deleting the delete marker that was created when you deleted the latest version of an object. The previous version of the object listed just below the delete marker is recovered and becomes the latest version of the object.

Using the OCI CLI

  1. List the objects in the bucket. See Viewing Object Versions and Details. In the output, locate the object version that has "is-delete-marker": true.

    Use the version-id of that object with the delete command to delete the delete marker.

    Note:

    If an object has a version-id of null, there is only one version of the object. To delete this object marker, omit the --version-id argument.

  2. Gather the information you need to run the command.

  3. Syntax:

    oci os object delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--object-name <object_name>
--version-id <bucket_version_id>

    Example:

    oci os object delete
--namespace-name examplenamespace  \ 
--bucket-name  MyBucket
--object-name application.log
--version-id  6ce3eb93-8850-4732-8949-cb6e67b722b0
Are you sure you want to delete this resource? [y/N]: y

Using Pre-Authenticated Requests

Pre-authenticated requests provide a way to let users access a bucket or an object without having their own credentials, as long as the request creator has permissions to access those objects.

For example, you can create a request that lets an operations support user upload backups to a bucket without owning API keys. Or, you can create a request that lets a business partner update shared data in a bucket without owning API keys.

When you create a pre-authenticated request, a unique URL is generated. Anyone you provide this URL to can access the Object Storage resources identified in the pre-authenticated request, using standard HTTP tools like curl and wget.

Important:

Assess the business requirement for and the security ramifications of pre-authenticated access to a bucket or objects.

A pre-authenticated request URL gives anyone who has the URL access to the targets identified in the request. Carefully manage the distribution of the URL.

For more conceptual information, refer to the Object Storage Overview section in the Oracle Private Cloud Appliance Concepts Guide.

Listing Pre-Authenticated Requests

Use this procedure to obtain information about pre-authenticated requests, such as obtaining the pre-authenticated requests id that you might need for other commands.

Note:

Listing pre-authenticated requests does not display the unique URL provided by the system when you created a pre-authenticated request. The URL is displayed only at the time of creation and cannot be retrieved later.

Using the OCI CLI

  • Listing All the Pre-Authenticated Requests in a Bucket

    1. Gather the information you need to run the command.

    2. Run the command.

      Syntax (entered on a single line):

      oci os preauth-request list
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

      Example:

      oci os preauth-request list \
--namespace-name examplenamespace  \
--bucket-name MyBucket
{
  "data": [
    {
      "access-type": "ObjectRead",
      "id": "5299a6f9-55c7-4805-88ca-b270c9a9e94f",
      "name": "PAR_ObjRead",
      "object-name": "compute.log",
      "time-created": "2021-06-10T20:34:01+00:00",
      "time-expires": "2021-07-30T23:55:00+00:00"
    },
    {
      "access-type": "AnyObjectWrite",
      "id": "783cd56b-9df5-4518-aacf-f523deae5102",
      "name": "PAR-all-objectsRW",
      "object-name": null,
      "time-created": "2021-06-10T20:49:11+00:00",
      "time-expires": "2021-07-30T23:54:59+00:00"
    },
    {
      "access-type": "ObjectRead",
      "id": "2ea48624-16ed-4d81-95ca-b23ea750ed3d",
      "name": "PAR-OS-READ",
      "object-name": "backup.log",
      "time-created": "2021-06-10T21:16:47+00:00",
      "time-expires": "2021-07-30T23:55:00+00:00"
    }
  ]
}
  • Getting the Details for a Specific Pre-Authenticated Request

    1. Gather the information you need to run the command.

    2. Run the command.

      Syntax (entered on a single line):

      oci os preauth-request get
--namespace-name <object_storage_namespace>
--bucket-name <bucket_name>
--par-id <preauth-id>

      Example:

      oci os preauth-request get  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--par-id 5299a6f9-55c7-4805-88ca-b270c9a9e94f
{
  "data": {
    "access-type": "ObjectRead",
    "id": "5299a6f9-55c7-4805-88ca-b270c9a9e94f",
    "name": "PAR_ObjRead",
    "object-name": "compute.log",
    "time-created": "2021-06-10T20:34:01+00:00",
    "time-expires": "2021-07-30T23:55:00+00:00"
  }
}

Creating a Pre-Authenticated Request for All Objects in a Bucket

Using the OCI CLI

  1. Gather the information you need to run the command.

    • Namespace (see Obtaining the Object Storage Namespace)

    • Bucket name (oci os bucket list), see Listing Buckets

    • Name for this pre-authenticated request.

    • Access type is one of these items:

      • AnyObjectRead permits reads on all objects in the bucket.

      • AnyObjectWrite permits writes to all objects in the bucket.

      • AnyObjectReadWrite permits reads and writes to all objects in the bucket.

      Note:

      Listing objects in a bucket is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

    • Timestamp Is a required argument and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

  2. Run the command.

    Syntax (entered on a single line):

    oci os preauth-request create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--name <preauthenticated_request_name> 
--access-type <access_value>
--time-expires <timestamp>

    This example creates a pre-authenticated request that allows reads and writes to all objects in the bucket:

     oci os preauth-request create  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--name PAR-all-objectsRW  \
--access-type AnyObjectWrite  \
--time-expires '2021-07-30 23:55'
{
  "data": {
    "access-type": "AnyObjectWrite",
    "access-uri": "/oci/p/KOCRWzqBilJmIsaBbJNelKLWcOxwRLq/n/examplenamespace/b/MyBucket/o/",
    "id": "783cd56b-9df5-4518-aacf-f523deae5102",
    "name": "PAR-all-objectsRW",
    "object-name": null,
    "time-created": "2021-06-10T20:49:11+00:00",
    "time-expires": "2021-07-30T23:54:59+00:00"
  }
}

  3. Important – Copy the access-uri to durable storage.

    The unique access-uri provided by the system is the only way to construct a URL that a user can use to access the bucket or object specified as the request target.

    The access-uri is displayed only at the time of creation and cannot be retrieved later.

  4. Construct a URL from the unique access-uri.

    See Constructing the Pre-Authenticated Request URL.

Creating a Pre-Authenticated Request for a Specific Object

Using the OCI CLI

  1. Gather the information you need to run the command.

    • Namespace (see Obtaining the Object Storage Namespace)

    • Bucket name (oci os bucket list), see Listing Buckets

    • Name for this pre-authenticated request.

    • Access type is one of these items:

      • AnyObjectRead permits reads on all objects in the bucket.

      • AnyObjectWrite permits writes to all objects in the bucket.

      • AnyObjectReadWrite permits reads and writes to all objects in the bucket.

      Note:

      Listing objects in a bucket is denied by default. If the --access-type is AnyObjectRead or AnyObjectReadWrite, you can specify the optional --bucket-listing-action ListObjects parameter when creating the pre-authenticated request that lets users list the objects in the bucket.

    • Timestamp Is a required argument and must be an RFC 3339 timestamp. For example: 2017-09-01T00:09:51.000+02:00.

    • Object name, or null

  2. Syntax (entered on a single line):

    oci os preauth-request create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--name <preauthenticated_request_name> 
--access-type <access_value> 
--time-expires <timestamp> 
-on <object_name_or_null>

    Example:

    oci os preauth-request create
--namespace-name examplenamespace  \ 
--bucket-name MyBucket 
--name PAR-OS-READ 
--access-type ObjectRead 
--time-expires '2021-07-30 23:55' 
-on compute.log

{
  "data": {
    "access-type": "ObjectRead",
    "access-uri": "/oci/p/eWvgyLcDthhvVUNkVaejymgDTOILHli/n/examplenamespace/b/MyBucket/o/compute.log",
    "id": "2ea48624-16ed-4d81-95ca-b23ea750ed3d",
    "name": "PAR-OS-READ",
    "object-name": "compute.log",
    "time-created": "2021-06-10T21:16:47+00:00",
    "time-expires": "2021-07-30T23:55:00+00:00"
  }
}

  3. Important – Copy the access-uri to durable storage.

    The unique access-uri provided by the system is the only way to construct a URL that a user can use to access the bucket or object specified as the request target.

    The access-uri is displayed only at the time of creation and cannot be retrieved later.

  4. Construct a URL from the unique access-uri.

    See Constructing the Pre-Authenticated Request URL.

Constructing the Pre-Authenticated Request URL

After you have a unique access-uri, you can construct the access URL that enables users to access pre-authenticated objects.

  1. Construct the URL using this syntax.

    Syntax:

    https://objectstorage.<pca_fqdn>/oci/<access-uri>

    where:

    Example:

    https://objectstorage.mypca01.us.example.com/oci/p/MrxLFkKlFkIlNDhvhcZnrjbUAlsoeah/n/mynamespace/b/my-bucket/o/

    Note – Sometimes, you need to omit the slash at the end of the <access-uri> string. Refer to the Oracle Private Cloud Appliance Release Notes.

Deleting a Pre-Authenticated Request

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax (entered on a single line):

    oci os preauth-request delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>
--par-id <preauthenticated_request_id>

    Example:

    oci os preauth-request delete  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--par-id 2ea48624-16ed-4d81-95ca-b23ea750ed3d
Are you sure you want to delete this resource? [y/N]: y

Listing Objects for Pre-Authenticated Requests

Using the unique request URL, you can use a tool like curl to list, read, and write data using the pre-authenticated request.

Using curl

  • Syntax (entered on a single line):

    $ curl -X GET <unique-PAR-URL>

    Example:

    $ curl -X GET    \
https://objectstorage.us-example-1.example.com/p/CoO26YkSARiRevWlDWJD_QUvtFPUocn/n/examplenamespace/b/MyParBucket/o/

{"objects":[{"name":"InfoWorld DeepDive - Tips  for Git and GitHub Users.pdf"},{"name":"OCI_User_Guide.pdf"},
{"name":"OracleCorporateTerminologyUsageGuideRedwood.pdf"},{"name":"VPN.png"},{"name":"eventslogreference.htm"},
{"name":"functionslogreference.htm"},{"name":"glob.txt"},{"name":"loadbalancerreference.htm"},{"name":"objectstoragelogreference.htm"},
{"name":"servicechanges.html"},{"name":"servicediscovery.dita"},{"name":"serviceessentials.html"},{"name":"servicelogreference.htm"},
{"name":"services.html"}]}

Uploading an Object Using a Pre-Authenticated Request

Using the unique request URL, you can use a tool like curl to read and write data using the pre-authenticated request.

Using curl

  • Syntax (entered on a single line):

    $ curl -X PUT --data-binary '@<local-filename>' <unique-PAR-URL>

    Example:

    $ curl -X PUT    \
--data-binary '@using-dita-guide.pdf'    \
https://objectstorage.us-example-1.example.com/p/lnaqMuXWef_lhTxCiS9ngCw/n/examplenamespace/b/MyParBucket/o/using-dita-guide.pdf

Downloading an Object Using a Pre-Authenticated Request

Using the unique request URL, you can use a tool like curl to read and write data using the pre-authenticated request.

Using curl

  • Syntax (entered on a single line):

    $ curl -X GET <unique-PAR-URL>

    Example:

    $ curl -X GET    \
https://objectstorage.us.example.com/p/tnjDhazP9o6s2KzLyFUxILQzSamEp/n/examplenamespace/b/MyParBucket/o/OCI_User_Guide.pdf 
'@data.1''@data.2''@data.3'

Defining Retention Rules

Retention rules provide immutable storage options for data written to Object Storage for data governance, regulatory compliance, and legal hold requirements. Retention rules can also protect your data from accidental or malicious writes or deletion. Retention rules can be locked to prevent rule modification and data deletion or modification even by administrators.

Retention rules are configured at the bucket level and are applied to all individual objects in the bucket.

For more conceptual information, refer to the Object Storage Overview in the Oracle Private Cloud Appliance Concepts Guide.

Viewing Retention Rules and Details

Using the OCI CLI

  • Listing the Retention Rules for a Bucket

    1. Gather the information you need to run the command.

    2. Run the command.

      Syntax:

      oci os retention-rule list
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name>

      Example:

      oci os retention-rule list  \
--namespace-name examplenamespace  \
--bucket-name MyBucket
{
  "data": {
    "items": [
      {
        "display-name": "RegulatoryCompliance",
        "duration": {
          "time-amount": 5,
          "time-unit": "YEARS"
        },
        "etag": "72be3a47de931cd50ad9d93c077def64",
        "id": "72be3a47de931cd50ad9d93c077def64",
        "time-created": "2021-06-10T22:24:21+00:00",
        "time-modified": "2021-06-10T22:24:21+00:00",
        "time-rule-locked": "2021-06-30T17:00:00+00:00"
      },
      {
        "display-name": "TempHold",
        "duration": {
          "time-amount": 30,
          "time-unit": "DAYS"
        },
        "etag": "344a9c205187408699b51c7769dc1bb4",
        "id": "344a9c205187408699b51c7769dc1bb4",
        "time-created": "2021-06-10T22:17:50+00:00",
        "time-modified": "2021-06-10T22:17:50+00:00",
        "time-rule-locked": null
      },
      {
        "display-name": "LegalHold",
        "duration": null,
        "etag": "bd8d8efb964d1025f4305c86de630a4f",
        "id": "bd8d8efb964d1025f4305c86de630a4f",
        "time-created": "2021-06-10T22:13:37+00:00",
        "time-modified": "2021-06-10T22:13:37+00:00",
        "time-rule-locked": null
      }
    ]
  }
}

  • Getting Details for a Specific Retention Rule

    1. Gather the information you need to run the command.

    2. Run the command.

      Syntax:

      oci os retention-rule get
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_identifier>

      Example:

      oci os retention-rule get  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--retention-rule-id 72be3a47de931cd50ad9d93c077def64

{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 5,
      "time-unit": "YEARS"
    },
    "etag": "72be3a47de931cd50ad9d93c077def64",
    "id": "72be3a47de931cd50ad9d93c077def64",
    "time-created": "2021-06-10T22:24:21+00:00",
    "time-modified": "2021-06-10T22:24:21+00:00",
    "time-rule-locked": "2021-06-30T17:00:00+00:00"
  }
}

Creating a Retention Rule

Using the OCI CLI

  • Creating an Indefinite Retention Rule

    1. Gather the information you need to run the command.

    2. Run this command.

      Syntax:

      oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <name_displayed_for_rule>

      Example:

      oci os retention-rule create   \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--display-name LegalHold
{
  "data": {
    "display-name": "LegalHold",
    "duration": null,
    "etag": "bd8d8efb964d1025f4305c86de630a4f",
    "id": "bd8d8efb964d1025f4305c86de630a4f",
    "time-created": "2021-06-10T22:13:37+00:00",
    "time-modified": "2021-06-10T22:13:37+00:00",
    "time-rule-locked": null
  }
}
  • Creating a time-bound, Unlocked Retention Rule

    1. Gather the information you need to run the command.

    2. Run this command.

      Syntax:

      oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <display_name> 
--time-amount <time_integer> 
--time-unit <days|years>

      Example:

       oci os retention-rule create  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--display-name TempHold  \
--time-amount 30  \
--time-unit days
{
  "data": {
    "display-name": "TempHold",
    "duration": {
      "time-amount": 30,
      "time-unit": "DAYS"
    },
    "etag": "344a9c205187408699b51c7769dc1bb4",
    "id": "344a9c205187408699b51c7769dc1bb4",
    "time-created": "2021-06-10T22:17:50+00:00",
    "time-modified": "2021-06-10T22:17:50+00:00",
    "time-rule-locked": null
  }
}

  • Creating a Time-Bound, Locked Retention Rule

    1. Gather the information you need to run the command.

      • Namespace (see Obtaining the Object Storage Namespace)

      • Bucket name (oci os bucket list), see Listing Buckets

      • Display name: The name you want to apply to this retention rule.

      • Time and unit (days|years). For example, 30 days or 5 years.

      • Date and time to lock the rule.

    2. Run this command.

      Syntax:

      oci os retention-rule create
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--display-name <display_name> 
--time-amount <time_integer> 
--time-unit <days|years> 
--time-rule-locked <date and time>

      Example:

      oci os retention-rule create  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--display-name RegulatoryCompliance   \
--time-amount 5   \
--time-unit years   \
--time-rule-locked "2021-06-30 17:00"
{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 5,
      "time-unit": "YEARS"
    },
    "etag": "72be3a47de931cd50ad9d93c077def64",
    "id": "72be3a47de931cd50ad9d93c077def64",
    "time-created": "2021-06-10T22:24:21+00:00",
    "time-modified": "2021-06-10T22:24:21+00:00",
    "time-rule-locked": "2021-06-30T17:00:00+00:00"
  }
}

Modifying a Retention Rule

Using the OCI CLI

  • Updating a Retention Rule

    1. Gather the information you need to run the command.

    2. Run this command.

      Syntax:

      oci os retention-rule update
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_id>

      Followed by the retention rule item that you plan to change:

      --time-amount <time_integer> 
--time-unit <days|years>

      Example:

      oci os retention-rule update  \
--namespace-name examplenamespace  \
--bucket-name MyBucket  \
--retention-rule-id 344a9c205187408699b51c7769dc1bb4  \
--time-amount 60  \
--time-unit days 
{
  "data": {
    "display-name": "TempHold",
    "duration": {
      "time-amount": 60,
      "time-unit": "DAYS"
    },
    "etag": "344a9c205187408699b51c7769dc1bb4",
    "id": "344a9c205187408699b51c7769dc1bb4",
    "time-created": "2021-06-10T22:17:50+00:00",
    "time-modified": "2021-06-10T22:45:16+00:00",
    "time-rule-locked": null
  }
}
  • Removing a Retention Rule Lock During the Delay Period

    1. Gather the information you need to run the command.

    2. Run this command.

      Syntax:

      oci os retention-rule update
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_id>
--time-rule-locked ""

      Example:

      oci os retention-rule update
--namespace-name examplenamespace  \ 
--bucket-name MyBucket  \
--retention-rule-id b1a6c84c-57c4-416c-b006-f864b0904c9e 
--time-rule-locked ""
{
  "data": {
    "display-name": "RegulatoryCompliance",
    "duration": {
      "time-amount": 6,
      "time-unit": "YEARS"
    },
    "etag": "5b4fa526-faec-47d4-9162-4acdf1813ee0",
    "id": "b1a6c84c-57c4-416c-b006-f864b0904c9e",
    "time-created": "2020-03-25T15:11:44.423000+00:00",
    "time-modified": "2020-03-25T22:02:43.745000+00:00",
    "time-rule-locked": null
  },
  "etag": "5b4fa526-faec-47d4-9162-4acdf1813ee0"
}

Deleting a Retention Rule

Using the OCI CLI

  1. Gather the information you need to run the command.

  2. Syntax:

    oci os retention-rule delete
--namespace-name <object_storage_namespace> 
--bucket-name <bucket_name> 
--retention-rule-id <retention_rule_identifier>

    Example:

    oci os retention-rule delete  \
--namespace-name examplenamespace  \
--bucket-name MyBucket   \
--retention-rule-id 344a9c205187408699b51c7769dc1bb4
Are you sure you want to delete this resource? [y/N]: y