cuno

Synopsis

cuno [--verbose|-v] [--option|-o <cunoFS option>] [--posix] [<command>] [<args>]

Options

--verbose, -v

Make cuno produce verbose output. Note that this is not the same as enabling CUNO_CLOUD_DEBUG! It only makes the cuno command itself verbose, not applications launched inside it.

-o, --option <cunoFS option>

Set a cunoFS option. Multiple options can be specified by providing multiple -o arguments. Together, cunoFS options set in this way are appended to those set via CUNO_OPTIONS. See the CONFIGURATION OPTIONS below for details.

--posix

Sets the environment variable CUNO_POSIX=1 to enable POSIX File Access mode. This is useful for short-term use of applications that expect POSIX semantics, such as rsync or tar.

Not to be confused with cuno mount --posix, which is required when mounting POSIX buckets with cunoFS Mount.

This will not write or override any bucket tags set, so should you should prefer to consistently enable POSIX File Access for all users/usages of a bucket by setting the tag cuno creds setposix <xx://bucket> true.

Commands

cuno shell [--flex|-f <path to mount>]

Enables cunoFS Direct Interception by launching a new interactive “wrapped” shell with cunoFS. 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.

The fully-supported shells are bash, and zsh. To select between them, this command checks the shell used to launch this command, the user’s preferred login shell, and installed shells. If unsatisfied, cuno shell will launch the first shell found (in the same search order). If no other shell is found, /bin/sh is used.

With no command set, cuno behaves like cuno shell.

cuno run <command>

Run a single shell command as if invoked directly, but with cunoFS loaded. The command should be an unquoted command line, e.g.:

cuno run ls -l s3://some-bucket

cuno creds [import | purge | pair | unpair | list | setposix | info | billing | upgrade | activate | deactivate | help] [<args>]

Launch the cunoFS Credentials Manager utility to import and manage credentials / bucket pairings. See cuno-creds(1) for details.

cuno mount [--unmount|-u] <mount-point> [<args>]

Mount or unmount a cunoFS Mount via FUSE. See cuno-mount(1) for details.

cuno version

Print out version information.

cuno help [shell | run | creds | mount | fusion]

Display the manual pages for one of the subcommands.

Environment

CUNO_CREDENTIALS

The location of imported cunoFS credentials. The default location is $XDG_CONFIG_HOME/cuno/creds (if unset, $XDG_CONFIG_HOME defaults to ~/.config). If the CUNO_CREDENTIALS environment variable is set but the path does not exist, cunoFS will next examine the default location. If that does not exist either, cunoFS will try to fall back to the path cuno-config/creds adjacent to the cunoFS installation directory; that is, /opt/cuno-config/creds or ~/.local/opt/cuno-config/creds for the default system or user local installation, respectively.

CUNO_OPTIONS

A whitespace-separated list of options to pass to cunoFS. See CONFIGURATION OPTIONS for details.

CUNO_POSIX

Default is 0 so cunoFS operates in Core File Access mode unless a tag has been on the bucket being accessed. If set to 1, cunoFS will enable POSIX File Access mode. This is useful for short-term use of applications that expect POSIX semantics, such as rsync or tar.

CUNO_LOG

There are rare occasions where cunoFS will output to the command line, and this will generally indicate a fault. All messages will be prefixed with [CUNO] and these will always be sent a to the standard error stream (stderr).

The options available for CUNO_LOG are cumulative and build on the previous level:

error

Only critical failures are output. (default)

warning

Errors and warnings.

debug

Information relevant to debugging.

trace

Very verbose verbiage.

CUNO_BASEDIR

The base directory of the cunoFS installation. Can be provided to cuno if is launched from an alternative location. If specified, it needs to be the cunoFS installation path ending in cuno, not its parent directory. Only useful if you have moved the cuno binary out of the installation directory.

Configuration options

Setting the environment variable CUNO_OPTIONS can be used to further configure cunoFS, including (for most options) while already running. Note that multiple options must be separated by spaces. Do not forget to escape these spaces, e.g. by quoting them. Here are the available options for CUNO_OPTIONS:

off	Disable cunoFS access.
+static	Enable interception of statically compiled binaries. (default)
-static	Disable interception of statically compiled binaries.
+closekeepcache=[N]	Keep recently closed virtual files cached for N*0.1 seconds. This helps the performance of applications like Apache which frequently open/close/reopen files. (Disabled by default, if N not specified then 1 second by default, i.e. N=10)
+cloud	Enable cloud access using both xx:// and /cuno/xx formats. (default)
-cloud	Disable cloud access. If followed by +urifile, then only xx:// formats are enabled.
+urifile=strict	Enable cloud access using strict URI formats such as xx://.
+urifile	Slight variations of URI format xx:// are also accepted, e.g., /xx://, /xx:/ , xx:/. (default)
+urifile=any	/xx:/ is recognized anywhere in the full given path to a file. Everything before the xx:/ is ignored. e.g. /my/path/s3:/bucket/object is interpreted as s3://bucket/object.
-urifile	Disable cloud access using URIs such as xx:// and other variations.
+uricompat=[binary1:binary2:...]	When a paired URI is detected, and if the binary is a member of this colon-separated list, then URI remapping is enforced, instead of the binary’s own URI handling scheme. Can also be wildcard * to mean all binaries.
-uricompat	Disable URI remapping scheme for all binaries.
-forceuri	URI remapping is enforced for all URIs, not just paired URIs.
+hardlink	Enable hard link functionality. (default ONLY when POSIX File Access is enabled)
-hardlink	Disable hard link functionality.
+cloudroot=[directory]	Define a custom directory path prefix that will be used instead of ‘/cuno’ to introduce cloud locations. For how this relates to FlexMount and the effects of setting cloudroot when mounting a cunoFS Mount, see the user-guide-cloudroot section. Using a tilde, ‘~’, in the path is unsupported. (default: /cuno)
-cloudrootover	cunoFS Direct Interception will prioritise the cunoFS Mount at the path specified by the cloudroot option. This means that any intercepted calls to a location within the cloudroot path will be handled by the cunoFS Mount at that location. This disables FlexMount mode, equivalent to ‘cloudrootover=off’. (default)
+cloudrootover	cunoFS Direct Interception will prioritise itself over anything at the path specified by cloudroot, but only if the input path exactly matches the text in cloudroot, equivalent to ‘cloudrootover=exact’. Use this to enable FlexMount behavior at the cloudroot.
cloudrootover=[off,exact,resolve,exe,<path-to-cunoFS-mount]	These settings affect what happens to when cunoFS Direct Interception (i.e. when cunoFS CLI is launched or LD_PRELOAD is set) encounters a path which already exists on the local filesystem, and affects the FlexMount behaviour if that local path refers to a cunoFS Mount. See the descriptions of each individual setting to learn more about what they do. (default: off)
cloudrootover=off	cunoFS Direct Interception will prioritise local directories, including the cunoFS Mount at the path specified by the cloudroot option. This means that any intercepted calls to a location within the cloudroot path will be handled by the cunoFS Mount at that location. This disables FlexMount mode. (default)
cloudrootover=exact	cunoFS Direct Interception will prioritise itself over local directories at the path specified by cloudroot, but only if the input path exactly matches the text in cloudroot. This also disables cunoFS Direct Interception’s static binary translator and cloud binary interception, so static binaries and binaries in object storage are passed through to the cunoFS Mount at the cloudroot. Use this to enable FlexMount behavior at the cloudroot.
cloudrootover=resolve	cunoFS Direct Interception will prioritise itself over anything that resolves to the same local path as the path specified by cloudroot. This also disables cunoFS Direct Interception’s static binary translator, so static binaries and binaries in object storage are passed through to the cunoFS Mount at the cloudroot. Use this to enable FlexMount behavior at the cloudroot, in a more resilient way.
cloudrootover=exe	cunoFS Direct Interception of static binaries and binaries on object storage will be re-enabled. Must be used in conjunction with a FlexMount-enabling cloudrootover option. This also enables ‘cloudrootover=resolve’.
cloudrootover=<path-to-cunoFS-mount>	The <path-to-cunoFS-mount> only needs to specified if an explicit ‘–root’ option was used when creating the cunoFS Mount. In this case, assuming the ‘–root’ value was set to a bucket or a directory on object storage (e.g. ‘cuno mount “$HOME/mybucket” –root /cuno/s3/mybucket/foo’), then you must set cloudrootover to the mount point AND not set cloudroot when launching cunoFS CLI to use the mount as FlexMount (e.g. ‘cuno -o cloudrootover=”$HOME/mybucket”’). This also implies ‘cloudrootover=exact’. If a cloudroot option was specified when creating the cunoFS Mount, or the –root option was used when creating the mount and refers to anywhere that isn’t inside the default cunoFS Mount cloudroot (‘/cuno’), then refer to the user-guide-cloudroot. Using a tilde, ‘~’, in the path is unsupported.
-cloudrootoverunload	We prefer that certain shells and debuggers (e.g. sh, tsh and gdb) disable/unload cunoFS Direct Interception in FlexMount-enabled modes for stability. Note that Direct Interception is re-enabled for any programs that they launch. This option disables this unloading behaviour. Warning: this may break things when you run these shells.
+cloudrootoverunload	We prefer that certain shells and debuggers (e.g. sh, tsh and gdb) disable cunoFS Direct Interception in cloudrootover enabled modes for stability. This option disables cunoFS Direct Interception (enables un-loading) when cloudrootover is enabled. (default)
cloudrootoverunload=[binary1:binary2:...]	Colon-separated list of paths to binaries. We prefer that certain shells and debuggers (e.g. sh, tsh and gdb) disable cunoFS Direct Interception in FlexMount-enabled modes for stability. This option disables cunoFS Direct Interception (enables un-loading) when FlexMount is enabled and one of binaries specified is launched. (default: bin/sh:bin/tsh:bin/gdb)
cloudrootoverunload=+<path-to-binary>	Appends <path-to-binary> to the list of ‘cloudrootoverunload’ binaries. This option will disable cunoFS Direct Interception (enable un-loading) in FlexMount-enabled modes when the specified binary is launched.
-cachehome	Disable cunoFS high performance metadata caching.
+cachehome=[directory]	Enable cunoFS high performance metadata caching and optionally set a semicolon-delimited list of directories to consider for caching (default: /cunodb;/dev/shm). If none of these directories exist, fall back to /tmp/cache/cuno. (default)
retry-multiplier=[decimal]	Scaling factor for the number of retries for non-fatal failed requests made to the server, e.g. CUNO_OPTIONS="retry-multiplier=1.5" increases the number of retries by 50%. If not set, the default multiplier value is set to 1. Accepted values are from 0 (disables retries) to 10000.
uid=[integer]	Define the default user ownership of files and directories within a bucket. Supply the user identifier in the numerical representation derived from id --user <USERNAME>.
gid=[integer]	Define the default group ownership of files and directories within a bucket. Supply the group identifier in the numerical representation derived from id --group <USERNAME>.
filemode=[octal]	Define the default file access permission bits of files within a bucket. Supply the octal (numeric) representation of the permissions you want to apply.
dirmode=[octal]	Define the default file access permission bits of directories within a bucket. Supply the octal (numeric) representation of the permissions you want to apply.
reset	Resetting discards any options from previous CUNO_OPTIONS assignments within the current shell. Subcommands only see the current CUNO_OPTIONS.

See also

cuno-shell(8), cuno-creds(1), cuno-mount(1)