usage.rst 12.4 KB
Newer Older
1
2
Usage
=====
3
4
5
6
7
8
9
10
11

Ganeti OS Interface
^^^^^^^^^^^^^^^^^^^

*snf-image* requires ganeti-os-interface v20 to operate and it introduces the
following OS Parameters:

 * **img_format** (required if *config_url* is missing): the image format type
   (:ref:`details <image-format>`)
12
13
 * **img_id** (required if *config_url* is missing): the URI used to identify
   the image (:ref:`details <image-id>`)
14
15
16
17
18
19
20
21
22
23
24
25
26
 * **img_passwd** (required if *config_url* is missing): the password to be
   injected to the image
 * **img_properties** (optional): additional image properties used to customize
   the image (:ref:`details <image-properties>`)
 * **img_personality** (optional): files to be injected into the image
   filesystem (:ref:`details <image-personality>`)
 * **config_url** (optional): the url to download configuration data from

.. _image-format:

Image Format
^^^^^^^^^^^^

27
snf-image supports 3 different types of image formats:
28

29
 * **diskdump** (recommended): a raw dump of a disk
30
31
32
 * **extdump**: a raw dump of an ext{2,3,4} file system
 * **ntfsdump**: a raw dump of an NTFS file system

33
34
35
36
37
These are also the only valid values for the **img_format** OS parameter.
The **diskdump** type is the newest and recommended type. Thus, all sample
images we provide are of this type. For more details about the internals of
image formats please see the :ref:`corresponding advanced section
<image-format-advanced>`.
38
39
40
41
42
43

.. _image-id:

Image IDs & Storage back-ends
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

44
45
46
*snf-image* capable of deploying images that are stored in a variety of
different back-ends. The back-end to be used is determined by the value of the
*img_id* OS parameter. The following back-ends are supported:
47
48
49

 * **Local back-end**:
   The local back-end is used to retrieve images that are stored in the ganeti
50
51
52
53
   node that the image deployment takes place. The local back-end is used if
   the value of the *img_id* ganeti OS parameter is either prefixed with
   *file://* or is not prefixed at all. All local images are expected to be
   found under a predifined image directory. By default */var/lib/snf-image* is
54
55
   used, but the user may change this by overwriting the value of the
   *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
59
   type is *diskdump*, snf-image will expect to find an image file under the
   following path: ``/usr/lib/snf-image/slackware.diskdump``
60
61
62
63
64
65
66
67

 * **Network back-end**:
   The network back-end is used to retrieve images that are accessible from the
   network. 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
   image using `cURL <http://curl.haxx.se/>`_.

 * **Pithos back-end**:
68
   If an *img_id* is prefixed with *pithos:* or *pithosmap:* the image is
69
70
71
72
   considered to be pithos back-ended. *snf-image* contains a special
   command-line tool (*pithcat*) for retrieving this kind of images. For
   *pithosmap:* images, the user needs to have set a valid value for the
   *PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
73
74
   the PITHOS_DB variable needs to contain a valid value too.
   ``/etc/default/snf-image`` may be used to set both values.
75
76
77

 * **Null back-end**:
   The null back-end is used if the *img_id* value is *null*. In this case no
78
79
80
   image copying is performed. This is usefull if the hard disk already
   contains an OS installation before *snf-image* is executed (for example if
   the hard disk is a snapshot of an existing VM's hard disk).
81
82
83
84
85
86

.. _image-properties:

Image Properties
^^^^^^^^^^^^^^^^

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
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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=n**
   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 and FreeBSD images, the *root* password is reset.

 * **EXCLUDE_ALL_TASKS=yes**
   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>=yes**
   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 here.


img_properties OS parameter
+++++++++++++++++++++++++++++++

143
144
Image properties are passed to snf_image through the img_properties OS
parameter as a simple json string like the one below:
145
146
147
148
149
150
151
152
153
154
155
156

| {
|     "PROPERTY1": "VALUE1",
|     "PROPERTY2": "VALUE2",
|     "PROPERTY3": "VALUE3",
|     ...
|     ...
|     ...
|     "PROPERTYn": "VALUEn"
| }


157
158
A real life example for creating a new ganeti instance and passing image
properties to snf-image would probably look more like this:
159
160
161
162
163
164
165
166
167
168

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

.. _image-personality:

Personality OS Parameter
^^^^^^^^^^^^^^^^^^^^^^^^

This parameter is an extension of the Server Personality notation proposed by
the OpenStack Compute API v1.1 and defines a list of files to be injected into
169
the image file system.
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210

Format
++++++

The format of this parameter is a JSON array of objects. Each object in the
array supports the following keys:

 * **path**: The absolute path of the file (string)
 * **contents**: The content of the file encoded as a base64 string (string)
 * **owner**: The user ownership of the file (string)
 * **group**: The group ownership of the file (string)
 * **mode**: The permission mode of the file (number)

The first two (path, contents) are mandatory. The others (owner, group, mode)
are optional and their default value is root, root and 0440 respectively.

Example
+++++++

The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
their permissions are ``-rw-r--r--`` [#]_

| [
|     {
|         "path": "/tmp/test1",
|         "contents": "dGVzdDENCg==",
|         "owner": "root",
|         "group": "root",
|         "mode": 0644
|     },
|     {
|         "path": "/tmp/test2",
|         "contents": "dGVzdDINCg==",
|         "owner": "root",
|         "group": "root",
|         "mode": 420
|     }
| ]

.. [#] The first mode is in octal representation and the second in decimal.
211

212
213
214

.. _sample-images:

215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
Sample Images
^^^^^^^^^^^^^

While developing *snf-image*, we created and tested a number of images. The
following images are basic installations of some popular Linux distributions,
that have been tested with snf-image and provided here for testing purposes:


 * Debian Squeeze Base System
   [`diskdump <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.meta>`_]
 * Debian Wheezy Base System
   [`diskdump <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.meta>`_]
 * Debian Desktop
   [`diskdump <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.meta>`_]
 * CentOS 6.0
   [`diskdump <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.meta>`_]
 * Fedora Desktop 18
   [`diskdump <http://cdn.synnefo.org/fedora-18-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.meta>`_]
 * Ubuntu Desktop LTS 12.04
   [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 * Kubuntu LTS 12.04
   [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 * Ubuntu Desktop 13.04
   [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 * Kubuntu 13.04
   [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 * Ubuntu Server 12.04
   [`diskdump <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.meta>`_]
 * OpenSUSE Desktop 12.3
   [`diskdump <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.meta>`_]
 * FreeBSD 9.1
   [`diskdump <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
   [`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
   [`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291

Sample Usage
^^^^^^^^^^^^

Download an Image
+++++++++++++++++

Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR.
Make sure you also have its corresponding metadata file.

Spawn a diskdump image
++++++++++++++++++++++

If you want to deploy an image of type diskdump, you need to provide the
corresponding *img_properties* as described in the
:ref:`Image Format<image-format>` section. If using a diskdump found in the
:ref:`sample-images` list, use the *img_properties* described in the image's
metadata file. For example:

``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``