← Back to branch summary

~ubuntu-branches/ubuntu/wily/simplestreams/wily-proposed

« back to all changes in this revision

Viewing changes to doc/README

  • Committer: Package Import Robot
  • Author(s): Scott Moser
  • Date: 2015-09-24 21:53:46 UTC
  • mfrom: (1.1.16)
  • Revision ID: package-import@ubuntu.com-20150924215346-ijw9jcrq49fchix8
Tags: 0.1.0~bzr400-0ubuntu1
https://launchpad.net/bugs/1249018
https://launchpad.net/bugs/1461181
https://launchpad.net/bugs/1353724
https://launchpad.net/bugs/1483159
https://launchpad.net/bugs/1487004
* New upstream snapshot.
  - sstream-mirror, sstream-query, sstream-sync: add --no-verify
    flag (LP: #1249018)
  - pep8/flake8 cleanups
  - several closing of filehandle fixes (LP: #1461181)
  - GlanceMirror fix stack trace if no matching entries (LP: #1353724)
  - tools: upstream development tools fixes (not shipped in ubuntu)
  - GlanceMirror: change known Ubuntu arches into appropriate glance
    arch values (LP: #1483159)
  - Ensure all users of 'sync' get checksumming of content by default.
    insert_item now provides a content source that does checksumming
    during reads and raises exception on error (LP: #1487004)
* debian/README.source: add file, doc how to take upstream snapshot
* debian/rules: export SS_REQUIRE_DISTRO_INFO so that test
  runs without a dependency on distro-info

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/README
1
1
== Simple Sync Format ==
2
 
Simple Sync format consists of 2 different file formats.
 
2
Simple Sync format consists of 2 different file formats:
3
3
 * A "products list" (format=products:1.0)
4
4
 * A "index" (format=index:1.0)
5
5
 
6
 
Files contain json formated data.
 
6
Files contain JSON formatted data.
7
7
Data can come in one of 2 formats:
8
 
 * Json file: <file>.json
 
8
 * JSON file: <file>.json
9
9
   A .json file can be accompanied by a .json.gpg file which contains
10
10
   signature data for .json file.
11
11
 
13
13
   may not be able to be obtained from a storage location at the same
14
14
   time, the preferred delivery of signed data is via '.sjson' format.
15
15
 
16
 
 * Signed Json File: <file>.sjson
17
 
   This is a gpg cleartext signed message.
18
 
      http://rfc-ref.org/RFC-TEXTS/2440/chapter7.html
19
 
   The payload the same content that would be included in the json file.
 
16
 * Signed JSON File: <file>.sjson
 
17
   This is a GPG cleartext signed message:
 
18
      https://tools.ietf.org/html/rfc4880#section-7
 
19
   The payload the same content that would be included in the JSON file.
20
20
 
21
21
Special dictionary entries:
22
22
 * 'path': If a 'product' dictionary in an index file or a item dictionary
24
24
   is content to be downloaded associated with that element.
25
25
 
26
26
   A 'path' must value must be relative to the base of the mirror.
27
 
   It is 
28
27
 
29
28
 * 'md5', 'sha256', 'sha512':
30
29
   If an item contains a 'path' and one of these fields, then the content
38
37
 
39
38
 * 'updated'
40
39
   This field can exist at the top level of a products or index, and
41
 
   contains a rfc-2822 timestamp indicating when the file was last updated
 
40
   contains a RFC 2822 timestamp indicating when the file was last updated
42
41
   This allows a client to quickly note that it is up to date.
43
42
 
44
43
== Simple Sync Mirrors ==
60
59
 
61
60
== Products List ==
62
61
products list: (format=products:1.0)
63
 
For Ubuntu, a product is 'server:precise:amd64'
 
62
For Ubuntu, an example product is 'server:precise:amd64'
64
63
A Products list has a 'content_id' and multiple products.
65
64
a product has multiple versions
66
65
a version has multiple items
67
66
 
68
67
An item can be globally uniquely identified by the path to it.
69
 
Ie, the 'content_id' for a products list and the key in each
 
68
i.e., the 'content_id' for a products list and the key in each
70
69
element of the tree form a unique tuple for that item.  Given:
71
70
  content_id = tree['content_id']
72
71
  prod_name =  tree['products'].keys()[0]
80
79
    An example is:
81
80
       com.ubuntu.cloud:released:aws
82
81
    It should have a reverse domain portion followed by a portion
83
 
    that represents a name underneith that domain.
 
82
    that represents a name underneath that domain.
84
83
 
85
84
  * product_name: product name is unique within a products list.  The same
86
85
    product name may appear in multiple products_lists.  For example,
87
 
    In Ubuntu, 'server:precise:amd64' will appear in both
 
86
    in Ubuntu, 'server:precise:amd64' will appear in both
88
87
    'com.ubuntu.cloud:released:aws' and
89
88
    'com.ubuntu.cloud:released:download'.
90
89
 
91
 
    That name collision should imply that the two separate 
 
90
    That name collision should imply that the two separate
92
91
    <content_id><product_name> pairs are equivalent in some manner.
93
92
 
94
93
  * version_name:
97
96
    by rules of a 'LANG=C sort()'.  That allows the client to trivially
98
97
    order versions to find the most recent.  Ubuntu uses "serial" numbers
99
98
    for these keys, in the format YYYYMMDD[.0-9].
100
 
  
 
99
 
101
100
  * item_name:
102
101
    Inside of a version, there may be multiple items.  An example would be
103
102
    a binary build and a source tarball.
104
103
 
105
104
    For Ubuntu download images, these are things like '.tar.gz',
106
 
    '-disk1.img' and '-root.tar.gz'.  
 
105
    '-disk1.img' and '-root.tar.gz'.
107
106
 
108
107
    The item name does not need to be user-friendly.  It must be
109
 
    consistent.  Because this id is unique amoungst the given
 
108
    consistent.  Because this id is unique within the given
110
109
    'version_name', a client needs only to store that key, rather than
111
110
    trying to determine which keys inside the item dictionary identify it.
112
111
 
113
112
    An 'item' dictionary may contain a 'path' element.
114
113
 
115
 
    'path' entries for a given item must be immutable.  That is, for a 
 
114
    'path' entries for a given item must be immutable.  That is, for a
116
115
    given 'path' under a mirror, the content must never change.
117
116
 
118
117
== Index ==
133
132
 
134
133
Useful definitions
135
134
 * item group
136
 
   an item group is a list of like items. Ie, all produced by the same build.
 
135
   an item group is a list of like items. e.g. all produced by the same build.
137
136
   requirements:
138
137
    * serial: a 'serial' entry that can be sorted by YYYYMMDD[.X]
139
138
    * items: a list of items