5 title: arv-mount options
8 Copyright (C) The Arvados Authors. All rights reserved.
10 SPDX-License-Identifier: CC-BY-SA-3.0
13 This page documents all available @arv-mount@ options with some usage examples.
15 h2(#contents). Mount contents
17 table(table table-bordered table-condensed).
18 |_. Option(s)|_. Description|
19 |@--all@|Mount a subdirectory for each mode: @home@, @shared@, @by_id@, and @by_tag@ (default if no @--mount-*@ options are given)|
20 |@--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":#layout section)|
21 |@--collection UUID_OR_PDH@|Mount the specified collection|
22 |@--home@|Mount your home project|
23 |@--project UUID@|Mount the specified project|
24 |@--shared@|Mount a subdirectory for each project shared with you|
25 |@--by-id@|Mount a magic directory where collections and projects are accessible through subdirectories named after their UUID or portable data hash|
26 |@--by-pdh@|Mount a magic directory where collections are accessible through subdirectories named after their portable data hash|
27 |@--by-tag@|Mount a subdirectory for each tag attached to a collection or project|
29 h2(#layout). Mount custom layout and filtering
31 table(table table-bordered table-condensed).
32 |_. Option(s)|_. Description|
33 |@--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":{{ site.baseurl }}/api/methods.html#filters. See the "example filters":#filters.|
34 |@--mount-home PATH@|Make your home project available under the mount at @PATH@|
35 |@--mount-shared PATH@|Make projects shared with you available under the mount at @PATH@|
36 |@--mount-tmp PATH@|Make a new temporary writable collection available under the mount at @PATH@. This collection is deleted when the mount is unmounted.|
37 |@--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|
38 |@--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|
39 |@--mount-by-tag PATH@|Make a subdirectory for each tag attached to a collection or project available under the mount at @PATH@|
41 h3(#filters). @--filters@ usage and limitations
43 Your argument to @--filters@ should be a JSON list of filters in "Arvados API list filter syntax":{{ site.baseurl }}/api/methods.html#filters. 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:
46 <pre><code>$ arv-mount --home <span class="userinput">--filters '[["groups.group_class", "!=", "filter"], ["collections.properties.type", "not in", ["intermediate", "log"]]]'</span> ...
50 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:
53 <pre><code>$ <span class="userinput">cat >~/arv-mount-filters.json <<EOF
61 "collections.properties.type",
70 $ arv-mount --home <span class="userinput">--filters ~/arv-mount-filters.json</span> ...
74 The current implementation of @--filters@ has a few limitations. These may be lifted in a future release:
76 * 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.
77 * Tag directory listings are generated by querying tags alone. Only filters that apply to @links@ will affect these listings.
79 h2(#access). Mount access and permissions
81 table(table table-bordered table-condensed).
82 |_. Option(s)|_. Description|
83 |@--allow-other@|Let other users on this system read mounted data (default false)|
84 |@--read-only@|Mounted data cannot be modified from the mount (default)|
85 |@--read-write@|Mounted data can be modified from the mount|
87 h2(#lifecycle). Mount lifecycle management
89 table(table table-bordered table-condensed).
90 |_. Option(s)|_. Description|
91 |@--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.|
92 |@--foreground@|Run mount process in the foreground instead of daemonizing (default false)|
93 |@--subtype SUBTYPE@|Set mounted filesystem type to @fuse.SUBTYPE@ (default is just @fuse@)|
94 |@--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.|
95 |@--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.|
96 |@--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.|
97 |@--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.|
99 h2(#logging). Mount logging and statistics
101 table(table table-bordered table-condensed).
102 |_. Option(s)|_. Description|
103 |@--crunchstat-interval SECONDS@|Write stats to stderr every N seconds (default disabled)|
104 |@--debug@|Log debug information|
105 |@--logfile LOGFILE@|Write debug logs and errors to the specified file (default stderr)|
107 h2(#cache). Mount local cache setup
109 table(table table-bordered table-condensed).
110 |_. Option(s)|_. Description|
111 |@--disk-cache@|Cache data on the local filesystem (default)|
112 |@--ram-cache@|Cache data in memory|
113 |@--disk-cache-dir DIRECTORY@|Filesystem cache location (default @~/.cache/arvados/keep@)|
114 |@--directory-cache BYTES@|Size of directory data cache in bytes (default 128 MiB)|
115 |@--file-cache BYTES@|Size of file data cache in bytes (default 8 GiB for filesystem cache, 256 MiB for memory cache)|
117 h2(#plumbing). Mount interactions with Arvados and Linux
119 table(table table-bordered table-condensed).
120 |_. Option(s)|_. Description|
121 |@--disable-event-listening@|Don't subscribe to events on the API server to update mount contents|
122 |@--encoding ENCODING@|Filesystem character encoding (default 'utf-8'; specify a name from the "Python codec registry":https://docs.python.org/3/library/codecs.html#standard-encodings)|
123 |@--retries RETRIES@|Maximum number of times to retry server requests that encounter temporary failures (e.g., server down). Default 10.|
124 |@--storage-classes CLASSES@|Comma-separated list of storage classes to request for new collections|
126 h2(#examples). Examples
128 h3(#exec). Using @--exec@
130 There are a couple of details that are important to understand when you use @--exec@:
132 * @--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.
133 * 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.
135 For example, this generates a recursive listing of all the projects and collections under your home project:
138 <pre><code>$ <span class="userinput">arv-mount --home --exec find -type d ArvadosHome -- ArvadosHome</span>
142 The first @ArvadosHome@ is a path argument to @find@. The second is the mount point argument to @arv-mount@.
144 h3(#systemd). Running arv-mount as a systemd service
146 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.
150 Description=Arvados FUSE mount
151 Documentation={{ site.baseurl }}/sdk/fuse/options.html
155 CacheDirectory=arvados/keep
156 CacheDirectoryMode=0700
158 # This unit makes the mount available as `Arvados` under the runtime directory root.
159 # If this is a system service installed under /etc/systemd/system,
160 # the mount will be at /run/Arvados.
161 # If this is a user service installed under ~/.config/systemd/user,
162 # the mount will be at $XDG_RUNTIME_DIR/Arvados.
163 # If you want to mount at another location on the filesystem, remove RuntimeDirectory
164 # and replace both instances of %t/Arvados with your desired path.
165 RuntimeDirectory=Arvados
166 # The arv-mount path must be the absolute path where you installed the command.
167 # If you installed from a distribution package, make this /usr/bin/arv-mount.
168 # If you installed from pip, replace ... with the path to your virtualenv.
169 # You can add options to select what gets mounted, access permissions,
170 # cache size, log level, etc.
171 ExecStart=<span class="userinput">...</span>/bin/arv-mount --foreground --disk-cache-dir %C/arvados/keep %t/Arvados
172 ExecStop=/usr/bin/fusermount -u %t/Arvados
174 # This unit assumes the running user has a ~/.config/arvados/settings.conf
175 # with ARVADOS_API_HOST and ARVADOS_API_TOKEN defined.
176 # If not, you can write those in a separate file
177 # and set its path as EnvironmentFile.
178 # Make sure that file is owned and only readable by the running user (mode 0600).