docs: split Image IDs and Storage backends

Split the section `Image IDs and Storage backends' to decouple
the actual feature, the logic and the configuration. Feature and
logic is moved to a new section under 'Architecture' and the rest
remain under 'Usage'. Also add examples for each case.

docs/architecture.rst

@@ -80,14 +80,49 @@ The architecture is presented below:
 
 .. image:: /images/arch.png
 
+
+.. _storage-backends:
+
+Storage backends
+^^^^^^^^^^^^^^^^
+
+As stated above, for step (1), *snf-image* is capable of fetching images that
+are stored in a variety of different backends and then extracting them onto the
+newly created block device. The following backends are supported:
+
+ * **Local backend**:
+   The local backend is used to retrieve images that are stored on the Ganeti
+   node that the image deployment takes place. All local images are expected to be
+   found under a predifined image directory. By default */var/lib/snf-image* is
+   used, but the user may change this by overwriting the value of the
+   *IMAGE_DIR* variable under ``/etc/default/snf-image``.
+
+ * **Network backend**:
+   The network backend is used to retrieve images that are accessible from the
+   network. snf-image can fetch images via *http:*, *https:*, *ftp:* or *ftps:*,
+   using `cURL <http://curl.haxx.se/>`_.
+
+ * **Pithos backend**:
+   *snf-image* contains a special command-line tool (*pithcat*) for retrieving
+   images residing on a Pithos installation. To set up snf-image's Pithos backend
+   the user needs to setup the ``PITHOS_DATA`` and ``PITHOS_DB`` variables inside
+   ``/etc/default/snf-image`` accordingly.
+
+ * **Null backend**:
+   If the null backend is selected, no image copying is performed. This actually
+   is meant for bypassing step (1) alltogether. This is useful, if the disk
+   provisioned by Ganeti already contains an OS installation before *snf-image* is
+   executed (for example if the disk was created as a clone of an existing VM's
+   hard disk).
+
 .. _image-configuration-tasks:
 
 Image Configuration Tasks
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Configuration tasks are scripts called by snf-image-helper to accomplish
-various configuration steps on the newly created instance. See below for a
-description of each one of them:
+Configuration tasks are scripts called by snf-image-helper inside the helper VM
+to accomplish various configuration steps on the newly created instance. See
+below for a description of each one of them:
 
 **FixPartitionTable**: Enlarges the last partition in the partition table of
 the instance, to consume all the available space and optionally adds a swap

docs/usage.rst

@@ -21,8 +21,8 @@ following OS Parameters:
 
 .. _image-format:
 
-Image Format
-^^^^^^^^^^^^
+Image Format (img_format)
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 snf-image supports 3 different types of image formats:
 
@@ -38,46 +38,46 @@ image formats please see the :ref:`corresponding advanced section
 
 .. _image-id:
 
-Image IDs & Storage back-ends
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-*snf-image* capable of deploying images that are stored in a variety of
-different back-ends. The back-end to be used is determined by the value of the
-*img_id* OS parameter. The following back-ends are supported:
-
- * **Local back-end**:
-   The local back-end is used to retrieve images that are stored in the ganeti
-   node that the image deployment takes place. The local back-end is used if
-   the value of the *img_id* ganeti OS parameter is either prefixed with
-   *file://* or is not prefixed at all. All local images are expected to be
-   found under a predifined image directory. By default */var/lib/snf-image* is
-   used, but the user may change this by overwriting the value of the
-   *IMAGE_DIR* variable under ``/etc/default/snf-image``. The name of the image
-   file is created by adding the image type extension in the end of the
-   *img_id*. For example if the *img_id* is *file://slackware* and the image
-   type is *diskdump*, snf-image will expect to find an image file under the
-   following path: ``/usr/lib/snf-image/slackware.diskdump``
-
- * **Network back-end**:
-   The network back-end is used to retrieve images that are accessible from the
-   network. If the *imd_id* starts with *http:*, *https:*, *ftp:* or *ftps:*,
-   snf-image will treat the *img_id* as a remote URL and will try to fetch the
+Image ID (img_id)
+^^^^^^^^^^^^^^^^^
+
+The **img_id** OS parameter points to the actual Image that we want to deploy.
+It is a URI and its prefix denotes the type of :ref:`backend <storage-backends>`
+to be used. If no prefix is used, it defaults to the local backend:
+
+ * **Local backend**:
+   To select it, the prefix should be ``file://``, followed by the name of the
+   image. All local images are expected to be found under a predefined image
+   directory (``/var/lib/snf-image`` by default). The name of the actual file
+   should be ``<img_id>.<img_format>``.
+   | For example, if we want to deploy the image file:
+   | ``/var/lib/snf-image/slackware.diskdump``
+   | Then:
+   | ``img_format=diskdump`` and ``img_id=file://slackware``
+
+ * **Network backend**:
+   If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``,
+   snf-image will treat the **img_id** as a remote URL and will try to fetch the
    image using `cURL <http://curl.haxx.se/>`_.
-
- * **Pithos back-end**:
-   If an *img_id* is prefixed with *pithos:* or *pithosmap:* the image is
-   considered to be pithos back-ended. *snf-image* contains a special
-   command-line tool (*pithcat*) for retrieving this kind of images. For
-   *pithosmap:* images, the user needs to have set a valid value for the
-   *PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
-   the PITHOS_DB variable needs to contain a valid value too.
-   ``/etc/default/snf-image`` may be used to set both values.
-
- * **Null back-end**:
-   The null back-end is used if the *img_id* value is *null*. In this case no
-   image copying is performed. This is usefull if the hard disk already
-   contains an OS installation before *snf-image* is executed (for example if
-   the hard disk is a snapshot of an existing VM's hard disk).
+   | For example, if we want to deploy an image from an http location:
+   | ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
+
+ * **Pithos backend**:
+   If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
+   image is considered to reside on a Pithos deployment. For ``pithosmap://``
+   images, the user needs to have set a valid value for the
+   ``PITHOS_DATA`` variable in snf-image's configuration file
+   (``/etc/default/snf-image`` by default). For ``pithos://`` images, in
+   addition to ``PITHOS_DATA``, the user needs to have set a valid value for the
+   ``PITHOS_DB`` variable, too.
+   | For example, if we want to deploy using a full Pithos URI:
+   | ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
+   | or if we already know the map:
+   | ``img_id=pithosmap://<slackware-image-map-name>``
+
+ * **Null backend**:
+   To select the Null backend and skip the fetching and extraction step, we set
+   ``img_id=null``.
 
 .. _image-properties: