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 Keep distributes data blocks among the available disks. It also stores
  49 multiple copies of each block, so a single disk or node failure does
  50 not cause any data to become unreachable.
  51
  52 ### No "delete"
  53
  54 One of the side effects of the Keep write semantics is the lack of a
  55 "delete" operation. Instead, Keep relies on garbage collection to
  56 delete unneeded data blocks.
  57
  58 ### Tagging valuable data
  59
  60 Valuable data must be marked explicitly by creating a Collection in
  61 Arvados. Otherwise, the data blocks will be deleted during garbage
  62 collection.
  63
  64 Use the arv(1) program to create a collection. For example:
  65
  66     arv collections create --uuid "acbd18db4cc2f85cedef654fccc4a4d8+3"
  67
  68 ## Getting started
  69
  70 Write three bytes of data to Keep.
  71
  72     echo -n foo | whput -
  73
  74 Output:
  75
  76     acbd18db4cc2f85cedef654fccc4a4d8+3
  77
  78 Retrieve the data.
  79
  80     whget acbd18db4cc2f85cedef654fccc4a4d8+3
  81
  82 Output:
  83
  84     foo
  85
  86
  87 {% include alert-stub.html %}
  88
  89 ### Writing a collection
  90
  91 ### Reading a file from a collection
  92
  93 ### Adding a collection to Arvados
  94
  95 ### Tagging a collection
  96
  97 ### Mounting Keep as a read-only POSIX filesystem
  98
  99 ### Mounting a single collection as a POSIX filesystem
 100