Merge lp:~aacid/system-image-client/doc into lp:system-image-client

[Albert Astals Cid]

Fix updating to non final mandatory versions

E.g. you are in version 1, version 2 is mandatory and version 3 recommended, you should get an update to version 2

Some documentation, i'm open to any kind of comment on how to improve

[jenkins (martin-mrazik+qa)]

PASSED: Continuous integration, rev:71
http://jenkins.qa.ubuntu.com/job/system-image-client-ci/60/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/system-image-client-ci/./label=precise/60/console

review: Approve (continuous-integration)

[jenkins (martin-mrazik+qa)]

PASSED: Continuous integration, rev:72
http://jenkins.qa.ubuntu.com/job/system-image-client-ci/61/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/system-image-client-ci/./label=precise/61/console

review: Approve (continuous-integration)

[Ted Gould (ted)]

review: Approve

=== added directory 'documentation'
=== added file 'documentation/creating_images'
--- documentation/creating_images	1970-01-01 00:00:00 +0000
+++ documentation/creating_images	2012-07-23 15:35:22 +0000
@@ -0,0 +1,21 @@
+
+This file explains how to create images for consumption of system-image-client
+
+Creating images for system-image-client is fairly easy:
+ * First you have to dump the contents of the filesystem you want to use for your image with dd. Make
+  sure the filesystem is not mounted so that you capture it in a consistent state
+ * Second you have to compress it with xz
+ * Third
+   * If you want to create a a raw image, you are done
+   * If you want to create a signed image, run it through gpg -s
+     with a signing key whose public key will be in the target system
+   * If you want to create an encrypted+signed image, run it through gpg -s -e
+     with a signing key whose public key will be in the target system
+     with a encryption key whose private key will be in the target system (and has no passphrase)
+
+Once you have finished those steps you will have you an image that system-image-client can use.
+
+** Notes **
+ * If the filesystem you are copying has UUID (like ext2/3/4) make sure each of the images has a different UUID
+   otherwise you will end up confusing the system because the target system will end up with two different
+   partitions that have the same UUID
\ No newline at end of file

=== added file 'documentation/creating_index_file'
--- documentation/creating_index_file	1970-01-01 00:00:00 +0000
+++ documentation/creating_index_file	2012-07-23 15:35:22 +0000
@@ -0,0 +1,90 @@
+
+This file explains the syntax of the index file used by the system-image-client.
+
+* The file will be a plain text file encoded in UTF-8
+* Lines are delimited by \n
+*The first line will be the version of the specification. This allows future changes in the spec 
+1.0
+
+* After that there will be an empty line and the list of images available, each image will be of the format
+name: string
+filename: string
+model: string
+version: integer
+type: string
+size: integer
+hash_type: string
+hash: string
+security: string
+changelog_security: string
+
+    The name field is a potentially user visible text that describes the name of the update e.g. "Precise Pangolin update for Canonical Phone X3 and X5"
+    The filename field contains the filename of the image that contains the update. The file will be in the same folder the index file is
+    The model field is non user visible text that defines the internal model that this image should be applied to, e.g. "GT-I9100" instead of "Samsung Galaxy SII".
+        This string will be matched against the internal configuration of the device to decide if this image is appliable or not to the device.
+        There can be multiple model: lines if a given image applies to more than one model e.g. the image applies for phones X3 and X5 
+    The version field is a non user visible number that starts at 1 and increases with each new version for that model. Given two images for the same model, the one with higher version number is the one that shall be installed
+    The type field defines which kind of update is there in this image, valid values for this field are
+        "mandatory" Mandatory update
+        "recommended" Recommended update (not mandatory but the user will get a notification that there is a new update available that he might want to install)
+        "nonrecommended" Non Recommended update (not mandatory, not notified to the user, only discoverable if the user actively goes to see if there are new updates) 
+    The size field contains the size in bytes of the image
+    The hash_type field defines how the contents of the hash field were calculated. Valid values are
+        "none"
+        "md5"
+        "sha1"
+    The hash field contains the result of hashing the file specified by the filename field using the hash_type algorithm. The result is in hexadecimal format with the alphabetic letters in lowercase. The field may be missing if hash_type is 0
+    The security field defines if the image file is raw, signed or encrypted+signedValid values are:
+        "raw"
+        "signed"
+        "encryptedsigned" 
+    The changelog_security field defines if the changelog file is raw, signed or encrypted+signedValid values are:
+        "raw"
+        "signed"
+        "encryptedsigned" 
+
+    The fields must be in that order.
+    Each image will have an empty line separating it to the next one. The last image has no empty line after it. 
+
+
+** Schema of the specification **
+CAPITAL words are substituted by their definition
+FILE represents the contents of the file
+strings between '' represent real textual representation
+The + qualifier means that there can be one or more appearances of the element. The appearances are put in the next line, not in the same one
+
+FILE:
+VERSION
+IMAGESLIST
+
+VERSION:
+''1.0''
+
+IMAGESLIST:
+IMAGE+
+
+IMAGE:
+emptyspace
+''name:'' string
+''filename:'' string
+MODELS
+''version:'' integer
+''type:'' [''mandatory''|''recommended''|''nonrecommended'']
+''size:'' integer
+''hash_type:'' [''none''|''md5''|''sha1'']
+HASH?
+security: [''raw''|''signed''|''encryptedsigned'']
+changelog_security: [''raw''|''signed''|''encryptedsigned'']
+
+MODELS:
+MODEL+
+
+MODEL:
+''model:'' string
+
+HASH:
+''hash:'' string
+
+
+** Appearance in the server **
+The file has to be named "index" and has to be compressed with xz and then signed with gpg
\ No newline at end of file

=== added file 'documentation/running_client'
--- documentation/running_client	1970-01-01 00:00:00 +0000
+++ documentation/running_client	2012-07-23 15:35:22 +0000
@@ -0,0 +1,31 @@
+
+This assumes you have your system correctly set up, if not, read the target_set_up file
+
+The system-image-client binary has different ways of working:
+ * Update to newest mandatoryversion for the current model
+ * Update to a given version for the current model
+ * Update from a given file in disk
+ * List the available images for the current model
+
+** Update to newest mandatory version for the current model **
+This is the default way of working of the system-image-client, what it does
+is download the index file, look in it the highest mandatory image version for the
+current model and update to it if it is bigger than the current one.
+
+
+** Update to a given version for the current model **
+This is activated by the --version command line switch.
+The system-image-client will download the index file, look for the given version
+in it and install it if found.
+
+
+** Update from a given file in disk **
+This is activated by the --image command line switch.
+The system-image-client will skip the index file and will install
+the image given in the path.
+
+
+** List the available images for the current model **
+This is activated by the --list-versions command line switch.
+The system-image-client will download the index file and broadcast both by
+dbus and on the command line the different images available for the current model
\ No newline at end of file

=== added file 'documentation/target_set_up'
--- documentation/target_set_up	1970-01-01 00:00:00 +0000
+++ documentation/target_set_up	2012-07-23 15:35:22 +0000
@@ -0,0 +1,25 @@
+This document explains how to set up a target system for system-image-client usage from scratch.
+
+The first thing you have to do is creating the configuration file.
+This file resides in /etc/system-image-client.conf and is composed of four parameters:
+ * indexRootLocation: where the index of images is located
+ * model: the model the current machine
+ * currentImageVersion: the current version of the image running in this machine
+ * systemPartitions the system partitions that are to be used for writting images separated by :
+
+Example:
+indexRootLocation=http://192.168.0.193/
+model=cp001
+currentImageVersion=1
+systemPartitions=/dev/sda1:/dev/sda3
+
+After creating the configuration file you need to setup the keyring and trustdb for gpg, there you have to store
+all the keys used for signing the index and images. The files are located at /etc/system-image-client-keyring.gpg
+and /etc/system-image-client-trustdb.gpg respectively
+
+Example on how to create the files:
+sudo gpg --primary-keyring /etc/system-image-client-keyring.gpg --no-default-keyring --import /path/to/my/public/key/file
+sudo bash -c 'echo "LONGKEYID:6:" | gpg --primary-keyring /etc/system-image-client-keyring.gpg --no-default-keyring --trustdb-name /etc/system-image-client-trustdb.gpg --import-ownertrust -'
+where LONGKEYID is something like 7623CDE5F6F95EAF2A8CCA9E1C5EE43DEF34A467
+
+With this you are ready to run the system-image-client, read the running_client file for more information
\ No newline at end of file