How to use cunoFS#

By default, cunoFS is configured for Core File Access which does not write additional cunoFS metadata to your buckets. Once you’re up and running, you can change the mode of operation to better suit your requirements.

For program calls to be routed through cunoFS, they must be either directly intercepted using the cuno command line; or pointed at a cunoFS Mount (a custom FUSE mount) set up using cuno mount. There is also cunoFS FlexMount, which makes use of both Direct Interception and a cunoFS Mount as a fallback.

Note

If you have a specialised use case, follow the relevant quick start guide:

Direct Interception with cunoFS CLI#

When running in Direct Interception mode, cunoFS will insert itself between your applications and the operating system. It will dynamically redirect relevant filesystem calls made by the application through the API of your object storage solution. As a result, our mapping between filesystem concepts and object storage gives any application instant access to objects as files.

Note

This includes applications you’ve written yourself - just treat the paths to object storage as local filesystem paths, and cunoFS handles the rest.

Direct Interception offers the highest performance access to object storage that cunoFS provides.

Warning

Direct interception does not currently support SUID binaries, or certain packaged apps like Snap, AppImage, or Flatpak applications. Future updates are planned to address this.

This mode is best suited for situations in which installed app compatibility is not a concern - for example, when setting up a fixed workflow with cunoFS that can be tested and verified before putting it into production.

Usage#

Direct Interception can be enabled per-session or per-command. Enable it for a session by calling cuno on the command line:

cuno

This will launch a new interactive “wrapped” shell with cunoFS acting in Direct Interception mode. The shell itself has cunoFS intercepting its calls, so every application launched from within it can be intercepted as well as the command line arguments being used.

Note

When the cunoFS CLI is used to launch a new shell, the primary purpose is to start a new shell (whether that’s bash, zsh, or whatever else) with LD_PRELOAD set to point at cuno.so. There is no cunoFS shell binary - it only wraps existing shells with cunoFS pre-loaded.

Inside the shell, object storage is accessed either in path or URI formats:

$ cuno
(cuno)$ ls s3://<bucket>/<path>
(cuno)$ ls /cuno/s3/<bucket>/<path>

See Transparent access to object storage for more information, options and examples of specfiying cloud paths using cunoFS CLI.

See User Guide: Direct Interception with cunoFS CLI for additional information, including how it works, as well as the benefits and drawbacks of using cunoFS in this way.

cunoFS Mount#

cunoFS Mount allows you to mount an object storage path in a directory within the local file system hierarchy. This allows you (and any other user with access to the mount) to access object storage as if it were just another local directory.

cunoFS Mount is a FUSE file system that routes calls through the cunoFS object storage back-end. Due to the nature of FUSE file systems, this is usually less performant than Direct Interception. However, you can still expect great performance.

Usage#

A default mount can be achieved using:

mkdir ~/my-object-storage
cuno mount ~/my-object-storage

Any paired object storage buckets will now be accessible through the mount:

ls ~/my-object-storage/s3/<bucket>/<path>

For directions on unmounting, configuration options and further information, see the user guide section on cunoFS Mount.

cunoFS FlexMount#

Use cunoFS FlexMount for the widest compatibility and support (including SUID binaries, Snap, AppImage and FlatPak applications using FUSE), combined with the speed of Direct Interception when possible.

FlexMount is used by setting up a cunoFS Mount and then accessing the cloud using cunoFS CLI always “through” the mount path. CunoFS will recognise that the path is a mount and use direct interception where possible for faster access. It will naturally fall back to the cunoFS Mount for anything that cannot be directly intercepted.

Usage#

A FlexMount is set up as follows:

  1. First, set up a cunoFS Mount:

    $ mkdir "$HOME/my-object-storage"
$ cuno mount "$HOME/my-object-storage"

  2. Each time the cunoFS CLI is launched, use the --flex <full path to mountpoint>" parameter, for example:

    $ cuno --flex "$HOME/my-object-storage"
(cuno) $ ls $HOME/my-object-storage/s3/<bucket>/<path>

    Warning

    You cannot use a tilde ~ in your CUNO_OPTIONS or cuno -o CLI options when setting up a FlexMount as this is something that the shell needs to resolve. You may still use it for your cuno mount commands, and subsequent FlexMount operations (such as ls ~/my-object-storage).

The same FlexMount can be re-used across multiple cunoFS wrapped shells.

The --flex option can also be used with cuno run to run a single command/script with cunoFS enabled, for example:

cuno run --flex "$HOME/my-object-storage" bash -c "touch $HOME/object_storage_mount/s3/<bucket>/newfile"

For more information and configuration options, see the user guide section on cunoFS FlexMount.

Enabling cunoFS in other environments#

For information on setting up Docker containers with cunoFS pre-loaded, automatically setting up a cunoFS Mount at boot, and other containerisation and HPC use-cases, see Advanced Loading.