doc/user/tutorials/tutorial-keep-mount-gnu-linux.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Access Keep as a GNU/Linux filesystem"
   5 ...
   6 {% comment %}
   7 Copyright (C) The Arvados Authors. All rights reserved.
   8
   9 SPDX-License-Identifier: CC-BY-SA-3.0
  10 {% endcomment %}
  11
  12 GNU/Linux users can use @arv-mount@ or Gnome to mount Keep as a file system in order to access Arvados collections using traditional filesystem tools.
  13
  14 {% include 'tutorial_expectations' %}
  15
  16 # "*Mounting at the command line with arv-mount*":#arv-mount
  17 # "*Mounting in Gnome File manager*":#gnome
  18
  19 h2(#arv-mount). Arv-mount
  20
  21 @arv-mount@ provides a file system view of Arvados Keep using File System in Userspace (FUSE).  You can browse, open and read Keep entries as if they are regular files, and existing tools can access files in Keep.  Data is streamed on demand.  It is not necessary to download an entire file or collection to start processing.
  22
  23 The default mode permits browsing any collection in Arvados as a subdirectory under the mount directory.  To avoid having to fetch a potentially large list of all collections, collection directories only come into existence when explicitly accessed by UUID or portable data hash. For instance, a collection may be found by its content hash in the @keep/by_id@ directory.
  24
  25 <notextile>
  26 <pre><code>~$ <span class="userinput">mkdir -p keep</span>
  27 ~$ <span class="userinput">arv-mount keep</span>
  28 ~$ <span class="userinput">cd keep/by_id/c1bad4b39ca5a924e481008009d94e32+210</span>
  29 ~/keep/by_id/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">ls</span>
  30 var-GS000016015-ASM.tsv.bz2
  31 ~/keep/by_id/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">md5sum var-GS000016015-ASM.tsv.bz2</span>
  32 44b8ae3fde7a8a88d2f7ebd237625b4f  var-GS000016015-ASM.tsv.bz2
  33 ~/keep/by_id/c1bad4b39ca5a924e481008009d94e32+210$ <span class="userinput">cd ../..</span>
  34 ~$ <span class="userinput">fusermount -u keep</span>
  35 </code></pre>
  36 </notextile>
  37
  38 The last line unmounts Keep.  Subdirectories will no longer be accessible.
  39
  40 In the top level directory of each collection, arv-mount provides a special file called @.arvados#collection@ that contains a JSON-formatted API record for the collection. This can be used to determine the collection's @portable_data_hash@, @uuid@, etc. This file does not show up in @ls@ or @ls -a@.
  41
  42 h3. Modifying files and directories in Keep
  43
  44 By default, all files in the Keep mount are read only.  However, @arv-mount --read-write@ enables you to perform the following operations using normal Unix command line tools (@touch@, @mv@, @rm@, @mkdir@, @rmdir@) and your own programs using standard POSIX file system APIs:
  45
  46 * Create, update, rename and delete individual files within collections
  47 * Create and delete subdirectories inside collections
  48 * Move files and directories within and between collections
  49 * Create and delete collections within a project (using @mkdir@ and @rmdir@ in a project directory)
  50
  51 Not supported:
  52
  53 * Symlinks, hard links
  54 * Changing permissions
  55 * Extended attributes
  56 * Moving a subdirectory of a collection into a project, or moving a collection from a project into another collection
  57
  58 If multiple clients (separate instances of arv-mount or other arvados applications) modify the same file in the same collection within a short time interval, this may result in a conflict.  In this case, the most recent commit wins, and the "loser" will be renamed to a conflict file in the form @name~YYYYMMDD-HHMMSS~conflict~@.
  59
  60 Please note this feature is in beta testing.  In particular, the conflict mechanism is itself currently subject to race conditions with potential for data loss when a collection is being modified simultaneously by multiple clients.  This issue will be resolved in future development.
  61
  62 h2(#gnome). Mounting in Gnome File manager
  63
  64 As an alternative to @arv-mount@ you can also access the WebDAV mount through the Gnome File manager.
  65
  66 # Open "Files"
  67 # On the left sidebar, click on "Other Locations"
  68 # At the bottom of the window, enter @davs://collections.ClusterID.example.com/@  When prompted for credentials, enter username "arvados" and a valid Arvados token in the @Password@ field.