OCIFS Utility

OCIFS has several mounting restrictions to consider before mounting an Object Storage bucket.

Review the following mounting rules and restrictions:

• File Types, Attributes and Sizing

• Naming Rules

• Data Synchronization

Specify and configure the API key-based authentication method to mount Object Storage buckets with OCIFS.

API key-based authentication is the default authentication method for OCIFS, and can be used from an OCI compute instance or from any other system. This authentication method requires a local OCI SDK and a CLI configuration file. You can specify the configuration file by using the config=file option with the ocifs command. By default, the configuration file is ~/.oci/config.

$ ocifs --auth=api_key --config=~/my_config bucket-1 mydir

Before mounting an Object Storage bucket using the API key-based authentication method, ensure that the CLI configuration file (~/.oci/config) has a [DEFAULT] profile, and the entries specified in the following table.

For more information, see SDK and CLI Configuration File.

Instead of the default API key-based authentication method, you can use the instance principal authentication method with the OCIFS utility.

Use the instance principal authentication method for OCIFS only from an authorized Oracle Cloud Infrastructure instance. This authentication method lets specified instances access Object Storage without a CLI configuration file. The instance then automatically discovers information to authenticate.

Instance principal authentication must be used to mount an Object Storage bucket on a compute instance that has been configured as an instance principal.

For example, to mount an Object Storage bucket, bucket-1, on the mydir directory using instance principal authentication:

$ ocifs --auth=instance_principal bucket-1 mydir

To use instance principal authentication, a compute instance must be part of a dynamic group, and a policy must allow the dynamic group to manage Object Storage. You can use the manage object-family verb and resource type to define a policy that allows managing of Object Storage objects. For more information about dynamic groups, see Managing Dynamic Groups.

For example, to allow a compute instance (with instance id ocid1.instance.OCID) to use instance principal authentication:

1. Create a dynamic group dgroup-ocifs with the following rule that matches the compute instance:

   All {instance.id = 'ocid1.instance.OCID'}

2. Create a policy that allows that dynamic group, dgroup-ocifs, to manage Object Storage:

   Allow dynamic-group dgroup-ocifs to manage object-family in compartment id ocid1.tenancy.tenancy_ID

For more information, see Calling Services from an Instance.

Instead of the default API key-based authentication method, you can use the resource principal authentication method with OCIFS.

Use the resource principal authentication method with OCIFS only from an authorized Oracle Cloud Infrastructure (OCI) function. This authentication method lets the specified function access another resource, or Object Storage, without a CLI configuration file. The OCI function then automatically discovers information to authenticate.

To use resource authentication, an OCI function must be part of a dynamic group, and a policy must allow the dynamic group to access that resource, or Object Storage. For more information about dynamic groups, see Managing Dynamic Groups.

For information about OCI functions accessing other OCI resources, see Accessing Other Oracle Cloud Infrastructure Resources.

To use the resource authentication method with OCIFS, enter --auth=resource_principal when mounting a bucket with the ocifs command.

For example, to mount an Object Storage bucket, bucket-1, on the mydir directory using resource principal authentication:

$ ocifs --auth=resource_principal bucket-1 mydir

You can change the OCIFS cache directory with the ocifs command cache=path option.

By default, OCIFS caches objects in ~/.ocifs/. You can change this cache directory using the cache=path option. This option sets the cache directory to the specified path. The path can be an absolute path or relative path to the user's home directory.

$ ocifs --cache=/var/tmp/ocifs-cache bucket-1 mydir

You can retain the OCIFS cache with the ocifs command cache-keep option, even if the OCIFS file system is unmounted.

Unmounting the OCIFS file system removes the OCIFS cache directory, unless you mount the file system with the cache-keep option.

For example, to mount an Object Storage bucket, bucket-1, on the mydir directory, and have the cache preserved after unmounting:

$ ocifs --cache-keep bucket-1 mydir

Notes:

• If you use the cache-keep option, you might be unable to mount the file system again unless you then use the cache-reuse option.
• Keeping data in cache after unmounting the file system can improve performance the next time you mount the file system. However, OCIFS doesn't check if there are any discrepancies between data in cache and the actual data in the Object Storage bucket.

The OCIFS utility cache-purge option lets you remove data from the OCIFS cache for files that have been closed for a specified amount of time.

By default, the OCIFS cache is never purged. The cache data is kept in the cache directory as long as the file system is mounted. The cache directory is only removed when the OCIFS file system is unmounted.

Using the cache-purge option, you can specify the amount of time data remains in cache after a file is closed. You can use this to preserve disk space, especially if files aren't often accessed. This is useful, for example, if you write new files and don't access the files again.

The OCIFS cache purge delay can be specified as listed in the following table:

The OCIFS utility cache-reuse option lets an OCIFS file system be mounted, even if there is an existing, nonempty cache directory.

By default, OCIFS prevents mounting a file system if it has an nonempty cache directory. With the cache-reuse option, you can remount the file system and reuse the existing cache directory, if present.

For example, to mount the Object Storage bucket, bucket-1, on the mydir directory, and reuse the existing cache directory:

$ ocifs --cache-reuse bucket-1 mydir

Notes:

• You can have a nonempty cache directory if the file system was previously mounted with the cache-keep option, or if the ocifs process was killed or has crashed.
• Reusing an existing cache can improve performance, as the OCIFS utility can access data already in the cache more quickly. However, using the cache-reuse option isn't recommended because OCIFS doesn't check for discrepancies between data in cache and the actual data in the Object Storage bucket.

OCIFS lets you determine when it uses mulipart upload to upload large files to Object Storage. With the OCIFS mpu-threshold=size option, you can specify the file size that, above which, multipart upload starts.

The default multipart upload size threshold value is 100 Mebibytes (recommended).

The following table lists the supported mpu-threshold=size option values.