doc/user/intro-keep.md

   1 ---
   2 layout: default
   3 navsection: userguide
   4 title: "Intro: Keep"
   5 navorder: 3
   6 ---
   7
   8 # Intro: Keep
   9
  10 Keep is a content-addressable storage system. Its semantics are
  11 inherently different from the POSIX-like file systems you're used to.
  12
  13 Using Keep looks like this:
  14
  15 1. Write data.
  16 2. Receive locator.
  17 3. Use locator to retrieve data.
  18 4. Tag the locator with a symbolic name.
  19
  20 By contrast, using POSIX looks like this:
  21
  22 1. Choose locator (*i.e.*, filename).
  23 2. Write data to locator.
  24 3. Use locator to retrieve data.
  25
  26 Content addressing provides various benefits, including:
  27
  28 * Reduction of unnecessary data duplication
  29 * Prevention of race conditions (a given locator always references the same data)
  30 * Systematic client- and server-side verification of data integrity
  31 * Provenance reporting (when combined with Arvados MapReduce jobs)
  32
  33 ### Vocabulary
  34
  35 Keep arranges data into **collections** and **data blocks**.
  36
  37 A collection is analogous to a directory tree in a POSIX
  38 filesystem. It contains subdirectories and filenames, and indicates
  39 where to find the data blocks which comprise the files. It is encoded
  40 in plain text.
  41
  42 A data block contains between 1 byte and 64 MiB of data. Its locator
  43 is the MD5 checksum of the data, followed by a plus sign and its size
  44 in bytes (encoded as a decimal number).
  45
  46 `acbd18db4cc2f85cedef654fccc4a4d8+3`
  47
  48 A locator may include additional "hints" to help the Keep store find a
  49 data block more quickly. For example, in the locator
  50 `acbd18db4cc2f85cedef654fccc4a4d8+3+K@{{ site.arvados_api_host }}` the
  51 hint "+K@{{ site.arvados_api_host }}" indicates that the data block is
  52 stored in the Keep instance called *{{ site.arvados_api_host }}*. The
  53 hints are not necessary for Keep to locate a data block -- only the
  54 MD5 hash is -- but they help improve performance.
  55
  56 Keep distributes data blocks among the available disks. It also stores
  57 multiple copies of each block, so a single disk or node failure does
  58 not cause any data to become unreachable.
  59
  60 ### No "delete"
  61
  62 One of the side effects of the Keep write semantics is the lack of a
  63 "delete" operation. Instead, Keep relies on garbage collection to
  64 delete unneeded data blocks.
  65
  66 ### Tagging valuable data
  67
  68 Valuable data must be marked explicitly by creating a Collection in
  69 Arvados. Otherwise, the data blocks will be deleted during garbage
  70 collection.
  71
  72 Use the arv(1) program to create a collection. For example:
  73
  74     arv collection create --uuid "acbd18db4cc2f85cedef654fccc4a4d8+3"
  75
  76 ## Getting started
  77
  78 Write three bytes of data to Keep.
  79
  80     echo -n foo | whput -
  81
  82 Output:
  83
  84     acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
  85
  86 Retrieve the data.
  87
  88     whget acbd18db4cc2f85cedef654fccc4a4d8+3+K@arv01
  89
  90 Output:
  91
  92     foo
  93
  94
  95 {% include alert-stub.html %}
  96
  97 ### Writing a collection
  98
  99 ### Reading a file from a collection
 100
 101 ### Adding a collection to Arvados
 102
 103 ### Tagging a collection
 104
 105 ### Mounting Keep as a read-only POSIX filesystem
 106
 107 ### Mounting a single collection as a POSIX filesystem
 108