Basic loading#

cunoFS may be loaded in a number of ways, depending on user requirements and environment.

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.

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.

To enable direct interception of a single command, use:

cuno run bash -c "<your command and arguments>"

Note

Always execute one-time commands this way to maintain support for wildcard expansion (*) .

Note

How it works

Direct interception uses the LD_PRELOAD environment variable so that cunoFS can capture and redirect storage access library and system calls through object storage APIs. If a static binary is intercepted, a JIT ELF binary translator will redirect relevant calls when the binary is loaded into memory.

Advantages and Disadvantages#

Direct Interception - Advantages and Disadvantages :header-rows: 1 :widths: 1 1#

Advantages

Disadvantages

Speed: Dynamic interception offers the best performance.

Compatibility: Direct interception does not currently support SUID binaries, Snaps, AppArmor, or Flatpak applications.

Set up time: This is the default; all you have to do is launch a cunoFS shell with the cuno command line utility. No FUSE mount set up is required.

Activation: In some cases, it is difficult to enable direct interception or keep it enabled (because of environment variable clobbering or lack of privileges to set use LD_PRELOAD).

_

Non-technical users: If cunoFS is being used by many people in an organization, teaching people how to use the cunoFS shell and diagnose if it’s working correctly may be less desirable than setting up a cunoFS Mount on their behalf.

Usage#

When Direct Interception is enabled using cuno or cuno run <command>, 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 using Direct Interception with the cunoFS CLI.

Fully supported shells#

bash and zsh are fully supported when using cunoFS CLI. This includes support for:

  • tab auto-completion of remote paths;

  • wildcard expansion (*) of filesystem and remote paths.

In either of these fully-supported shells, the prompt will be prefixed with (cuno) to indicate that Direct Interception is enabled and that you are using a cunoFS CLI shell, like so:

(cuno) user@host:~$

Note

To select between the two shells, cunoFS detects if either is present in one of the following, in order:

  1. the shell used to launch cunoFS;

  2. the user’s preferred login shell;

  3. all installed shells.

If neither bash nor zsh are found, then the first shell in this list is used. If no shell is set, then /bin/sh is used.

To launch a specific shell with cunoFS enabled, use cuno run:

cuno run <shell>

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 of the mount to access object storage as if it were just another directory.

cunoFS Mount uses Linux FUSE (Filesystem in Userspace) v3 to mount an object storage path in a directory within the file system hierarchy. Due to the nature of FUSE file systems, cunoFS Mount is usually less performant than Direct Interception using cunoFS CLI. Consider using cunoFS CLI or the userspace library (described in User-mode library) if speed is the primary objective.

Note

The --posix option requires that a FUSE package be installed on the system.

Advantages#

  1. Compatibility: use a cunoFS Mount when extensively using cunoFS with a variety of operating systems, applications or when compatibility is a particular concern.

  2. Simple usage: after a mount is set up, scripts only need to be changed to point at it, without any further changes to the workflow. No environment variables need to be set, and no cunoFS-wrapped shell has to be launched.

  3. Greater admin control: a centralised cunoFS Mount can be set up by an admin, without giving users any credentials. This allows the admin to abstract away the concepts of object storage entirely from users.

  4. When launching the cuno binary is not possible (limited cases, e.g. an automation engine without the required features, TODO: real example).

Disadvantages#

  1. You cannot use URI paths like “s3://bucket1/foo” directly when using a cunoFS mount. To convert such a path to be usable, you need to replace the URI prefix (s3://) with the path to your mount.

Usage#

cuno mount [-o allow_other] [-o allow-root] [--auto-restart] [--posix] [--root <object-path>] <mount-path>

These options are explained in the following table.

cunoFS Mount options#

Option

Description

-o allow_other

Allows other users to access the mount; requires user_allow_other in /etc/fuse.conf.

-o allow_root

Allows root access to the mount; required for SUID permissions.

--auto-restart

Automatically restarts cunoFS Mount if problems occur during execution.

--posix

Enables setting and enforcing access permissions, symbolic and hard links, users, groups, and access control lists (ACLs). Can be used with default permissions.

--root <object-path>

Specifies the root object path for the mount operation.

CUNO_OPTIONS

Additional settings for configuring cunoFS Mount; refer to Configuration options for more information.

Mount on boot#

You can info add mount commands to /etc/fstab to automount on start up.

Unmounting#

To unmount a cunoFS Mount from <mount-path>, use the command:

cuno mount -u <mount-path>

or

cuno mount --unmount <mount-path>

cunoFS FlexMount#

cunoFS FlexMount is for when the speed of direct interception is preferred whenever it is possible to use, but wider-support for different contexts and types of applications is also required.

FlexMount is used by setting up a cunoFS Mount and then accessing the cloud using cunoFS CLI.

Usage#

A FlexMount is set up as follows:

  1. First, set up a cunoFS Mount, with a cloudroot set:

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

  1. Each time a cunoFS CLI is launched, use the parameters -o cloudrootover -o cloudroot="<full-path-to-mountpoint>", for example:

$ cuno -o cloudrootover -o cloudroot="~/my-object-storage"
(cuno) $ ls ~/object_storage_mount/s3/<bucket>/<path>

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

The cloudrootover can be configured to exact string matching (exact) or path resolution matching (resolve) for identifying interception. By default it acts in exact string matching mode for speed, and thus relies on the slower FUSE mount in cases where paths don’t match the cloudroot - for example with symbolic links located outside the mount pointing into the mount. The resolve mode will do full resolution of paths including symbolic links to check if the file is ultimately located inside the mount point. To use resolve mode use the parameters -o cloudrootover=resolve -o cloudroot="<full-path-to-mountpoint>", for example:

$ cuno -o cloudrootover=resolve -o cloudroot="~/my-object-storage"
(cuno) $ ls ~/object_storage_mount/s3/<bucket>/<path>

Advantages#

  1. Speed: where interception is possible, cunoFS in FlexMount mode will be as fast as cunoFS

  2. Support: support for all POSIX applications, as anything that cannot be directly intercepted falls through to the cunoFS Mount.

Disadvantages#

  1. Set up time: a cunoFS Mount needs to be set up. Consider setting up the mount at boot.

  2. Launch is more complicated: each time a cunoFS shell is launched it must be configured to use the mount. This can be worked around by setting