Arvados™ Docs
  1. Overview
    1. SDK Reference
  2. Python
    1. Installation
    2. Arvados API Client
    3. Code cookbook
    4. PyDoc Reference
    5. Arvados CWL Runner
    6. Subscribing to database events
  3. Command line tools (CLI SDK)
    1. Installation
    2. Overview
    3. arv reference
    4. arv subcommands
  4. FUSE Driver
    1. Installing the FUSE Driver
    2. arv-mount options
  5. Go
    1. Installation
    2. Examples
  6. Java
    1. Installation
    2. Examples
    3. Javadoc Reference
  7. R
    1. R SDK Overview
    2. R Reference
  8. Ruby
    1. Installation
    2. Examples

arv-mount options

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

  1. Mount contents
  2. Mount custom layout and filtering
    1. --filters usage and limitations
  3. Mount access and permissions
  4. Mount lifecycle management
  5. Mount logging and statistics
  6. Mount local cache setup
  7. Mount interactions with Arvados and Linux
  8. 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 Filesystem cache location (default ~/.cache/arvados/keep)
--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
CacheDirectory=arvados/keep
CacheDirectoryMode=0700

# 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 --disk-cache-dir %C/arvados/keep %t/Arvados
ExecStop=/usr/bin/fusermount -u %t/Arvados

# This unit assumes the running user has a ~/.config/arvados/settings.conf
# with ARVADOS_API_HOST and ARVADOS_API_TOKEN defined.
# If not, you can write those in a separate file
# and set its path as EnvironmentFile.
# Make sure that file is owned and only readable by the running user (mode 0600).
#EnvironmentFile=...
Previous: Installing the FUSE Driver Next: Installation

The content of this documentation is licensed under the Creative Commons Attribution-Share Alike 3.0 United States licence.
Code samples in this documentation are licensed under the Apache License, Version 2.0.