docs: Add a configuration section

Add a section where it is explained how snf-image can be configured
via the /etc/default/snf-image file.

docs/configuration.rst

+Configuration
+=============
+
+The user may configure the behavior of snf-image by uncommenting and
+overwriting the default value for some configuration parameters and the path of
+some external programs in ``/etc/default/snf-image``:
+
+.. code-block:: console
+
+  # snf-image defaults file
+
+  # IMAGE_NAME: Name of the image to use
+  # Generally you use the name of the image with the version of the OS included.
+  # Examples include:
+  #   centos-5.4 debian-4.0 fedora-12
+  # IMAGE_NAME=""
+
+  # IMAGE_DIR: directory location for disk images
+  # IMAGE_DIR="/var/lib/snf-image"
+
+  # IMAGE_DEBUG: turn on debugging output for the scripts
+  # IMAGE_DEBUG=no
+
+  # VERSION_CHECK: Check if snf-image and snf-image-helper have the same version.
+  # This is useful if snf-image is installed as Debian package and not from
+  # source.
+  # VERSION_CHECK="yes"
+
+  # HELPER_DIR: Directory hosting the helper files
+  # HELPER_DIR="/var/lib/snf-image/helper/"
+
+  # HELPER_SIZE: Size of the helper VM image in MB
+  # HELPER_SIZE="600"
+
+  # HELPER_TIMEOUT: Soft and hard timeout limits for helper instance. The helper
+  # instance will be terminated after a given time if it hasn't exited by itself.
+  # A TERM signal will be send if the instance is running after a
+  # HELPER_SOFT_TIMEOUT interval. A KILL signal will be sent, if the instance is
+  # still running after a HELPER_HARD_TIMEOUT interval since the initial signal
+  # was sent. The timeout values are integer numbers with an optional suffix: `s'
+  # for seconds (the default), `m' for minutes, `h' for hours or `d' for days.
+  # HELPER_SOFT_TIMEOUT="120"
+  # HELPER_HARD_TIMEOUT="5"
+
+  # HELPER_USER: For security reasons, it is recommended that the helper VM
+  # runs as an unprivileged user. KVM drops root privileges and runs as
+  # HELPER_USER immediately before starting execution of the helper VM.
+  # HELPER_USER="nobody"
+
+  # HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM.
+  # HELPER_MEMORY="500"
+
+  # MULTISTRAP_CONFIG: Configuration file to be used with multistrap to create
+  # the rootfs of the helper image.
+  # MULTISTRAP_CONFIG="/etc/snf-image/multistrap.conf"
+
+  # MULTISTRAP_APTPREFDIR: Directory where APT preference files are hosted. Those
+  # files will be injected to the helper image before multistrap is called.
+  # MULTISTRAP_APTPREFDIR="/etc/snf-image/apt.pref.d"
+
+  # XEN_SCRIPTS_DIR: Directory where the Xen scripts are stored
+  # XEN_SCRIPTS_DIR=="/etc/xen/scripts"
+
+  # PITHOS_DB: Pithos database in SQLAlchemy format
+  # PITHOS_DB="sqlite://///var/lib/pithos/backend.db"
+
+  # PITHOS_DATA: Directory where Pithos data are hosted
+  # PITHOS_DATA="//var/lib/pithos/data"
+
+  # PROGRESS_MONITOR: External program that monitors the progress of image
+  # deployment. Monitoring messages will be redirected to the standard input of
+  # this program.
+  # PROGRESS_MONITOR=""
+
+  # UNATTEND: This variables overwrites the unattend.xml file used when deploying
+  # a Windows image. snf-image-helper will use its own unattend.xml file if this
+  # variable is empty. Please leave this empty, unless you really know what you
+  # are doing.
+  # UNATTEND=""
+
+  # Paths for needed programs. Uncomment and change the variables below if you
+  # don't want to use the default one.
+  # LOSETUP="losetup"
+  # KPARTX="kpartx"
+  # SFDISK="sfdisk"
+  # INSTALL_MBR="install-mbr"
+  # TIMEOUT="timeout"
+  # CURL="curl"
+  # TAR="tar"
+
+Configuration parameters
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The most common configuration parameters the user may need to overwrite are:
+
+ * **IMAGE_DIR**: To specify the directory where the local images are hosted
+ * **HELPER_SOFT_TIMEOUT**: To increase the allowed deployment time
+ * **PITHOS_DB**: To specify the Pithos database and credentials, in case the
+   user is accessing pithos-hosted images
+ * **PITHOS_DATA**: To specify the directory where the pithos data blocks are
+   hosted, in case the user is accessing pithos-hosted images
+ * **PROGRESS_MONITOR**: To specify an executable that will handle the
+   monitoring messages exported by snf-image
+
+Paths of external programs
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In ``/etc/default/snf-image`` the user may also overwrite the path of some
+external programs snf-image uses, or add default options to them. For example,
+if the user wants to access network based images via insecure SSL connections,
+he/she will need to overwrite the value of the *CURL* variable like this:
+``CURL="curl -k"``
+

docs/index.rst

@@ -42,6 +42,7 @@ Contents:
    architecture
    interface
    installation
+   configuration
    usage
    advanced
 

snf-image-host/defaults.in

@@ -13,7 +13,7 @@
 # IMAGE_DEBUG=no
 
 # VERSION_CHECK: Check if snf-image and snf-image-helper have the same version.
-# This is usefull if snf-image is installed as debian package and not from
+# This is useful if snf-image is installed as Debian package and not from
 # source.
 # VERSION_CHECK="@VERSION_CHECK@"
 
@@ -23,7 +23,7 @@
 # HELPER_SIZE: Size of the helper VM image in MB
 # HELPER_SIZE="600"
 
-# HELPER_TIMOUT: Soft and hard timeout limits for helper instance. The helper
+# HELPER_TIMEOUT: Soft and hard timeout limits for helper instance. The helper
 # instance will be terminated after a given time if it hasn't exited by itself.
 # A TERM signal will be send if the instance is running after a
 # HELPER_SOFT_TIMEOUT interval. A KILL signal will be sent, if the instance is
@@ -35,7 +35,7 @@
 
 # HELPER_USER: For security reasons, it is recommended that the helper VM
 # runs as an unprivileged user. KVM drops root privileges and runs as
-# HELPER_USER imeddiately before starting execution of the helper VM.
+# HELPER_USER immediately before starting execution of the helper VM.
 # HELPER_USER="nobody"
 
 # HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM.
@@ -45,7 +45,7 @@
 # the rootfs of the helper image.
 # MULTISTRAP_CONFIG="@MULTISTRAP_CONFIG@"
 
-# MULTISTRAP_APTPREFDIR: Directory where apt preference files are hosted. Those
+# MULTISTRAP_APTPREFDIR: Directory where APT preference files are hosted. Those
 # files will be injected to the helper image before multistrap is called.
 # MULTISTRAP_APTPREFDIR="@MULTISTRAP_APTPREFDIR@"
 
@@ -55,7 +55,7 @@
 # PITHOS_DB: Pithos database in SQLAlchemy format
 # PITHOS_DB="sqlite:////@localstatedir@/lib/pithos/backend.db"
 
-# PITHOS_DATA: Directory where pithos data are hosted
+# PITHOS_DATA: Directory where Pithos data are hosted
 # PITHOS_DATA="/@localstatedir@/lib/pithos/data"
 
 # PROGRESS_MONITOR: External program that monitors the progress of the image
@@ -64,12 +64,12 @@
 # PROGRESS_MONITOR="@PROGRESS_MONITOR@"
 
 # UNATTEND: This variables overwrites the unattend.xml file used when deploying
-# a windows image. snf-image-helper will use its own unattend.xml file if this
+# a Windows image. snf-image-helper will use its own unattend.xml file if this
 # variable is empty. Please unless you really know what you are doing, leave
 # this empty.
 # UNATTEND="@UNATTEND@"
 
-# Paths for needed programs. Uncommend and change the variables below if you
+# Paths for needed programs. Uncomment and change the variables below if you
 # don't want to use the default one.
 # LOSETUP="losetup"
 # KPARTX="kpartx"