Synnefo » snf-image

h1. Image Format

The image format (@img_format@) is a required OS Provider parameter and snf-image will complain if not found

Right now we support 3 different types of image formats:

* @extdump@

* @ntfsdump@

* @diskdump@

h2. extdump & ntfsdump image formats

Those two formats are dumps (raw copies using dd) of partitions hosting Linux systems on ext{2,3,4} and Windows systems on ntfs filesystems respectively.

Partitions hosting a Windows or Linux system that are suitable for dumping should have the following properties:

* Be the first partition in the filesystem

* The OS they host should not depend on any other partitions

* Start at sector 2048

* Have a bootloader installed in the boot sector of the partition (not MBR)

* Have the root device in /etc/fstab specified in a persistent way, using UUID or LABEL (for extdump only)

h3. Known Issues

* For linux systems, having grub installed in the partition is fragile and things can go wrong when resizing the partitions, especially when shrinking.

* Swap space is not supported.

* More complicated partition schemes are not supported.

h2. diskdump image format

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 design decision has the following benefits:

* Swap partitions are supported

* The system may use multiple partitions:

** dedicated partitions for /boot, /home etc in linux

** system and boot partition in Windows

* There are no restrictions on starting sectors of partitions

Although diskdump is a lot more flexible than the older formats, there are still some rules to follow:

* All devices in fstab should be specified by persistent names (UUID or LABEL)

* LVMs and extended partitions should be avoided.

** The support for extended partitions is partial. snf-image does not support resizing logical partitions.

** Logical volumes are not supported at all

* In Linux disks only ext{2,3,4} filesystems are supported

h2. Image Properties

In order for snf-image to be able to properly configure an image, it may make use of a set of image properties. Those image properties are passed to snf-image by Ganeti through the @img_poroperties@ OS parameter (see [[:#Ganeti-OS-Interface|Ganeti OS Interface]]). The name of all image properties is *case-insensitive*. For the @diskdump@ format some properties are *mandatory*. For {ext,ntfs}dump formats all image properties are optional.

A list of mandatory and optional properties follows:

* Mandatory properties (@diskdump@ only)

** *OSFAMILY={linux,windows}*

This specifies whether the image is a Linux or a Windows Image. {ext,ntfs}dump formats are self descriptive regarding this property.

** *ROOT_PARTITION={1,2,3,4}*

This specifies the partition number of the root partition. As mentioned earlier, for now, only primary partitions are supported. This property is trivial for {ext,ntfs}dump formats (they only host one partition).

* Optional properties

** *USERS="username1 username2...."*

This is a space-seperated list of users, whose password will be reset by snf-image. The use of this property is optional, but highly recommended. For now, if this property is missing, the users are chosen according to a set of rules, but those rules may change or even be dropped in the future. The rules we currently use are listed below:

*** For Windows images, the @Administrator@'s password is reset.

*** For Linux images, the root password is reset for all distribution.

** *EXCLUDE_ALL_TASKS*

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 because it gives the ability to deploy images hosting operating systems whose configuration is not supported by @snf-image@.

** *EXCLUDE_TASK_<task_name>*

This family of properties gives the ability to exclude individual configuration tasks from running. Hence, if the property @EXCLUDE_TASK_DeleteSSHKeys@ with a value other than _null_ is passed to @snf-image@, the aforementioned configuration step will not be executed, and the SSH Keys found in the image will not be removed during the deployment. Task exclusion provides great flexibility, but it needs to be used with great care. Tasks depend on each other and although those dependencies are well documented, automatic task dependency resolution isn't yet supported in @snf-image@. If you exclude task A but not task B which depends on A, you will probably end up with an unsuccessful deployment because B will fail and exit in an abnormal way. You can read more about configuration tasks [[Configuration Tasks|here]].

h3. OS parameter (img_properties)

Image properties are passed to snf_image through the @img_properties@ OS parameter as a simple json string like the one below:

<pre>

{

     "PROPERTY1": "VALUE1",

     "PROPERTY2": "VALUE2",

     "PROPERTY3": "VALUE3",

     ...

     ...

     ...

     "PROPERTYn": "VALUEn"

 }

</pre>

A real life example for creating a new ganeti instance and passing image properties to @snf-image@ would probably look more like this:

<pre>

gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump...

</pre>