Oracle Object Storage

At a glance

Capability	Support
rclone support tier	Tier 1: Core
Checksums	MD5
Modification times	Kept, to 1 ms
Case-insensitive names	No
Duplicate names allowed	No
Server-side copy	Yes
Server-side move and rename	No
Folder move and rename	No: each file is moved in turn
Free space reporting	No
Empty folders	No: folders exist only while they hold files
Change notifications	No
Uploads of unknown size	Yes
Public links	No

From rclone’s documentation

The rest of this page is adapted from rclone’s documentation for this backend (rclone v1.75.2, MIT licence). It is written for rclone’s command line: where it mentions a flag such as --oracleobjectstorage-example, set the option example in the wizard’s options instead. Commands such as rclone copy aren’t part of CloudMount.

Object Storage provided by the Oracle Cloud Infrastructure (OCI). Read more at <oracle.com>:

• Oracle Object Storage Overview
• Oracle Object Storage FAQ

You may put subdirectories in too, e.g. remote:bucket/path/to/dir.

Sample command to transfer local artifacts to remote:bucket in oracle object storage:

rclone -vvv  --progress --stats-one-line --max-stats-groups 10 --log-format date,time,UTC,longfile --fast-list --buffer-size 256Mi --oos-no-check-bucket --oos-upload-cutoff 10Mi --multi-thread-cutoff 16Mi --multi-thread-streams 3000 --transfers 3000 --checkers 64  --retries 2  --oos-chunk-size 10Mi --oos-upload-concurrency 10000  --oos-attempt-resume-upload --oos-leave-parts-on-error sync ./artifacts  remote:bucket -vv

Authentication Providers

OCI has various authentication methods. To learn more about authentication methods please refer oci authentication methods These choices can be specified in the rclone config file.

Rclone supports the following OCI authentication provider.

User Principal
Instance Principal
Resource Principal
Workload Identity
No authentication

User Principal

Sample rclone config file for Authentication Provider User Principal:

[oos]
type = oracleobjectstorage
namespace = id<redacted>34
compartment = ocid1.compartment.oc1..aa<redacted>ba
region = us-ashburn-1
provider = user_principal_auth
config_file = /home/opc/.oci/config
config_profile = Default

Advantages:

• One can use this method from any server within OCI or on-premises or from other cloud provider.

Considerations:

• you need to configure user’s privileges / policy to allow access to object storage
• Overhead of managing users and keys.
• If the user is deleted, the config file will no longer work and may cause automation regressions that use the user’s credentials.

Instance Principal

An OCI compute instance can be authorized to use rclone by using it’s identity and certificates as an instance principal. With this approach no credentials have to be stored and managed.

Sample rclone configuration file for Authentication Provider Instance Principal:

[opc@rclone ~]$ cat ~/.config/rclone/rclone.conf
[oos]
type = oracleobjectstorage
namespace = id<redacted>fn
compartment = ocid1.compartment.oc1..aa<redacted>k7a
region = us-ashburn-1
provider = instance_principal_auth

Advantages:

• With instance principals, you don’t need to configure user credentials and transfer/ save it to disk in your compute instances or rotate the credentials.
• You don’t need to deal with users and keys.
• Greatly helps in automation as you don’t have to manage access keys, user private keys, storing them in vault, using kms etc.

Considerations:

• You need to configure a dynamic group having this instance as member and add policy to read object storage to that dynamic group.
• Everyone who has access to this machine can execute the CLI commands.
• It is applicable for oci compute instances only. It cannot be used on external instance or resources.

Resource Principal

Resource principal auth is very similar to instance principal auth but used for resources that are not compute instances such as serverless functions. To use resource principal ensure Rclone process is started with these environment variables set in its process.

export OCI_RESOURCE_PRINCIPAL_VERSION=2.2
export OCI_RESOURCE_PRINCIPAL_REGION=us-ashburn-1
export OCI_RESOURCE_PRINCIPAL_PRIVATE_PEM=/usr/share/model-server/key.pem
export OCI_RESOURCE_PRINCIPAL_RPST=/usr/share/model-server/security_token

Sample rclone configuration file for Authentication Provider Resource Principal:

[oos]
type = oracleobjectstorage
namespace = id<redacted>34
compartment = ocid1.compartment.oc1..aa<redacted>ba
region = us-ashburn-1
provider = resource_principal_auth

Workload Identity

Workload Identity auth may be used when running Rclone from Kubernetes pod on a Container Engine for Kubernetes (OKE) cluster. For more details on configuring Workload Identity, see Granting Workloads Access to OCI Resources. To use workload identity, ensure Rclone is started with these environment variables set in its process.

export OCI_RESOURCE_PRINCIPAL_VERSION=2.2
export OCI_RESOURCE_PRINCIPAL_REGION=us-ashburn-1

No authentication

Public buckets do not require any authentication mechanism to read objects. Sample rclone configuration file for No authentication:

[oos]
type = oracleobjectstorage
namespace = id<redacted>34
compartment = ocid1.compartment.oc1..aa<redacted>ba
region = us-ashburn-1
provider = no_auth

Modification times and hashes

The modification time is stored as metadata on the object as opc-meta-mtime as floating point since the epoch, accurate to 1 ns.

If the modification time needs to be updated rclone will attempt to perform a server side copy to update the modification if the object can be copied in a single part. In the case the object is larger than 5Gb, the object will be uploaded rather than copied.

Note that reading this from the object takes an additional HEAD request as the metadata isn’t returned in object listings.

The MD5 hash algorithm is supported.

Multipart uploads

rclone supports multipart uploads with OOS which means that it can upload files bigger than 5 GiB.

Note that files uploaded both with multipart upload and through crypt remotes do not have MD5 sums.

rclone switches from single part uploads to multipart uploads at the point specified by --oos-upload-cutoff. This can be a maximum of 5 GiB and a minimum of 0 (ie always upload multipart files).

The chunk sizes used in the multipart upload are specified by --oos-chunk-size and the number of chunks uploaded concurrently is specified by --oos-upload-concurrency.

Multipart uploads will use --transfers * --oos-upload-concurrency * --oos-chunk-size extra memory. Single part uploads to not use extra memory.

Single part transfers can be faster than multipart transfers or slower depending on your latency from oos - the more latency, the more likely single part transfers will be faster.

Increasing --oos-upload-concurrency will increase throughput (8 would be a sensible value) and increasing --oos-chunk-size also increases throughput (16M would be sensible). Increasing either of these will use more memory. The default values are high enough to gain most of the possible performance without using too much memory.

Options

Standard options

The wizard asks for these when you add the drive.

provider

Choose your Auth Provider

Type: string · Default: env_auth

Choices:

• env_auth: automatically pickup the credentials from runtime(env), first one to provide auth wins
• user_principal_auth: use an OCI user and an API key for authentication. you’ll need to put in a config file your tenancy OCID, user OCID, region, the path, fingerprint to an API key. https://docs.oracle.com/en-us/iaas/Content/API/Concepts/sdkconfig.htm
• instance_principal_auth: use instance principals to authorize an instance to make API calls. each instance has its own identity, and authenticates using the certificates that are read from instance metadata. https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm
• workload_identity_auth: use workload identity to grant OCI Container Engine for Kubernetes workloads policy-driven access to OCI resources using OCI Identity and Access Management (IAM). https://docs.oracle.com/en-us/iaas/Content/ContEng/Tasks/contenggrantingworkloadaccesstoresources.htm
• resource_principal_auth: use resource principals to make API calls
• no_auth: no credentials needed, this is typically for reading public buckets

namespace

Object storage namespace

Type: string · Required

compartment

Specify compartment OCID, if you need to list buckets.

List objects works without compartment OCID.

Type: string

Only for providers: !no_auth

region

Object storage Region

Type: string · Required

endpoint

Endpoint for Object storage API.

Leave blank to use the default endpoint for the region.

Type: string

config_file

Path to OCI config file

Type: string · Default: ~/.oci/config

Only for providers: user_principal_auth

Choices:

• ~/.oci/config: oci configuration file location

config_profile

Profile name inside the oci config file

Type: string · Default: Default

Only for providers: user_principal_auth

Choices:

• Default: Use the default profile

Advanced options

The wizard shows these under Advanced options. Most drives work without changing any of them.

storage_tier

The storage class to use when storing new objects in storage. https://docs.oracle.com/en-us/iaas/Content/Object/Concepts/understandingstoragetiers.htm

Type: string · Default: Standard

Choices:

• Standard: Standard storage tier, this is the default tier
• InfrequentAccess: InfrequentAccess storage tier
• Archive: Archive storage tier

upload_cutoff

Cutoff for switching to chunked upload.

Any files larger than this will be uploaded in chunks of chunk_size. The minimum is 0 and the maximum is 5 GiB.

Type: SizeSuffix · Default: 200Mi

chunk_size

Chunk size to use for uploading.

When uploading files larger than upload_cutoff or files with unknown size (e.g. from “rclone rcat” or uploaded with “rclone mount” they will be uploaded as multipart uploads using this chunk size.

Note that “upload_concurrency” chunks of this size are buffered in memory per transfer.

If you are transferring large files over high-speed links and you have enough memory, then increasing this will speed up the transfers.

Rclone will automatically increase the chunk size when uploading a large file of known size to stay below the 10,000 chunks limit.

Files of unknown size are uploaded with the configured chunk_size. Since the default chunk size is 5 MiB and there can be at most 10,000 chunks, this means that by default the maximum size of a file you can stream upload is 48 GiB. If you wish to stream upload larger files then you will need to increase chunk_size.

Increasing the chunk size decreases the accuracy of the progress statistics displayed with “-P” flag.

Type: SizeSuffix · Default: 5Mi

max_upload_parts

Maximum number of parts in a multipart upload.

This option defines the maximum number of multipart chunks to use when doing a multipart upload.

OCI has max parts limit of 10,000 chunks.

Rclone will automatically increase the chunk size when uploading a large file of a known size to stay below this number of chunks limit.

Type: int · Default: 10000

upload_concurrency

Concurrency for multipart uploads.

This is the number of chunks of the same file that are uploaded concurrently.

If you are uploading small numbers of large files over high-speed links and these uploads do not fully utilize your bandwidth, then increasing this may help to speed up the transfers.

Type: int · Default: 10

copy_cutoff

Cutoff for switching to multipart copy.

Any files larger than this that need to be server-side copied will be copied in chunks of this size.

The minimum is 0 and the maximum is 5 GiB.

Type: SizeSuffix · Default: 4.656Gi

copy_timeout

Timeout for copy.

Copy is an asynchronous operation, specify timeout to wait for copy to succeed

Type: Duration · Default: 1m0s

disable_checksum

Don’t store MD5 checksum with object metadata.

Normally rclone will calculate the MD5 checksum of the input before uploading it so it can add it to metadata on the object. This is great for data integrity checking but can cause long delays for large files to start uploading.

Type: bool · Default: false

encoding

The encoding for the backend.

See the encoding section in the overview for more info.

Type: Encoding · Default: Slash,InvalidUtf8,Dot

leave_parts_on_error

If true avoid calling abort upload on a failure, leaving all successfully uploaded parts for manual recovery.

It should be set to true for resuming uploads across different sessions.

WARNING: Storing parts of an incomplete multipart upload counts towards space usage on object storage and will add additional costs if not cleaned up.

Type: bool · Default: false

attempt_resume_upload

If true attempt to resume previously started multipart upload for the object. This will be helpful to speed up multipart transfers by resuming uploads from past session.

WARNING: If chunk size differs in resumed session from past incomplete session, then the resumed multipart upload is aborted and a new multipart upload is started with the new chunk size.

The flag leave_parts_on_error must be true to resume and optimize to skip parts that were already uploaded successfully.

Type: bool · Default: false

no_check_bucket

If set, don’t attempt to check the bucket exists or create it.

This can be useful when trying to minimise the number of transactions rclone does if you know the bucket exists already.

It can also be needed if the user you are using does not have bucket creation permissions.

Type: bool · Default: false

sse_customer_key_file

To use SSE-C, a file containing the base64-encoded string of the AES-256 encryption key associated with the object. Please note only one of sse_customer_key_file|sse_customer_key|sse_kms_key_id is needed.’

Type: string

Choices:

• (empty): None

sse_customer_key

To use SSE-C, the optional header that specifies the base64-encoded 256-bit encryption key to use to encrypt or decrypt the data. Please note only one of sse_customer_key_file|sse_customer_key|sse_kms_key_id is needed. For more information, see Using Your Own Keys for Server-Side Encryption (https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm)

Type: string

Choices:

• (empty): None

sse_customer_key_sha256

If using SSE-C, The optional header that specifies the base64-encoded SHA256 hash of the encryption key. This value is used to check the integrity of the encryption key. see Using Your Own Keys for Server-Side Encryption (https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm).

Type: string

Choices:

• (empty): None

sse_kms_key_id

if using your own master key in vault, this header specifies the OCID (https://docs.cloud.oracle.com/Content/General/Concepts/identifiers.htm) of a master encryption key used to call the Key Management service to generate a data encryption key or to encrypt or decrypt a data encryption key. Please note only one of sse_customer_key_file|sse_customer_key|sse_kms_key_id is needed.

Type: string

Choices:

• (empty): None

sse_customer_algorithm

If using SSE-C, the optional header that specifies “AES256” as the encryption algorithm. Object Storage supports “AES256” as the encryption algorithm. For more information, see Using Your Own Keys for Server-Side Encryption (https://docs.cloud.oracle.com/Content/Object/Tasks/usingyourencryptionkeys.htm).

Type: string

Choices:

• (empty): None
• AES256: AES256

decompress

If set this will decompress gzip encoded objects.

It is possible to upload objects to object storage with “Content-Encoding: gzip” set. Normally rclone will download these files as compressed objects.

If this flag is set then rclone will decompress these files with “Content-Encoding: gzip” as they are received. This means that rclone can’t check the size and hash but the file contents will be decompressed.

Type: bool · Default: false

description

Description of the remote.

Type: string

Tutorials

Mounting Buckets