Commit 79afb6b8 authored by Nikos Skalkotos's avatar Nikos Skalkotos
Browse files

Merge branch 'master' into debian

parents a04278f9 2342b7a3
2014-09-17, v0.16rc2 2014-09-22, v0.16
* Add support for Desktop variants of Windows * Add support for Desktop variants of Windows
* Add support for archipelago images * Add support for archipelago images
* Update the documentation * Update the documentation
......
...@@ -6,7 +6,7 @@ Advanced Topics ...@@ -6,7 +6,7 @@ Advanced Topics
Image Format Image Format
^^^^^^^^^^^^ ^^^^^^^^^^^^
snf-image supports 3 types of image formats: *snf-image* supports 3 types of image formats:
* **extdump**: a raw dump of an ext{2,3,4} file system * **extdump**: a raw dump of an ext{2,3,4} file system
* **ntfsdump**: a raw dump of an NTFS file system * **ntfsdump**: a raw dump of an NTFS file system
...@@ -24,8 +24,8 @@ should have the following properties: ...@@ -24,8 +24,8 @@ should have the following properties:
* The OS they host should not depend on any other partitions * The OS they host should not depend on any other partitions
* Start at sector 2048 * Start at sector 2048
* Have a boot loader installed in the boot sector of the partition (not MBR) * Have a boot loader installed in the boot sector of the partition (not MBR)
* Have the root device in */etc/fstab* specified in a persistent way, using * Have the root device in ``/etc/fstab`` specified in a persistent way, using
UUID or LABEL (for extdump only) UUID or LABEL (for *extdump* only)
Known Issues Known Issues
------------ ------------
...@@ -37,7 +37,7 @@ Known Issues ...@@ -37,7 +37,7 @@ Known Issues
diskdump image format (recommended) diskdump image format (recommended)
+++++++++++++++++++++++++++++++++++ +++++++++++++++++++++++++++++++++++
Diskdump is a newer format that overcomes most of the aforementioned issues. *diskdump* is a newer format that overcomes most of the aforementioned issues.
This format is a dump (raw copy using dd) of a whole disk. This format is a dump (raw copy using dd) of a whole disk.
This design decision has the following benefits: This design decision has the following benefits:
...@@ -48,17 +48,17 @@ This design decision has the following benefits: ...@@ -48,17 +48,17 @@ This design decision has the following benefits:
* Separate system and boot partition in Windows * Separate system and boot partition in Windows
* There are no restrictions on starting sectors of partitions * There are no restrictions on starting sectors of partitions
Although diskdump is a lot more flexible than the older formats, there are Although *diskdump* is a lot more flexible than the older formats, there are
still some rules to follow: still some rules to follow:
* For Linux: * For Linux:
* All block devices in */etc/fstab* should be specified using persistent names (UUID or LABEL) * All block devices in ``/etc/fstab`` should be specified using persistent names (UUID or LABEL)
* LVM partitions are not supported * LVM partitions are not supported
* Only ext{2,3,4} file systems are supported * Only ext{2,3,4} file systems are supported
* For FreeBSD: * For FreeBSD:
* GUID Partition Tables (GPT) should be used * GUID Partition Tables (GPT) should be used
* Only UFS2 file systems are supported * Only UFS2 file systems are supported
* Labels should be omitted in */etc/fstab* entries * Labels should be omitted in ``/etc/fstab`` entries
* For {Open,Net}BSD: * For {Open,Net}BSD:
* Only FFS file systems should be used * Only FFS file systems should be used
...@@ -67,7 +67,7 @@ still some rules to follow: ...@@ -67,7 +67,7 @@ still some rules to follow:
Windows Deployment Windows Deployment
^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^
snf-image performs Windows customization by installing an Answer File for *snf-image* performs Windows customization by installing an Answer File for
Unattended Installation (typically named Unattend.xml) into the VM's hard Unattended Installation (typically named Unattend.xml) into the VM's hard
disk and customizing the file accordingly. The VM will auto-configure itself disk and customizing the file accordingly. The VM will auto-configure itself
the first time it boots. For this to work, the used Windows image must have the first time it boots. For this to work, the used Windows image must have
...@@ -77,7 +77,7 @@ previously been generalized [#f1]_ with a command like this: ...@@ -77,7 +77,7 @@ previously been generalized [#f1]_ with a command like this:
Sysprep /generalize /shutdown /oobe Sysprep /generalize /shutdown /oobe
The pre-included Unattend.xml file that snf-image will by default install on The pre-included Unattend.xml file that *snf-image* will by default install on
the VM's hard disk is this one: the VM's hard disk is this one:
.. literalinclude:: ../snf-image-helper/unattend.xml .. literalinclude:: ../snf-image-helper/unattend.xml
...@@ -106,17 +106,17 @@ releases the developers have confirmed it to work with: ...@@ -106,17 +106,17 @@ releases the developers have confirmed it to work with:
+-------+----------------------+----------------------+ +-------+----------------------+----------------------+
Nevertheless, the user may want to use a custom Unattend.xml file that better Nevertheless, the user may want to use a custom Unattend.xml file that better
fits his needs. To do so, he can either update the **UNATTEND** configuration fits his needs. To do so, he can either update the *UNATTEND* configuration
parameter in ``/etc/default/snf-image`` to point to such a file in the host parameter in ``/etc/default/snf-image`` to point to such a file in the host
system or put his copy of the file in the root directory of the image's system or put his copy of the file in the root directory of the image's
%SystemDrive% (snf-image will not install an Unattend.xml file if it is already %SystemDrive% (*snf-image* will not install an Unattend.xml file if it is
present in the image, unless IGNORE_UNATTEND image property is defined). The already present in the image, unless *IGNORE_UNATTEND* image property is
latter is the recommended way to do it since it allows to provide answer files defined). The latter is the recommended way to do it since it allows to provide
in a per-image basis. answer files in a per-image basis.
.. warning:: .. warning::
When using custom Unattend.xml files, keep in mind that the highlighted When using custom Unattend.xml files, keep in mind that the highlighted
entries (lines 7 & 21-30) are crucial for snf-image to work. You may remove entries (lines 7 & 21-30) are crucial for *snf-image* to work. You may remove
or add settings in the file but the highlighted entries must be present. or add settings in the file but the highlighted entries must be present.
......
...@@ -4,27 +4,27 @@ Architecture ...@@ -4,27 +4,27 @@ Architecture
Overview Overview
^^^^^^^^ ^^^^^^^^
snf-image is a Ganeti OS definition. This means that Ganeti provisions a new *snf-image* is a Ganeti OS definition. This means that Ganeti provisions a new
disk (block device) and passes it to snf-image. Then, snf-image is responsible disk (block device) and passes it to *snf-image*. Then, *snf-image* is
to deploy an Image on that disk. If snf-image returns successfully, Ganeti will responsible to deploy an Image on that disk. If *snf-image* returns
then spawn a VM with that disk as its primary disk. successfully, Ganeti will then spawn a VM with that disk as its primary disk.
Thus, snf-image is responsible for two (2) things, which are executed in two Thus, *snf-image* is responsible for two (2) things, which are executed in two
separate steps: separate steps:
| 1. Fill the newly provisioned disk with Image data | 1. Fill the newly provisioned disk with Image data
| 2. Customize the Image accordingly | 2. Customize the Image accordingly
For (1), snf-image can fetch the Image from a number of backends, as we For (1), *snf-image* can fetch the Image from a number of backends, as we
describe later. For (2) snf-image spawns a helper VM and runs a number of describe later. For (2) *snf-image* spawns a helper VM and runs a number of
configuration tasks inside the isolated environment. Once the last task returns configuration tasks inside the isolated environment. Once the last task returns
successfully, the helper VM ceases and snf-image returns the newly configured successfully, the helper VM ceases and *snf-image* returns the newly configured
disk to Ganeti. disk to Ganeti.
The whole procedure is configurable via OS interface parameters, that can be The whole procedure is configurable via OS interface parameters, that can be
passed to snf-image from the Ganeti command line or RAPI. passed to *snf-image* from the Ganeti command line or RAPI.
snf-image is split in two components: The main program running on the Ganeti *snf-image* is split in two components: The main program running on the Ganeti
host with full root privilege (*snf-image*, previously *snf-image-host*) and a host with full root privilege (*snf-image*, previously *snf-image-host*) and a
part running inside an unprivileged helper VM (*snf-image-helper*). part running inside an unprivileged helper VM (*snf-image-helper*).
...@@ -35,18 +35,19 @@ snf-image ...@@ -35,18 +35,19 @@ snf-image
This part implements the Ganeti OS interface. It extracts the Image onto the This part implements the Ganeti OS interface. It extracts the Image onto the
Ganeti-provided block device, using streaming block I/O (dd with oflag=direct), Ganeti-provided block device, using streaming block I/O (dd with oflag=direct),
then spawns a helper VM, and passes control to snf-image-helper running inside then spawns a helper VM, and passes control to *snf-image-helper* running
that helper VM. The helper VM is created using either KVM or XEN depending on inside that helper VM. The helper VM is created using either KVM or XEN
the supported hypervisor as dictated by Ganeti. It runs as an unprivileged depending on the supported hypervisor as dictated by Ganeti. It runs as an
user. unprivileged user.
There is no restriction on the distribution running inside the helper VM, as There is no restriction on the distribution running inside the helper VM, as
long as it executes the snf-image-helper component automatically upon boot-up. long as it executes the *snf-image-helper* component automatically upon
The snf-image-update-helper script is provided with snf-image to automate the boot-up. The ``snf-image-update-helper`` script is provided with *snf-image*
creation of a helper VM image based on Debian Stable, using multistrap. to automate the creation of a helper VM image based on Debian Stable, using
``multistrap``.
The snf-image-helper component runs inside a specific environment, which is The *snf-image-helper* component runs inside a specific environment, which is
created and ensured by snf-image: created and ensured by *snf-image*:
* The VM features a virtual floppy, containing an ext2 file system with all * The VM features a virtual floppy, containing an ext2 file system with all
parameters needed for image customization. parameters needed for image customization.
...@@ -57,11 +58,11 @@ created and ensured by snf-image: ...@@ -57,11 +58,11 @@ created and ensured by snf-image:
maintains. maintains.
* The helper VM is expected to output "SUCCESS" to its second serial port if * The helper VM is expected to output "SUCCESS" to its second serial port if
image customization was successful inside the VM. image customization was successful inside the VM.
* If "SUCCESS" is not returned, snf-image assumes that, execution of the * If "SUCCESS" is not returned, *snf-image* assumes that, execution of the
helper VM or snf-image-helper has failed. helper VM or *snf-image-helper* has failed.
* The helper VM is expected to shutdown automatically once it is done. Its * The helper VM is expected to shutdown automatically once it is done. Its
execution is time-limited; if it has not terminated after a number of execution is time-limited; if it has not terminated after a number of
seconds, configurable via ``/etc/default/snf-image``, snf-image sends a seconds, configurable via ``/etc/default/snf-image``, *snf-image* sends a
SIGTERM and/or a SIGKILL to it. SIGTERM and/or a SIGKILL to it.
snf-image-helper snf-image-helper
...@@ -105,12 +106,12 @@ newly created block device. The following back-ends are supported: ...@@ -105,12 +106,12 @@ newly created block device. The following back-ends are supported:
* **Pithos backend**: * **Pithos backend**:
*snf-image* contains a special command-line tool (*pithcat*) for retrieving *snf-image* contains a special command-line tool (*pithcat*) for retrieving
images residing on a Pithos installation. To set up snf-image's Pithos images residing on a Pithos installation. To set up *snf-image*'s Pithos
backend the user needs to setup the ``PITHOS_BACKEND_STORAGE`` variable backend the user needs to setup the ``PITHOS_BACKEND_STORAGE`` variable
inside ``/etc/default/snf-image``. inside ``/etc/default/snf-image``.
Possible values are ``nfs`` and ``rados``. If ``nfs`` is used the user needs Possible values are ``nfs`` and ``rados``. If ``nfs`` is used the user needs
to setup ``PITHOS_DATA`` variable, and when ``rados`` is used the user needs to setup *PITHOS_DATA* variable, and when ``rados`` is used the user needs
to setup ``PITHOS_RADOS_POOL_MAPS`` and ``PITHOS_RADOS_POOL_BLOCKS`` to setup *PITHOS_RADOS_POOL_MAPS* and *PITHOS_RADOS_POOL_BLOCKS*
accordingly. accordingly.
* **Null backend**: * **Null backend**:
...@@ -125,8 +126,8 @@ newly created block device. The following back-ends are supported: ...@@ -125,8 +126,8 @@ newly created block device. The following back-ends are supported:
Image Configuration Tasks Image Configuration Tasks
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
Configuration tasks are scripts called by snf-image-helper inside the helper VM Configuration tasks are scripts called by *snf-image-helper* inside the helper
to accomplish various configuration steps on the newly created instance. See VM to accomplish various configuration steps on the newly created instance. See
below for a description of each one of them: below for a description of each one of them:
**FixPartitionTable**: Enlarges the last partition in the partition table of **FixPartitionTable**: Enlarges the last partition in the partition table of
......
Configuration Configuration
============= =============
The user may configure the behavior of snf-image by uncommenting and The user may configure the behavior of *snf-image* by uncommenting and
overwriting the default value for some configuration parameters and the path of overwriting the default value for some configuration parameters and the path of
some external programs in ``/etc/default/snf-image``: some external programs in ``/etc/default/snf-image``:
...@@ -42,7 +42,7 @@ some external programs in ``/etc/default/snf-image``: ...@@ -42,7 +42,7 @@ some external programs in ``/etc/default/snf-image``:
# HELPER_USER="nobody" # HELPER_USER="nobody"
# HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM. # HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM.
# HELPER_MEMORY="500" # HELPER_MEMORY="512"
# MULTISTRAP_CONFIG: Configuration file to be used with multistrap to create # MULTISTRAP_CONFIG: Configuration file to be used with multistrap to create
# the rootfs of the helper image. # the rootfs of the helper image.
...@@ -53,7 +53,7 @@ some external programs in ``/etc/default/snf-image``: ...@@ -53,7 +53,7 @@ some external programs in ``/etc/default/snf-image``:
# MULTISTRAP_APTPREFDIR="/etc/snf-image/apt.pref.d" # MULTISTRAP_APTPREFDIR="/etc/snf-image/apt.pref.d"
# XEN_SCRIPTS_DIR: Directory where the Xen scripts are stored # XEN_SCRIPTS_DIR: Directory where the Xen scripts are stored
# XEN_SCRIPTS_DIR=="/etc/xen/scripts" # XEN_SCRIPTS_DIR="/etc/xen/scripts"
# PITHOS_DB: Pithos database in SQLAlchemy format # PITHOS_DB: Pithos database in SQLAlchemy format
# PITHOS_DB="sqlite://///var/lib/pithos/backend.db" # PITHOS_DB="sqlite://///var/lib/pithos/backend.db"
...@@ -61,15 +61,15 @@ some external programs in ``/etc/default/snf-image``: ...@@ -61,15 +61,15 @@ some external programs in ``/etc/default/snf-image``:
# PITHOS_BACKEND_STORAGE: Select Pithos backend storage. Possible values are # PITHOS_BACKEND_STORAGE: Select Pithos backend storage. Possible values are
# 'nfs' and 'rados'. According to the value you select, you need to set the # 'nfs' and 'rados'. According to the value you select, you need to set the
# corresponding variables that follow. # corresponding variables that follow.
# If you select 'nfs' that's 'PITHOS_DATA'. If you select 'rados' then you # If you select 'nfs' that's 'PITHOS_DATA'. If you select 'rados' then you need
# need to set all the "*_RADOS_*" ones. # to set all the "*_RADOS_*" ones.
# PITHOS_BACKEND_STORAGE="nfs" # PITHOS_BACKEND_STORAGE="nfs"
# PITHOS_DATA: Directory where Pithos data are hosted # PITHOS_DATA: Directory where Pithos data are hosted
# PITHOS_DATA="//var/lib/pithos/data" # PITHOS_DATA="//var/lib/pithos/data"
# PITHOS_RADOS_CEPH_CONF: RADOS configuration file # PITHOS_RADOS_CEPH_CONF: RADOS configuration file
# PITHOS_RADOS_CEPH_CONF="@sysconfdir@/ceph/ceph.conf" # PITHOS_RADOS_CEPH_CONF="/etc/ceph/ceph.conf"
# PITHOS_RADOS_POOL_MAPS: RADOS pool for storing Pithos maps # PITHOS_RADOS_POOL_MAPS: RADOS pool for storing Pithos maps
# PITHOS_RADOS_POOL_MAPS="maps" # PITHOS_RADOS_POOL_MAPS="maps"
...@@ -77,12 +77,15 @@ some external programs in ``/etc/default/snf-image``: ...@@ -77,12 +77,15 @@ some external programs in ``/etc/default/snf-image``:
# PITHOS_RADOS_POOL_BLOCKS: RADOS pool for storing Pithos blocks # PITHOS_RADOS_POOL_BLOCKS: RADOS pool for storing Pithos blocks
# PITHOS_RADOS_POOL_BLOCKS="blocks" # PITHOS_RADOS_POOL_BLOCKS="blocks"
# PROGRESS_MONITOR: External program that monitors the progress of image # PITHOS_ARCHIPELAGO_CONF: Archipelago configuration file
# deployment. Monitoring messages will be redirected to the standard input of # PITHOS_ARCHIPELAGO_CONF="/etc/archipelago/archipelago.conf"
# this program.
# PROGRESS_MONITOR: External program that monitors the progress of the image
# deployment. The snf-image monitor messages will be redirected to the standard
# input of this program.
# PROGRESS_MONITOR="" # PROGRESS_MONITOR=""
# UNATTEND: This variables overwrites the unattend.xml file used when deploying # UNATTEND: This variable 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 leave this empty, unless you really know what you # variable is empty. Please leave this empty, unless you really know what you
# are doing. # are doing.
...@@ -90,6 +93,7 @@ some external programs in ``/etc/default/snf-image``: ...@@ -90,6 +93,7 @@ some external programs in ``/etc/default/snf-image``:
# Paths for needed programs. Uncomment 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. # don't want to use the default one.
# KVM="kvm"
# LOSETUP="losetup" # LOSETUP="losetup"
# KPARTX="kpartx" # KPARTX="kpartx"
# SFDISK="sfdisk" # SFDISK="sfdisk"
...@@ -106,18 +110,18 @@ The most common configuration parameters the user may need to overwrite are: ...@@ -106,18 +110,18 @@ The most common configuration parameters the user may need to overwrite are:
* **IMAGE_DIR**: To specify the directory where the local images are hosted * **IMAGE_DIR**: To specify the directory where the local images are hosted
* **HELPER_SOFT_TIMEOUT**: To increase the allowed deployment time * **HELPER_SOFT_TIMEOUT**: To increase the allowed deployment time
* **PITHOS_DB**: To specify the Pithos database and credentials, in case the * **PITHOS_DB**: To specify the Pithos database and credentials, in case the
user is accessing pithos-hosted images user is accessing Pithos-hosted images
* **PITHOS_DATA**: To specify the directory where the pithos data blocks are * **PITHOS_DATA**: To specify the directory where the Pithos data blocks are
hosted, in case the user is accessing pithos-hosted images hosted, in case the user is accessing Pithos-hosted images
* **PROGRESS_MONITOR**: To specify an executable that will handle the * **PROGRESS_MONITOR**: To specify an executable that will handle the
monitoring messages exported by snf-image monitoring messages exported by *snf-image*
Paths of external programs Paths of external programs
^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^
In ``/etc/default/snf-image`` the user may also overwrite the path of some 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, external programs *snf-image* uses, or add default options to them. For
if the user wants to access network based images via insecure SSL connections, example, if the user wants to access network based images via insecure SSL
he/she will need to overwrite the value of the *CURL* variable like this: connections, he/she will need to overwrite the value of the *CURL* variable
``CURL="curl -k"`` like this: ``CURL="curl -k"``
Installation Installation
============ ============
Before installing snf-image be sure to have a working Ganeti installation in Before installing *snf-image* be sure to have a working Ganeti installation in
your cluster. The installation process should take place in **all** Ganeti your cluster. The installation process should take place in **all** Ganeti
nodes. Here we will describe the installation in a single node. The process is nodes. Here we will describe the installation in a single node. The process is
identical for all nodes and should be repeated manually or automatically, e.g., identical for all nodes and should be repeated manually or automatically, e.g.,
...@@ -76,7 +76,7 @@ To add the GRNET repository in your system, run: ...@@ -76,7 +76,7 @@ To add the GRNET repository in your system, run:
You can verify the authenticity of the package using our public key found You can verify the authenticity of the package using our public key found
`here <https://dev.grnet.gr/files/apt-grnetdev.pub>`_. `here <https://dev.grnet.gr/files/apt-grnetdev.pub>`_.
To install snf-image run: To install *snf-image* run:
.. code-block:: console .. code-block:: console
...@@ -104,7 +104,7 @@ Untar, configure and build the source: ...@@ -104,7 +104,7 @@ Untar, configure and build the source:
$ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var $ ./configure --prefix=/usr --sysconfdir=/etc --localstatedir=/var
$ make $ make
Install snf-image: Install *snf-image*:
.. code-block:: console .. code-block:: console
......
...@@ -24,7 +24,7 @@ following OS Parameters: ...@@ -24,7 +24,7 @@ following OS Parameters:
Image Format (img_format) Image Format (img_format)
^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^
snf-image supports 3 different types of image formats: *snf-image* supports 3 different types of image formats:
* **diskdump** (recommended): a raw dump of a disk * **diskdump** (recommended): a raw dump of a disk
* **extdump**: a raw dump of an ext{2,3,4} file system * **extdump**: a raw dump of an ext{2,3,4} file system
...@@ -57,8 +57,8 @@ to be used. If no prefix is used, it defaults to the local back-end: ...@@ -57,8 +57,8 @@ to be used. If no prefix is used, it defaults to the local back-end:
* **Network backend**: * **Network backend**:
If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``, 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 *snf-image* will treat the **img_id** as a remote URL and will try to fetch
image using `cURL <http://curl.haxx.se/>`_. the image using `cURL <http://curl.haxx.se/>`_.
| For example, if we want to deploy an image from an http location: | For example, if we want to deploy an image from an http location:
| ``img_id=http://www.synnefo.org/path/to/image/slackware-image`` | ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
...@@ -66,13 +66,13 @@ to be used. If no prefix is used, it defaults to the local back-end: ...@@ -66,13 +66,13 @@ to be used. If no prefix is used, it defaults to the local back-end:
* **Pithos backend**: * **Pithos backend**:
If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
image is considered to reside on a Pithos deployment. For ``pithosmap://`` 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`` 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 variable in *snf-image*'s configuration file (``/etc/default/snf-image`` by
default) if the storage backend is ``nfs`` or ``PITHOS_RADOS_POOL_MAPS`` and default) if the storage backend is ``nfs`` or *PITHOS_RADOS_POOL_MAPS* and
``PITHOS_RADOS_POOL_BLOCKS`` if the storage backend is ``rados``. *PITHOS_RADOS_POOL_BLOCKS* if the storage backend is ``rados``.
For ``pithos://`` images, in addition to ``PITHOS_DATA`` or For ``pithos://`` images, in addition to *PITHOS_DATA* or
``PITHOS_RADOS_POOL_*``, the user needs to have set a valid value for the *PITHOS_RADOS_POOL_**, the user needs to have set a valid value for the
``PITHOS_DB`` variable, too. *PITHOS_DB* variable, too.
| For example, if we want to deploy using a full Pithos URI: | For example, if we want to deploy using a full Pithos URI:
| ``img_id=pithos://<user-uuid>/<container>/<slackware-image>`` | ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
...@@ -98,10 +98,10 @@ Image Properties (img_properties) ...@@ -98,10 +98,10 @@ Image Properties (img_properties)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
*snf-image* may use a number of properties to properly configure the image. *snf-image* may use a number of properties to properly configure the image.
Those image properties are passed to snf-image by Ganeti through the Those image properties are passed to *snf-image* by Ganeti through the
*img_poroperties* OS parameter (see Ganeti OS Interface). The name of all image **img_poroperties** OS parameter (see Ganeti OS Interface). The name of all
properties is case-insensitive. For the diskdump format some properties are image properties is case-insensitive. For the *diskdump* format some properties
mandatory. For {ext,ntfs}dump formats all image properties are optional. are mandatory. For *{ext,ntfs}dump* formats all image properties are optional.
We can group image properties in two categories: We can group image properties in two categories:
...@@ -116,11 +116,11 @@ Mandatory properties (for diskdump only) ...@@ -116,11 +116,11 @@ Mandatory properties (for diskdump only)
* **OSFAMILY=linux|windows|freebsd|netbsd|openbsd** * **OSFAMILY=linux|windows|freebsd|netbsd|openbsd**
This specifies whether the image is a Linux, a Windows or a \*BSD Image. This specifies whether the image is a Linux, a Windows or a \*BSD Image.
{ext,ntfs}dump formats are self descriptive regarding this property. *{ext,ntfs}dump* formats are self descriptive regarding this property.
* **ROOT_PARTITION=n** * **ROOT_PARTITION=n**
This specifies the partition number of the root partition. As mentioned This specifies the partition number of the root partition. As mentioned
earlier, for now, only primary partitions are supported. This property is earlier, for now, only primary partitions are supported. This property is
trivial for {ext,ntfs}dump formats (they only host one partition). trivial for *{ext,ntfs}dump* formats (they only host one partition).
Optional properties Optional properties
+++++++++++++++++++ +++++++++++++++++++
...@@ -144,12 +144,12 @@ Optional properties ...@@ -144,12 +144,12 @@ Optional properties
* **IGNORE_UNATTEND=yes** * **IGNORE_UNATTEND=yes**
When deploying a Windows image, the InstallUnattend configuration task will When deploying a Windows image, the InstallUnattend configuration task will
install an Answer File for Unattended Installation (the one shipped with install an Answer File for Unattended Installation (the one shipped with
snf-image or the one pointed out by the UNATTEND configuration parameter) *snf-image* or the one pointed out by the *UNATTEND* configuration
only if such a file is not already present in the root directory of the parameter) only if such a file is not already present in the root directory
image's %SystemDrive%. By defining this property, the installation of the of the image's %SystemDrive%. By defining this property, the installation of
external answer file is always performed, even if such a file already exists the external answer file is always performed, even if such a file already
in the above-mentioned location. For more information on "answer files" exists in the above-mentioned location. For more information on "answer
please refer to :ref:`windows-deployment`. files" please refer to :ref:`windows-deployment`.
* **PASSWORD_HASHING_METHOD=md5|sha1|blowfish|sha256|sha512** * **PASSWORD_HASHING_METHOD=md5|sha1|blowfish|sha256|sha512**
This property can be used on Unix instances to specify the method to be used This property can be used on Unix instances to specify the method to be used
...@@ -166,7 +166,7 @@ Optional properties ...@@ -166,7 +166,7 @@ Optional properties
kernel will assign to this partition. For example, if you have a disk with kernel will assign to this partition. For example, if you have a disk with
an MSDOS partition table on it and one primary partition, the image an MSDOS partition table on it and one primary partition, the image
property *SWAP=2:512* would instruct *snf-image* to create a 512MB long property *SWAP=2:512* would instruct *snf-image* to create a 512MB long
primary partition for swap with id=2. On the other hand, if the SWAP primary partition for swap with id=2. On the other hand, if the *SWAP*
property had this form: *SWAP=5:512*, since primary partitions may have an property had this form: *SWAP=5:512*, since primary partitions may have an
id from 1 to 4, *snf-image* would create a 512MB extended partition with id from 1 to 4, *snf-image* would create a 512MB extended partition with
id=2 and a logical swap partition with id=5 in it with the same size. This id=2 and a logical swap partition with id=5 in it with the same size. This
...@@ -176,7 +176,7 @@ Optional properties ...@@ -176,7 +176,7 @@ Optional properties
If this property is defined with a value other than null, then during the If this property is defined with a value other than null, then during the
deployment, the image will not be configured at all. This is really handy deployment, the image will not be configured at all. This is really handy
because it gives the ability to deploy images hosting operating systems because it gives the ability to deploy images hosting operating systems
whose configuration is not supported by snf-image. whose configuration is not supported by *snf-image*.
* **EXCLUDE_TASK_<task_name>=yes** * **EXCLUDE_TASK_<task_name>=yes**
This family of properties gives the ability to exclude individual This family of properties gives the ability to exclude individual
...@@ -194,7 +194,7 @@ Optional properties ...@@ -194,7 +194,7 @@ Optional properties
img_properties OS parameter img_properties OS parameter
+++++++++++++++++++++++++++ +++++++++++++++++++++++++++
Image properties are passed to snf_image through the img_properties OS Image properties are passed to *snf-image* through the **img_properties** OS
parameter as a simple JSON string like the one below: parameter as a simple JSON string like the one below:
| { | {
...@@ -209,7 +209,7 @@ parameter as a simple JSON string like the one below: ...@@ -209,7 +209,7 @@ parameter as a simple JSON string like the one below:
A real life example for creating a new Ganeti instance and passing image A real life example for creating a new Ganeti instance and passing image
properties to snf-image looks like this: properties to *snf-image* looks like this:
.. code-block:: console .. code-block:: console
......
...@@ -8,7 +8,7 @@ Sample Images ...@@ -8,7 +8,7 @@ Sample Images
While developing *snf-image*, we created and tested a number of images. The While developing *snf-image*, we created and tested a number of images. The
following images are basic installations of some popular Linux distributions, following images are basic installations of some popular Linux distributions,
that have been tested with snf-image and provided here for testing purposes: that have been tested with *snf-image* and provided here for testing purposes:
* Debian Wheezy Base System * Debian Wheezy Base System
...@@ -66,19 +66,19 @@ Sample Usage ...@@ -66,19 +66,19 @@ Sample Usage
Download an Image Download an Image
+++++++++++++++++ +++++++++++++++++
Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR. Download a :ref:`Sample Image <sample-images>` and store it under *IMAGE_DIR*.
Make sure you also have its corresponding metadata file. Make sure you also have its corresponding metadata file.
Spawn a diskdump image Spawn a diskdump image
++++++++++++++++++++++ ++++++++++++++++++++++