OCIFS Utility

OCIFS has several mounting restrictions to consider.

Before mounting an Object Storage bucket with OCIFS, review the OCIFS 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 OCIFS.

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) 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.<id>) 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.<id>'}

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.

You can change the OCIFS cache directory with the 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

The cache-keep option lets you retain the cache, even if the OCIFS file system is unmounted.

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

For example, to mount a bucket and have the cache preserved when 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 performances the next time you mount the file system. However, OCIFS doesn't check if there any discrepancies between data in cache and the actual data in the Object Storage bucket.

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

By default, the 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 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 cache purge delay can be specified as listed in the following table:

The 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 a bucket (bucket-1) 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 had crashed.
• Reusing an existing cache can improve performance as OCIFS 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.