arv-mount options

This page documents all available arv-mount options with some usage examples.

Mount contents
Mount custom layout and filtering
1. --filters usage and limitations
Mount access and permissions
Mount lifecycle management
Mount logging and statistics
Mount local cache setup
Mount interactions with Arvados and Linux
Examples
1. Using --exec
2. Running arv-mount as a systemd service

Mount contents

Option(s)	Description
`--all`	Mount a subdirectory for each mode: `home`, `shared`, `by_id`, and `by_tag` (default if no `--mount-*` options are given)
`--custom`	Mount a subdirectory for each mode specified by a `--mount-` option (default if any `--mount-` options are given; see Mount custom layout and filtering section)
`--collection UUID_OR_PDH`	Mount the specified collection
`--home`	Mount your home project
`--project UUID`	Mount the specified project
`--shared`	Mount a subdirectory for each project shared with you
`--by-id`	Mount a magic directory where collections and projects are accessible through subdirectories named after their UUID or portable data hash
`--by-pdh`	Mount a magic directory where collections are accessible through subdirectories named after their portable data hash
`--by-tag`	Mount a subdirectory for each tag attached to a collection or project

Mount custom layout and filtering

Option(s)	Description
`--filters FILTERS`	Filters to apply to all project, shared, and tag directory contents. Pass filters as either a JSON string or a path to a JSON file. The JSON object should be a list of filters in Arvados API list filter syntax. See the example filters.
`--mount-home PATH`	Make your home project available under the mount at `PATH`
`--mount-shared PATH`	Make projects shared with you available under the mount at `PATH`
`--mount-tmp PATH`	Make a new temporary writable collection available under the mount at `PATH`. This collection is deleted when the mount is unmounted.
`--mount-by-id PATH`	Make a magic directory available under the mount at `PATH` where collections and projects are accessible through subdirectories named after their UUID or portable data hash
`--mount-by-pdh PATH`	Make a magic directory available under the mount at `PATH` where collections are accessible through subdirectories named after portable data hash
`--mount-by-tag PATH`	Make a subdirectory for each tag attached to a collection or project available under the mount at `PATH`

`--filters` usage and limitations

Your argument to --filters should be a JSON list of filters in Arvados API list filter syntax. If your filter checks any field besides uuid, you should prefix it with the <resource type>. Taken together, here’s an example that mounts your home directory excluding filter groups, workflow intermediate output collections, and workflow log collections:

$ arv-mount --home --filters '[["groups.group_class", "!=", "filter"], ["collections.properties.type", "not in", ["intermediate", "log"]]]' ...

Because filters can be awkward to write on the command line, you can also write them in a file, and pass that file path to the --filters option. This example does the same filtering:

$ cat >~/arv-mount-filters.json <<EOF
[
  [
    "groups.group_class",
    "!=",
    "filter"
  ],
  [
    "collections.properties.type",
    "not in",
    [
      "intermediate",
      "log"
    ]
  ]
]
EOF
$ arv-mount --home --filters ~/arv-mount-filters.json ...

The current implementation of --filters has a few limitations. These may be lifted in a future release:

You can always access any project or collection by UUID or portable data hash under a magic directory. If you access a project this way, your filters will apply to the project contents.
Tag directory listings are generated by querying tags alone. Only filters that apply to links will affect these listings.

Mount access and permissions

Option(s)	Description
`--allow-other`	Let other users on this system read mounted data (default false)
`--read-only`	Mounted data cannot be modified from the mount (default)
`--read-write`	Mounted data can be modified from the mount

Mount lifecycle management

Option(s)	Description
`--exec ...`	Mount data, run the specified command, then unmount and exit. `--exec` reads all remaining options as the command to run, so it must be the last option you specify. Either end your command arguments (and other options) with a `--` argument, or specify `--exec` after your mount point.
`--foreground`	Run mount process in the foreground instead of daemonizing (default false)
`--subtype SUBTYPE`	Set mounted filesystem type to `fuse.SUBTYPE` (default is just `fuse`)
`--replace`	If a FUSE mount is already mounted at the given directory, unmount it before mounting the requested data. If `--subtype` is specified, unmount only if the mount has that subtype. WARNING: This command can affect any kind of FUSE mount, not just arv-mount.
`--unmount`	If a FUSE mount is already mounted at the given directory, unmount it and exit. If `--subtype` is specified, unmount only if the mount has that subtype. WARNING: This command can affect any kind of FUSE mount, not just arv-mount.
`--unmount-all`	Unmount all FUSE mounts at or below the given directory, then exit. If `--subtype` is specified, unmount only if the mount has that subtype. WARNING: This command can affect any kind of FUSE mount, not just arv-mount.
`--unmount-timeout SECONDS`	The number of seconds to wait for a clean unmount after an `--exec` command has exited (default 2.0). After this time, the mount will be forcefully unmounted.

Mount logging and statistics

Option(s)	Description
`--crunchstat-interval SECONDS`	Write stats to stderr every N seconds (default disabled)
`--debug`	Log debug information
`--logfile LOGFILE`	Write debug logs and errors to the specified file (default stderr)

Mount local cache setup

Option(s)	Description
`--disk-cache`	Cache data on the local filesystem (default)
`--ram-cache`	Cache data in memory
`--disk-cache-dir DIRECTORY`	Set custom filesystem cache location
`--directory-cache BYTES`	Size of directory data cache in bytes (default 128 MiB)
`--file-cache BYTES`	Size of file data cache in bytes (default 8 GiB for filesystem cache, 256 MiB for memory cache)

Mount interactions with Arvados and Linux

Option(s)	Description
`--disable-event-listening`	Don’t subscribe to events on the API server to update mount contents
`--encoding ENCODING`	Filesystem character encoding (default ‘utf-8’; specify a name from the Python codec registry)
`--retries RETRIES`	Maximum number of times to retry server requests that encounter temporary failures (e.g., server down). Default 10.
`--storage-classes CLASSES`	Comma-separated list of storage classes to request for new collections

Examples

Using `--exec`

There are a couple of details that are important to understand when you use --exec:

--exec reads all remaining options as the command to run, so it must be the last option you specify. Either end your command arguments (and other options) with a -- argument, or specify --exec after your mount point.
The command you specify runs from the same directory that you started arv-mount from. To access data inside the mount, you will generally need to pass the path to the mount as an argument.

For example, this generates a recursive listing of all the projects and collections under your home project:

$ arv-mount --home --exec find -type d ArvadosHome -- ArvadosHome

The first ArvadosHome is a path argument to find. The second is the mount point argument to arv-mount.

Running arv-mount as a systemd service

If you want to run arv-mount as a long-running service, it’s easy to write a systemd service definition for it. We do not publish one because the entire definition tends to be site-specific, but you can start from this template. You must change the ExecStart path. Comments detail other changes you might want to make.

[Unit]
Description=Arvados FUSE mount
Documentation=//doc.arvados.org/main/sdk/fuse/options.html

[Service]
Type=simple

# arv-mount will cache data under a `keep` subdirectory of CacheDirectory.
# If this is a system service installed under /etc/systemd/system,
# the cache will be at /var/cache/arvados/keep.
# The default value of `arvados` lets arv-mount share the cache with other
# tools.
CacheDirectory=arvados

# arv-mount will get Arvados API credentials from the `settings.conf` file
# under ConfigurationDirectory.
# If this is a system service installed under /etc/systemd/system,
# the configuration will be read from /etc/arvados/settings.conf.
# The default value of `arvados` lets arv-mount read configuration from the
# same location as other tools.
ConfigurationDirectory=arvados

# This unit makes the mount available as `Arvados` under the runtime directory root.
# If this is a system service installed under /etc/systemd/system,
# the mount will be at /run/Arvados.
# If this is a user service installed under ~/.config/systemd/user,
# the mount will be at $XDG_RUNTIME_DIR/Arvados.
# If you want to mount at another location on the filesystem, remove RuntimeDirectory
# and replace both instances of %t/Arvados with your desired path.
RuntimeDirectory=Arvados

# The arv-mount path must be the absolute path where you installed the command.
# If you installed from a distribution package, make this /usr/bin/arv-mount.
# If you installed from pip, replace ... with the path to your virtualenv.
# You can add options to select what gets mounted, access permissions,
# cache size, log level, etc.
ExecStart=.../bin/arv-mount --foreground %t/Arvados
ExecStop=/usr/bin/fusermount -u %t/Arvados

Previous: Installing the FUSE Driver Next: Installation