7 *snf-image* requires ganeti-os-interface v20 to operate and it introduces the
8 following OS Parameters:
10 * **img_format** (required if *config_url* is missing): the image format type
11 (:ref:`details <image-format>`)
12 * **img_id** (required if *config_url* is missing): the URI used to identify
13 the image (:ref:`details <image-id>`)
14 * **img_passwd** (required if *config_url* is missing): the password to be
16 * **img_properties** (optional): additional image properties used to customize
17 the image (:ref:`details <image-properties>`)
18 * **img_personality** (optional): files to be injected into the image
19 filesystem (:ref:`details <image-personality>`)
20 * **config_url** (optional): the url to download configuration data from
27 Right now 3 different types of image formats are supported:
29 * **extdump**: a raw dump of an ext{2,3,4} file system
30 * **ntfsdump**: a raw dump of an NTFS file system
31 * **diskdump**: a raw dump of a disk
33 extdump and ntfsdump image formats
34 ++++++++++++++++++++++++++++++++++
36 Those two formats are dumps (raw copies using dd) of partitions hosting Linux
37 systems on ext{2,3,4} and Windows systems on ntfs file systems respectively.
38 Partitions hosting a Windows or Linux system that are suitable for dumping
39 should have the following properties:
41 * Be the first partition in the file system
42 * The OS they host should not depend on any other partitions
43 * Start at sector 2048
44 * Have a boot loader installed in the boot sector of the partition (not MBR)
45 * Have the root device in */etc/fstab* specified in a persistent way, using
46 UUID or LABEL (for extdump only)
51 * For Linux systems, having grub installed in the partition is fragile and
52 things can go wrong when resizing the partitions, especially when shrinking.
53 * More complicated partition schemes are not supported.
58 Diskdump is a newer format that overcomes most of the aforementioned issues.
59 This format is a dump (raw copy using dd) of a whole disk.
61 This design decision has the following benefits:
63 * Swap partitions are supported
64 * The system may use multiple partitions:
65 * dedicated partitions for /boot, /home etc in Linux
66 * system and boot partition in Windows
67 * There are no restrictions on starting sectors of partitions
69 Although diskdump is a lot more flexible than the older formats, there are
70 still some rules to follow:
72 * All devices in fstab should be specified by persistent names (UUID or LABEL)
73 * LVMs are not supported
74 * For Linux disks only ext{2,3,4} file systems are supported
75 * For FreeBSD disks only UFS file systems are supported
76 * For FreeBSD only GUID Partition Tables (GPT) are supported
80 Image IDs & Storage back-ends
81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
83 *snf-image* capable of deploying images that are stored in a variety of
84 different back-ends. The back-end to be used is determined by the value of the
85 *img_id* OS parameter. The following back-ends are supported:
88 The local back-end is used to retrieve images that are stored in the ganeti
89 node that the image deployment takes place. The local back-end is used if
90 the value of the *img_id* ganeti OS parameter is either prefixed with
91 *file://* or is not prefixed at all. All local images are expected to be
92 found under a predifined image directory. By default */var/lib/snf-image* is
93 used, but the user may change this by overwriting the value of the
94 *IMAGE_DIR* variable under ``/etc/default/snf-image``. The name of the image
95 file is created by adding the image type extension in the end of the
96 *img_id*. For example if the *img_id* is *file://slackware* and the image
97 type is *diskdump*, snf-image will expect to find an image file under the
98 following path: ``/usr/lib/snf-image/slackware.diskdump``
100 * **Network back-end**:
101 The network back-end is used to retrieve images that are accessible from the
102 network. If the *imd_id* starts with *http:*, *https:*, *ftp:* or *ftps:*,
103 snf-image will treat the *img_id* as a remote URL and will try to fetch the
104 image using `cURL <http://curl.haxx.se/>`_.
106 * **Pithos back-end**:
107 If an *img_id* is prefixed with *pithos:* or *pithosmap:* the image is
108 considered to be pithos back-ended. *snf-image* contains a special
109 command-line tool (*pithcat*) for retrieving this kind of images. For
110 *pithosmap:* images, the user needs to have set a valid value for the
111 *PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
112 the PITHOS_DB variable needs to contain a valid value too.
113 ``/etc/default/snf-image`` may be used to set both values.
116 The null back-end is used if the *img_id* value is *null*. In this case no
117 image copying is performed. This is usefull if the hard disk already
118 contains an OS installation before *snf-image* is executed (for example if
119 the hard disk is a snapshot of an existing VM's hard disk).
121 .. _image-properties:
126 In order for *snf-image* to be able to properly configure an image, it may make
127 use of a set of image properties. Those image properties are passed to
128 *snf-image* by Ganeti through the *img_poroperties* OS parameter (see Ganeti OS
129 Interface). The name of all image properties is case-insensitive. For the
130 diskdump format some properties are mandatory. For {ext,ntfs}dump formats all
131 image properties are optional.
133 A list of mandatory and optional properties follows:
135 Mandatory properties (diskdump only)
136 ++++++++++++++++++++++++++++++++++++
138 * **OSFAMILY={linux,windows}**
139 This specifies whether the image is a Linux or a Windows Image.
140 {ext,ntfs}dump formats are self descriptive regarding this property.
141 * **ROOT_PARTITION=n**
142 This specifies the partition number of the root partition. As mentioned
143 earlier, for now, only primary partitions are supported. This property is
144 trivial for {ext,ntfs}dump formats (they only host one partition).
149 * **USERS="username1 username2...."**
150 This is a space-seperated list of users, whose password will be reset by
151 *snf-image*. The use of this property is optional, but highly recommended.
152 For now, if this property is missing, the users are chosen according to a
153 set of rules, but those rules may change or even be dropped in the future.
154 The rules we currently use are listed below:
156 * For Windows images, the *Administrator*'s password is reset.
157 * For Linux and FreeBSD images, the *root* password is reset.
159 * **EXCLUDE_ALL_TASKS=yes**
160 If this property is defined with a value other than null, then during the
161 deployment, the image will not be configured at all. This is really handy
162 because it gives the ability to deploy images hosting operating systems
163 whose configuration is not supported by snf-image.
165 * **EXCLUDE_TASK_<task_name>=yes**
166 This family of properties gives the ability to exclude individual
167 configuration tasks from running. Hence, if the property
168 *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
169 *snf-image*, the aforementioned configuration step will not be executed, and
170 the SSH Keys found in the image will not be removed during the deployment.
171 Task exclusion provides great flexibility, but it needs to be used with
172 great care. Tasks depend on each other and although those dependencies are
173 well documented, automatic task dependency resolution isn't yet supported in
174 *snf-image*. If you exclude task A but not task B which depends on A, you
175 will probably end up with an unsuccessful deployment because B will fail and
176 exit in an abnormal way. You can read more about configuration tasks here.
179 img_properties OS parameter
180 +++++++++++++++++++++++++++++++
182 Image properties are passed to snf_image through the img_properties OS
183 parameter as a simple json string like the one below:
186 | "PROPERTY1": "VALUE1",
187 | "PROPERTY2": "VALUE2",
188 | "PROPERTY3": "VALUE3",
192 | "PROPERTYn": "VALUEn"
196 A real life example for creating a new ganeti instance and passing image
197 properties to snf-image would probably look more like this:
199 ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump...``
201 .. _image-personality:
203 Personality OS Parameter
204 ^^^^^^^^^^^^^^^^^^^^^^^^
206 This parameter is an extension of the Server Personality notation proposed by
207 the OpenStack Compute API v1.1 and defines a list of files to be injected into
208 the image file system.
213 The format of this parameter is a JSON array of objects. Each object in the
214 array supports the following keys:
216 * **path**: The absolute path of the file (string)
217 * **contents**: The content of the file encoded as a base64 string (string)
218 * **owner**: The user ownership of the file (string)
219 * **group**: The group ownership of the file (string)
220 * **mode**: The permission mode of the file (number)
222 The first two (path, contents) are mandatory. The others (owner, group, mode)
223 are optional and their default value is root, root and 0440 respectively.
228 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
229 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
230 their permissions are ``-rw-r--r--`` [#]_
234 | "path": "/tmp/test1",
235 | "contents": "dGVzdDENCg==",
241 | "path": "/tmp/test2",
242 | "contents": "dGVzdDINCg==",
249 .. [#] The first mode is in octal representation and the second in decimal.
257 While developing *snf-image*, we created and tested a number of images. The
258 following images are basic installations of some popular Linux distributions,
259 that have been tested with snf-image and provided here for testing purposes:
262 * Debian Squeeze Base System
263 [`diskdump <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump>`_]
264 [`md5sum <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.md5sum>`_]
265 [`metadata <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.meta>`_]
266 * Debian Wheezy Base System
267 [`diskdump <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump>`_]
268 [`md5sum <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.md5sum>`_]
269 [`metadata <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.meta>`_]
271 [`diskdump <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump>`_]
272 [`md5sum <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.md5sum>`_]
273 [`metadata <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.meta>`_]
275 [`diskdump <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump>`_]
276 [`md5sum <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.md5sum>`_]
277 [`metadata <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.meta>`_]
279 [`diskdump <http://cdn.synnefo.org/fedora-18-x86_64.diskdump>`_]
280 [`md5sum <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.md5sum>`_]
281 [`metadata <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.meta>`_]
282 * Ubuntu Desktop LTS 12.04
283 [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump>`_]
284 [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
285 [`metadata <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
287 [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump>`_]
288 [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
289 [`metadata <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
290 * Ubuntu Desktop 13.04
291 [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump>`_]
292 [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
293 [`metadata <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
295 [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump>`_]
296 [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
297 [`metadata <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
298 * Ubuntu Server 12.04
299 [`diskdump <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump>`_]
300 [`md5sum <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.md5sum>`_]
301 [`metadata <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.meta>`_]
302 * OpenSUSE Desktop 12.3
303 [`diskdump <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump>`_]
304 [`md5sum <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.md5sum>`_]
305 [`metadata <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.meta>`_]
307 [`diskdump <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
308 [`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
309 [`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
317 Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR.
318 Make sure you also have its corresponding metadata file.
320 Spawn a diskdump image
321 ++++++++++++++++++++++
323 If you want to deploy an image of type diskdump, you need to provide the
324 corresponding *img_properties* as described in the
325 :ref:`Image Format<image-format>` section. If using a diskdump found in the
326 :ref:`sample-images` list, use the *img_properties* described in the image's
327 metadata file. For example:
329 ``gnt-instance add -o snf-image+default --os-parameters img_passwd=SamplePassw0rd,img_format=diskdump,img_id=debian_base-6.0-7-x86_64,img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' -t plain --disk=0:size=10G --no-name-check --no-ip-check --no-nics test1``