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 snf-image supports 3 different types of image formats:
29 * **diskdump** (recommended): a raw dump of a disk
30 * **extdump**: a raw dump of an ext{2,3,4} file system
31 * **ntfsdump**: a raw dump of an NTFS file system
33 These are also the only valid values for the **img_format** OS parameter.
34 The **diskdump** type is the newest and recommended type. Thus, all sample
35 images we provide are of this type. For more details about the internals of
36 image formats please see the :ref:`corresponding advanced section
37 <image-format-advanced>`.
41 Image IDs & Storage back-ends
42 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
44 *snf-image* capable of deploying images that are stored in a variety of
45 different back-ends. The back-end to be used is determined by the value of the
46 *img_id* OS parameter. The following back-ends are supported:
49 The local back-end is used to retrieve images that are stored in the ganeti
50 node that the image deployment takes place. The local back-end is used if
51 the value of the *img_id* ganeti OS parameter is either prefixed with
52 *file://* or is not prefixed at all. All local images are expected to be
53 found under a predifined image directory. By default */var/lib/snf-image* is
54 used, but the user may change this by overwriting the value of the
55 *IMAGE_DIR* variable under ``/etc/default/snf-image``. The name of the image
56 file is created by adding the image type extension in the end of the
57 *img_id*. For example if the *img_id* is *file://slackware* and the image
58 type is *diskdump*, snf-image will expect to find an image file under the
59 following path: ``/usr/lib/snf-image/slackware.diskdump``
61 * **Network back-end**:
62 The network back-end is used to retrieve images that are accessible from the
63 network. If the *imd_id* starts with *http:*, *https:*, *ftp:* or *ftps:*,
64 snf-image will treat the *img_id* as a remote URL and will try to fetch the
65 image using `cURL <http://curl.haxx.se/>`_.
67 * **Pithos back-end**:
68 If an *img_id* is prefixed with *pithos:* or *pithosmap:* the image is
69 considered to be pithos back-ended. *snf-image* contains a special
70 command-line tool (*pithcat*) for retrieving this kind of images. For
71 *pithosmap:* images, the user needs to have set a valid value for the
72 *PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
73 the PITHOS_DB variable needs to contain a valid value too.
74 ``/etc/default/snf-image`` may be used to set both values.
77 The null back-end is used if the *img_id* value is *null*. In this case no
78 image copying is performed. This is usefull if the hard disk already
79 contains an OS installation before *snf-image* is executed (for example if
80 the hard disk is a snapshot of an existing VM's hard disk).
87 In order for *snf-image* to be able to properly configure an image, it may make
88 use of a set of image properties. Those image properties are passed to
89 *snf-image* by Ganeti through the *img_poroperties* OS parameter (see Ganeti OS
90 Interface). The name of all image properties is case-insensitive. For the
91 diskdump format some properties are mandatory. For {ext,ntfs}dump formats all
92 image properties are optional.
94 A list of mandatory and optional properties follows:
96 Mandatory properties (diskdump only)
97 ++++++++++++++++++++++++++++++++++++
99 * **OSFAMILY={linux,windows}**
100 This specifies whether the image is a Linux or a Windows Image.
101 {ext,ntfs}dump formats are self descriptive regarding this property.
102 * **ROOT_PARTITION=n**
103 This specifies the partition number of the root partition. As mentioned
104 earlier, for now, only primary partitions are supported. This property is
105 trivial for {ext,ntfs}dump formats (they only host one partition).
110 * **USERS="username1 username2...."**
111 This is a space-seperated list of users, whose password will be reset by
112 *snf-image*. The use of this property is optional, but highly recommended.
113 For now, if this property is missing, the users are chosen according to a
114 set of rules, but those rules may change or even be dropped in the future.
115 The rules we currently use are listed below:
117 * For Windows images, the *Administrator*'s password is reset.
118 * For Linux and FreeBSD images, the *root* password is reset.
120 * **EXCLUDE_ALL_TASKS=yes**
121 If this property is defined with a value other than null, then during the
122 deployment, the image will not be configured at all. This is really handy
123 because it gives the ability to deploy images hosting operating systems
124 whose configuration is not supported by snf-image.
126 * **EXCLUDE_TASK_<task_name>=yes**
127 This family of properties gives the ability to exclude individual
128 configuration tasks from running. Hence, if the property
129 *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
130 *snf-image*, the aforementioned configuration step will not be executed, and
131 the SSH Keys found in the image will not be removed during the deployment.
132 Task exclusion provides great flexibility, but it needs to be used with
133 great care. Tasks depend on each other and although those dependencies are
134 well documented, automatic task dependency resolution isn't yet supported in
135 *snf-image*. If you exclude task A but not task B which depends on A, you
136 will probably end up with an unsuccessful deployment because B will fail and
137 exit in an abnormal way. You can read more about configuration tasks here.
140 img_properties OS parameter
141 +++++++++++++++++++++++++++++++
143 Image properties are passed to snf_image through the img_properties OS
144 parameter as a simple json string like the one below:
147 | "PROPERTY1": "VALUE1",
148 | "PROPERTY2": "VALUE2",
149 | "PROPERTY3": "VALUE3",
153 | "PROPERTYn": "VALUEn"
157 A real life example for creating a new ganeti instance and passing image
158 properties to snf-image would probably look more like this:
160 ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump...``
162 .. _image-personality:
164 Personality OS Parameter
165 ^^^^^^^^^^^^^^^^^^^^^^^^
167 This parameter is an extension of the Server Personality notation proposed by
168 the OpenStack Compute API v1.1 and defines a list of files to be injected into
169 the image file system.
174 The format of this parameter is a JSON array of objects. Each object in the
175 array supports the following keys:
177 * **path**: The absolute path of the file (string)
178 * **contents**: The content of the file encoded as a base64 string (string)
179 * **owner**: The user ownership of the file (string)
180 * **group**: The group ownership of the file (string)
181 * **mode**: The permission mode of the file (number)
183 The first two (path, contents) are mandatory. The others (owner, group, mode)
184 are optional and their default value is root, root and 0440 respectively.
189 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
190 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
191 their permissions are ``-rw-r--r--`` [#]_
195 | "path": "/tmp/test1",
196 | "contents": "dGVzdDENCg==",
202 | "path": "/tmp/test2",
203 | "contents": "dGVzdDINCg==",
210 .. [#] The first mode is in octal representation and the second in decimal.
218 While developing *snf-image*, we created and tested a number of images. The
219 following images are basic installations of some popular Linux distributions,
220 that have been tested with snf-image and provided here for testing purposes:
223 * Debian Squeeze Base System
224 [`diskdump <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump>`_]
225 [`md5sum <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.md5sum>`_]
226 [`metadata <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.meta>`_]
227 * Debian Wheezy Base System
228 [`diskdump <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump>`_]
229 [`md5sum <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.md5sum>`_]
230 [`metadata <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.meta>`_]
232 [`diskdump <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump>`_]
233 [`md5sum <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.md5sum>`_]
234 [`metadata <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.meta>`_]
236 [`diskdump <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump>`_]
237 [`md5sum <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.md5sum>`_]
238 [`metadata <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.meta>`_]
240 [`diskdump <http://cdn.synnefo.org/fedora-18-x86_64.diskdump>`_]
241 [`md5sum <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.md5sum>`_]
242 [`metadata <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.meta>`_]
243 * Ubuntu Desktop LTS 12.04
244 [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump>`_]
245 [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
246 [`metadata <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
248 [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump>`_]
249 [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
250 [`metadata <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
251 * Ubuntu Desktop 13.04
252 [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump>`_]
253 [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
254 [`metadata <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
256 [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump>`_]
257 [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
258 [`metadata <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
259 * Ubuntu Server 12.04
260 [`diskdump <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump>`_]
261 [`md5sum <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.md5sum>`_]
262 [`metadata <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.meta>`_]
263 * OpenSUSE Desktop 12.3
264 [`diskdump <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump>`_]
265 [`md5sum <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.md5sum>`_]
266 [`metadata <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.meta>`_]
268 [`diskdump <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
269 [`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
270 [`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
278 Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR.
279 Make sure you also have its corresponding metadata file.
281 Spawn a diskdump image
282 ++++++++++++++++++++++
284 If you want to deploy an image of type diskdump, you need to provide the
285 corresponding *img_properties* as described in the
286 :ref:`Image Format<image-format>` section. If using a diskdump found in the
287 :ref:`sample-images` list, use the *img_properties* described in the image's
288 metadata file. For example:
290 ``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``