Merge pull request rauc#95 from ejoerns/v0/topic/documentation-next

Extend documentation

README.md

@@ -6,38 +6,69 @@
 [![Coverity](https://img.shields.io/coverity/scan/5085.svg)](https://scan.coverity.com/projects/5085)
 [![Documentation](https://readthedocs.org/projects/rauc/badge/?version=latest)](http://rauc.readthedocs.org/en/latest/?badge=latest)
 
-> rauc controls the update process on embedded linux systems
+RAUC controls the update process on embedded linux systems. It is both a target
+application that runs as an update client and a host/target tool
+that allows you to create, inspect and modify installation artifacts.
 
 Source Code: https://github.com/jluebbe/rauc
 
 Documentation: https://rauc.readthedocs.org/
 
 ## Features
 
-* Supports whole-system updates using at least two redundant installations
-  * Symmetric: Root-FS A & Root-FS B
-  * Asymmetric: recovery & normal
-  * Also supports custom partition layouts
-* Fail-Safe: no change to the running system
+* **Fail-Safe & Atomic**:
+  * An update may be interrupted at any point without breaking the running
+    system.
+  * Update compatibility check
+* **Cryptographic signing and verification** of updates using OpenSSL (signatures
+  based on x.509 certificates)
+* **Flexible and customizable** redundancy/storage setup
+  * **Symmetric** setup (Root-FS A & B)
+  * **Asymmetric** setup (recovery & normal)
+  * Application partition, Data Partitions, ...
+  * Allows **grouping** of multiple slots (rootfs, appfs) as update targets
 * Two update modes:
   * Bundle: single file containing the whole update
   * Network: separate manifest and component files
-* Bootloader support:
+* **Bootloader support**:
   * [grub](https://www.gnu.org/software/grub/)
   * [barebox](http://barebox.org/)
+  * [u-boot](http://www.denx.de/wiki/U-Boot)
 * Storage support:
-  * raw (ext2/3/4, btrfs, squashfs, ...)
-  * ubi (using [UBI volume update](http://www.linux-mtd.infradead.org/doc/ubi.html#L_volupdate))
+  * ext2/3/4 filesystem
+  * UBI volumes
+  * UBIFS
+  * raw NAND (using nandwrite)
+  * squashfs
+* Independent from updates source
+  * **USB Stick**
+  * Software provisioning server (e.g. **Hawkbit**)
+* Controllable via **D-Bus** interface
+* Supports Data migration
 * Network protocol support using libcurl (https, http, ftp, ssh, ...)
-* Cryptographic verification using OpenSSL (signatures based on x.509
-  certificates)
+* Several layers of update customization
+  * Update-specific extensions (hooks)
+  * System-specific extensions (handlers)
+  * fully custom update script
 
-## Requirements
+### Host Features
+* Create update bundles
+* Sign/resign bundles
+* Inspect bundle files
+
+### Target Features
+* Run as a system service (d-bus interface)
+* Install bundles
+* View system status information
+* Change status of symmetric/asymmetric/custom slots
+
+
+## Target Requirements
 
 * Boot state storage
-  * grub environment file on SD/eMMC/SSD/disk
-  * State partition on EEPROM/FRAM/MRAM or NAND flash
-  * ...
+  * GRUB: environment file on SD/eMMC/SSD/disk
+  * Barebox: State partition on EEPROM/FRAM/MRAM or NAND flash
+  * U-Boot: environment variable
 * Boot target selection support in the bootloader
 * Enough mass storage for two symmetric/asymmetric/custom slots
 * For bundle mode:
@@ -49,30 +80,39 @@ Documentation: https://rauc.readthedocs.org/
 * Hardware watchdog (optional, but recommended)
 * RTC (optional, but recommended)
 
-### Host features
-* Create update bundles
-* Sign/resign bundles
-* Inspect bundle files
-
-### Target Features
-* Run as a system service (d-bus interface)
-* Install bundles
-* View system status information
-* Change status of symmetric/asymmetric/custom slots
-
 ## Usage
 
 Please see the [documentation](https://rauc.readthedocs.org/) for details.
 
 ## Prerequisites
 
+### Host (Build) Prerequisites
+
+* automake
+* libtool
+* libglib2.0-dev
+* libcurl3-dev
+* libssl-dev
+
     sudo apt-get install automake libtool libglib2.0-dev libcurl3-dev libssl-dev 
 
-### Optional Prerequisites
+If you intend to use json-support you also need
 
     sudo apt-get install libjson-glib-dev
 
-## Building from sources
+### Target Prerequisites
+
+Required kernel options:
+
+  * `CONFIG_BLK_DEV_LOOP=y`
+  * `CONFIG_SQUASHFS=y`
+
+For using tar archive in RAUC bundles with Busybox tar, you have to enable the
+following Busybox feature:
+
+  * `CONFIG_FEATURE_TAR_AUTODETECT=y`
+
+## Building from Sources
 
     git clone https://github.com/jluebbe/rauc
     cd rauc
@@ -86,7 +126,7 @@ Please see the [documentation](https://rauc.readthedocs.org/) for details.
     make check
     ./uml-test
 
-## Creating a bundle
+## Creating a Bundle
 
     mkdir content-dir/
     cp $SOURCE/rootfs.ext4.img content-dir/
@@ -101,7 +141,7 @@ Please see the [documentation](https://rauc.readthedocs.org/) for details.
     EOF
     rauc --cert autobuilder.cert.pem --key autobuilder.key.pem bundle content-dir/ update-2015.04-1.raucb
 
-## Installing a bundle
+## Installing a Bundle
 
     rauc install update-2015.04-1.raucb
 

docs/conf.py

@@ -55,9 +55,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '1'
+version = 'v0'
 # The full version, including alpha/beta/rc tags.
-release = '1'
+release = 'v0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -245,7 +245,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
   ('index', 'rauc', u'rauc Documentation',
-   u'Jan Luebbe, Enrico Joerns, Juergen Borleis', 'rauc', 'One line description of project.',
+   u'Jan Luebbe, Enrico Joerns, Juergen Borleis', 'rauc', 'rauc Documentation.',
    'Miscellaneous'),
 ]
 

docs/design.rst

@@ -15,12 +15,12 @@ Network Mode
 * manifest should define complete consistent system
 * manifest is signed with a detached CMS signature
 * manifest contains size and cryptographic hash of each file
-* rauc detects files which have not changed and skips the download
+* RAUC detects files which have not changed and skips the download
 * server can control update process
 
 Custom Handlers
 ---------------
-* a handler can override default rauc behaviour to handle special cases (which
+* a handler can override default RAUC behaviour to handle special cases (which
   were not anticipated during the initial project development)
 
   * sanity checks

docs/examples.rst

@@ -1,7 +1,7 @@
 Examples
 ========
 
-This chapter aims to explain the basic concepts needed for rauc using a simple
+This chapter aims to explain the basic concepts needed for RAUC using a simple
 but realistic scenario.
 
 The system is a x86 system with 1GiB of disk space and 1GiB of RAM. GRUB_ was
@@ -21,7 +21,7 @@ This scenario can be easily reproduced using a QEMU_ virtual machine.
 PKI Setup
 ---------
 
-rauc uses an x.509 PKI (public key infrastructure) to sign and verify updates.
+RAUC uses an x.509 PKI (public key infrastructure) to sign and verify updates.
 To create a simple key pair for testing, we can use ``openssl``::
 
   > openssl req -x509 -newkey rsa:4096 -nodes -keyout demo.key.pem -out demo.cert.pem -subj "/O=rauc Inc./CN=rauc-demo"
@@ -32,10 +32,10 @@ easy-rsa_ is a good first step.
 
 .. _easy-rsa: https://github.com/OpenVPN/easy-rsa
 
-rauc Configuration
+RAUC Configuration
 ------------------
 
-We need a rauc system configuration file to describe the slots which can be
+We need a RAUC system configuration file to describe the slots which can be
 updated
 
 .. code-block:: cfg
@@ -59,7 +59,7 @@ updated
   bootname=B
 
 In this case, we need to place the signing certificate into
-``/etc/rauc/demo.cert.pem``, so that it is used by rauc for verification.
+``/etc/rauc/demo.cert.pem``, so that it is used by RAUC for verification.
 
 GRUB Configuration
 ------------------
@@ -68,7 +68,7 @@ GRUB itself is stored on ``/dev/sda1``, separate from the root file system. To
 access GRUB's environment file, this partition should be mounted to ``/boot``
 (which means that the environment file is found at ``/boot/grub/grubenv``).
 
-GRUB does not provide the boot target selection logic as needed by rauc
+GRUB does not provide the boot target selection logic as needed by RAUC
 out of the box. Instead we use a script to implement it
 
 .. code-block:: sh
@@ -139,7 +139,7 @@ by GRUB. It can also be used to inspect the current contents::
   B_TRY=0
 
 The initial installation of the bootloader and rootfs on the system is out of
-scope for rauc. A common approach is to generate a complete disk image
+scope for RAUC. A common approach is to generate a complete disk image
 (including the partition table) using a build system such as
 OpenEmbedded/Yocto, PTXdist or buildroot.
 
@@ -152,7 +152,7 @@ of the update in a directory (in this case only the root file system image)::
   > mkdir temp-dir/
   > cp …/rootfs.ext4.img temp-dir/
 
-Next, to describe the bundle contents to rauc, we create a *manifest* file.
+Next, to describe the bundle contents to RAUC, we create a *manifest* file.
 This must be named  ``manifest.raucm``::
 
   > cat >> temp-dir/manifest.raucm << EOF
@@ -165,9 +165,9 @@ This must be named  ``manifest.raucm``::
   EOF
 
 Note that we can omit the ``sha256`` and ``size`` parameters for the image
-here, as rauc will fill them out automatically when creating the bundle.
+here, as RAUC will fill them out automatically when creating the bundle.
 
-Finally, we run rauc to create the bundle::
+Finally, we run RAUC to create the bundle::
 
   > rauc --cert demo.cert.pem --key demo.key.pem bundle temp-dir/ update-2015.04-1.raucb
   > rm -r temp-dir
@@ -178,11 +178,11 @@ target system, in this case using a USB memory stick.
 Update Installation
 -------------------
 
-Having copied ``update-2015.04-1.raucb`` onto the target, we only need to run rauc::
+Having copied ``update-2015.04-1.raucb`` onto the target, we only need to run RAUC::
 
   > rauc install /mnt/usb/update-2015.04-1.raucb
 
-After cyptographically verifying the bundle, rauc will now determine the
+After cyptographically verifying the bundle, RAUC will now determine the
 active slots by looking at the ``rauc.slot`` variable. Then, it can select the
 target slot for the update image from the inactive slots.
 

docs/index.rst

@@ -1,9 +1,9 @@
-.. rauc documentation master file, created by
+.. RAUC documentation master file, created by
    sphinx-quickstart on Fri Jan 22 16:00:15 2016.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to the rauc documentation!
+Welcome to the RAUC documentation!
 ==================================
 
 Contents:
@@ -14,6 +14,7 @@ Contents:
    :maxdepth: 1
 
    overview
+   updating
    using
    examples
    scenarios