doc/architecture/manifest-format.html.textile.liquid

   1 ---
   2 layout: default
   3 navsection: architecture
   4 title: Manifest format
   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 Each collection record has a @manifest_text@ field, which describes how to reassemble keep blocks into files. Each block identifier in the manifest has an added signature which is used to confirm permission to read the block.  To read a block from a keepstore server, the client must provide the block identifier, the signature, and the same API token used to retrieve the collection record.
  13
  14 !(full-width){{site.baseurl}}/images/Keep_manifests.svg!
  15
  16 h2. Manifest v1
  17
  18 A manifest is utf-8 encoded text, consisting of zero or more newline-terminated streams.
  19
  20 <pre>
  21 manifest       ::= stream*
  22 stream         ::= stream-name (" " locator)+ (" " file-segment)+ "\n"
  23 stream-name    ::= "." ("/" path-component)*
  24 path-component ::= <printable ASCII - (whitespace, "/")>+
  25 file-segment   ::= position ":" size ":" filename
  26 position       ::= [0-9]+
  27 size           ::= [0-9]+
  28 filename       ::= path-component ("/" path-component)*
  29 </pre>
  30
  31 Notes:
  32
  33 * The first token is the stream name, consisting of one or more path components, delimited by @"/"@.
  34 ** The first path component is always @"."@.
  35 ** No path component is empty.
  36 ** No path component following the first one can be "." or "..".
  37 ** The stream name never begins or ends with @"/"@.
  38 * The next N tokens are "keep locators":#locator
  39 ** These describe the "data stream".  By logically concatenating the blocks in the order that they appear, we can refer to "positions" in the data stream.
  40 * File tokens come after the sequence of keep locators.
  41 ** A file token has three parts, delimited by @":"@: position, size, filename.
  42 ** Position and size are given in decimal
  43 ** The position is the position in the data stream
  44 ** The size is the count of bytes following the position in the data stream.  A file size may cross multiple blocks in the data stream.
  45 ** Filename may contain @"/"@ characters, but must not start or end with @"/"@, and must not contain @"//"@.
  46 ** Filename components (delimited by @"/"@) must not be @"."@ or @".."@.
  47 ** There may be multiple file tokens.
  48
  49 It is legal to have multiple file tokens in the manifest (possible across different streams) with the same combined path name @stream name + "/" + filename@.  This must be interpreted as a concatenation of file content, in the order that the file tokens appear in the manifest.
  50
  51 Spaces are represented by the escape sequence @\040@.  Spaces in stream names and filenames must be translated when reading and writing manifests.  A manifest may not contain TAB characters, nor other ASCII whitespace characters or control codes other than the spaces or newlines used as delimiters specified above.  A manifest always ends with a newline -- except the empty (zero-length) string, which is a valid manifest.
  52
  53 h3. Normalized manifest v1
  54
  55 A normalized manifest is a manifest that meets the following additional restrictions:
  56
  57 * Streams are in alphanumeric order.
  58 * Each stream name is unique within the manifest.
  59 * Files within a stream are listed in alphanumeric order.
  60 * Blocks within a stream are ordered based on order of file tokens of the stream.  A given block is listed at most once in a stream.
  61 * Filename must not contain @"/"@ (the stream name represents the path prefix)
  62
  63 h3. Estimating manifest size
  64
  65 Here's a formula for estimating manifest size as stored in the database, assuming efficiently packed blocks.
  66
  67 <pre>
  68 manifest_size =
  69    + (total data size / 64 MB) * 40
  70    + sum(number of files * 20)
  71    + sum(size of all directory paths)
  72    + sum(size of all file names)
  73 </pre>
  74
  75 Here is the size when including block signatures.  The block signatures authorize access to fetch each block from a Keep server, as <a href="#token_signatures">described below</a>.  The signed manifest text is what is actually transferred to/from the API server and stored in RAM by @arv-mount@.  The effective upper limit on how large a collection manifest can be is determined by @API.MaxRequestSize@ in @config.yml@ as well as the maximum request size configuration in your reverse proxy or load balancer (e.g. @client_max_body_size@ in Nginx).
  76
  77 <pre>
  78 manifest_size =
  79    + (total data size / 64 MB) * 94
  80    + sum(number of files * 20)
  81    + sum(size of all directory paths)
  82    + sum(size of all file names)
  83 </pre>
  84
  85 h3. Example manifests
  86
  87 A manifest with four files in two directories:
  88
  89 <pre>
  90 . 930625b054ce894ac40596c3f5a0d947+33 0:0:a 0:0:b 0:33:output.txt
  91 ./c d41d8cd98f00b204e9800998ecf8427e+0 0:0:d
  92 </pre>
  93
  94 The same manifest with permission signatures on each block:
  95
  96 <pre>
  97 . 930625b054ce894ac40596c3f5a0d947+33+A1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc 0:0:a 0:0:b 0:33:output.txt
  98 ./c d41d8cd98f00b204e9800998ecf8427e+0+A27117dcd30c013a6e85d6d74c9a50179a1446efa@5835c8bc 0:0:d
  99 </pre>
 100
 101 A manifest containing a file consisting of multiple blocks and a space in the file name:
 102
 103 <pre>
 104 . c449ed86671e4a34a8b8b9430850beba+67108864 09fcfea01c3a141b89dd0dcfa1b7768e+22534144 0:89643008:Docker\040image.tar
 105 </pre>
 106 h2(#locator). Keep locator format
 107
 108 BNF notation for a valid Keep locator string (with hints).  For example: *d41d8cd98f00b204e9800998ecf8427e+0+Z+Ada39a3ee5e6b4b0d3255bfef95601890afd80709@53bed294*
 109
 110 <pre>
 111 locator          ::= sized-digest hint*
 112 sized-digest     ::= digest size-hint
 113 digest           ::= <32 lowercase hexadecimal digits>
 114 size-hint        ::= "+" [0-9]+
 115 hint             ::= "+" hint-type hint-content
 116 hint-type        ::= [A-Z]+
 117 hint-content     ::= [A-Za-z0-9@_-]*
 118 sign-hint        ::= "+A" <40 lowercase hexadecimal digits> "@" sign-timestamp
 119 remote-sign-hint ::= "+R" [A-Za-z0-9]{5} "-" <40 lowercase hexadecimal digits> "@" sign-timestamp
 120 sign-timestamp   ::= <8 lowercase hexadecimal digits>
 121 </pre>
 122
 123 h3. Regular expression to validate locator
 124
 125 <pre>
 126 /^([0-9a-f]{32})\+([0-9]+)(\+[A-Z][-A-Za-z0-9@_]*)*$/
 127 </pre>
 128
 129 h3. Valid locators
 130
 131 table(table table-bordered table-condensed).
 132 |@d41d8cd98f00b204e9800998ecf8427e+0@|
 133 |@d41d8cd98f00b204e9800998ecf8427e+0+Z@|
 134 |<code>d41d8cd98f00b204e9800998ecf8427e+0+Z+Ada39a3ee5e6b4b0d3255bfef95601890afd80709@53bed294</code>|
 135 |<code>930625b054ce894ac40596c3f5a0d947+33+Rzzzzz-1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>|
 136
 137 h3. Invalid locators
 138
 139 table(table table-bordered table-condensed).
 140 ||Why|
 141 |@d41d8cd98f00b204e9800998ecf8427e@|No size hint|
 142 |@d41d8cd98f00b204e9800998ecf8427e+Z+0@|Other hint before size hint|
 143 |@d41d8cd98f00b204e9800998ecf8427e+0+0@|Multiple size hints|
 144 |@d41d8cd98f00b204e9800998ecf8427e+0+z@|Hint does not start with uppercase letter|
 145 |@d41d8cd98f00b204e9800998ecf8427e+0+Zfoo*bar@|Hint contains invalid character @*@|
 146
 147 h3(#token_signatures). Token signatures
 148
 149 A token signature (sign-hint) provides proof-of-access for a data block.  It is computed by taking a SHA1 HMAC of the blob signing token (a shared secret between the API server and keep servers), block digest, current API token, expiration timestamp, and blob signature TTL.
 150
 151 When communicating with the @keepstore@ to fetch a block, or the API server to create or update a collection, the service computes the expected token signature for each block and compares it to the token signature that was presented by the client.  Keep clients receive valid block signatures when uploading a block to a keep store (getting back a signed token as proof of knowledge) or, from the API server, getting the manifest text of a collection on which the user has read permission.
 152
 153 Security of a token signature is derived from the following characteristics:
 154
 155 # Valid signatures can only be generated by entities that know the shared secret (the "blob signing token")
 156 # A signature can only be used by an entity that also know the API token that was used to generate it.
 157 # It expires after a set date (the expiration time, based on the "blob signature time-to-live (TTL)")
 158
 159 h3(#federationsignatures). Federation and signatures
 160
 161 When a collection record is returned through a federation request, the keep blocks listed in the manifest may not be available on the local cluster, and the keep block signatures returned by the remote cluster are not valid for the local cluster.  To solve this, @arvados-controller@ rewrites the signatures in the manifest to "remote cluster" signatures.
 162
 163 A local signature comes after the block identifier and block size, and starts with @+A@:
 164
 165 <code>930625b054ce894ac40596c3f5a0d947+33+A1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>
 166
 167 A remote cluster signature starts with @+R@, then the cluster id of the cluster it originated from (@zzzzz@ in this example), a dash, and then the original signature:
 168
 169 <code>930625b054ce894ac40596c3f5a0d947+33+Rzzzzz-1f27a35dd9af37191d63ad8eb8985624451e7b79@5835c8bc</code>
 170
 171 When the client provides a remote-signed block locator to keepstore, the keepstore proxies the request to the remote cluster.
 172
 173 # keepstore determines the cluster id to contact from the first part of the @+R@ signature
 174 # creates a salted token using the API token and cluster id
 175 # contacts the "accessible" endpoint on the remote cluster to determine the remote cluster's keepstore or keepproxy hosts
 176 # converts the remote signature @+R@ back to a local signature @+A@
 177 # contacts the remote keepstore or keepproxy host and requests the block using the local signature
 178 # returns the block contents back to the client
 179
 180 h3(#example). Example
 181
 182 This example uses @c1bad4b39ca5a924e481008009d94e32+210@, which is the content hash of a @collection@ that was added to Keep in "how to upload data":{{ site.baseurl }}/user/tutorials/tutorial-keep.html.  Get the collection manifest using @arv-get@:
 183
 184 <notextile>
 185 <pre><code>~$ <span class="userinput">arv-get c1bad4b39ca5a924e481008009d94e32+210</span>
 186 . 204e43b8a1185621ca55a94839582e6f+67108864+Aasignatureforthisblockaaaaaaaaaaaaaaaaaa@5f612ee6 b9677abbac956bd3e86b1deb28dfac03+67108864+Aasignatureforthisblockbbbbbbbbbbbbbbbbbb@5f612ee6 fc15aff2a762b13f521baf042140acec+67108864+Aasignatureforthisblockcccccccccccccccccc@5f612ee6 323d2a3ce20370c4ca1d3462a344f8fd+25885655+Aasignatureforthisblockdddddddddddddddddd@5f612ee6 0:227212247:var-GS000016015-ASM.tsv.bz2
 187 </code></pre>
 188 </notextile>
 189
 190 This collection includes a single file @var-GS000016015-ASM.tsv.bz2@ which is 227212247 bytes long. It is stored using four sequential data blocks with hashes @204e43b8a1185621ca55a94839582e6f+67108864@, @b9677abbac956bd3e86b1deb28dfac03+67108864@, @fc15aff2a762b13f521baf042140acec+67108864@, and @323d2a3ce20370c4ca1d3462a344f8fd+25885655@. Each of the block hashes is followed by the rest of their "locator":#locator.
 191
 192 Use @arv-get@ to download the first data block:
 193
 194 notextile. <pre><code>~$ <span class="userinput">arv-get 204e43b8a1185621ca55a94839582e6f+67108864+Aasignatureforthisblockaaaaaaaaaaaaaaaaaa@5f612ee6 &gt; block1</span></code></pre>
 195
 196 Inspect the size and compute the MD5 hash of @block1@:
 197
 198 <notextile>
 199 <pre><code>~$ <span class="userinput">ls -l block1</span>
 200 -rw-r--r-- 1 you group 67108864 Dec  9 20:14 block1
 201 ~$ <span class="userinput">md5sum block1</span>
 202 204e43b8a1185621ca55a94839582e6f  block1
 203 </code></pre>
 204 </notextile>
 205
 206 As expected, the md5sum of the contents of the block matches the @digest@ part of the "locator":#locator, and the size of the contents matches the @size-hint@.