interface.rst 9.97 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
Interface
=========

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>`)
 * **img_id** (required if *config_url* is missing): the URI used to identify
   the image (:ref:`details <image-id>`)
 * **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>`)
18
19
20
 * **img_personality** (optional): files to be injected into the image's file
   system (:ref:`details <image-personality>`)
 * **config_url** (optional): the URL to download configuration data from
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

.. _image-format:

Image Format (img_format)
^^^^^^^^^^^^^^^^^^^^^^^^^

snf-image supports 3 different types of image formats:

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

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

.. _image-id:

Image ID (img_id)
^^^^^^^^^^^^^^^^^

The **img_id** OS parameter points to the actual Image that we want to deploy.
45
It is a URI and its prefix denotes the type of :ref:`backend <storage-backends>`
46
to be used. If no prefix is used, it defaults to the local back-end:
47

48
 * **Local backend**:
49
   To select it, the prefix should be ``local://``, followed by the name of the
50
   image. All local images are expected to be found under a predefined image
51
   directory (``/var/lib/snf-image`` by default).
52
53
54
55

  | For example, if we want to deploy the image file:
  | ``/var/lib/snf-image/slackware.diskdump``
  | We need to assign:
56
  | ``img_id=local://slackware.diskdump``
57

58
 * **Network backend**:
59
60
61
   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/>`_.
62
63
64

  | For example, if we want to deploy an image from an http location:
  | ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
65

66
 * **Pithos backend**:
67
68
   If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
   image is considered to reside on a Pithos deployment. For ``pithosmap://``
Chrysostomos Nanakos's avatar
Chrysostomos Nanakos committed
69
70
71
72
73
74
   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
   default) if the storage backend is ``nfs`` or ``PITHOS_RADOS_POOL_MAPS`` and
   ``PITHOS_RADOS_POOL_BLOCKS`` if the storage backend is ``rados``.
   For ``pithos://`` images, in addition to ``PITHOS_DATA`` or
   ``PITHOS_RADOS_POOL_*``, the user needs to have set a valid value for the
75
   ``PITHOS_DB`` variable, too.
76
77
78
79

  | For example, if we want to deploy using a full Pithos URI:
  | ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
  | or if we already know the map:
80
  | ``img_id=pithosmap://<slackware-image-map-name>/<size>``
81

82
 * **Null backend**:
83
   To select the Null back-end and skip the fetching and extraction step, we set
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
   ``img_id=null``.

.. _image-properties:

Image Properties (img_properties)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

*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
*img_poroperties* OS parameter (see 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.

We can group image properties in two categories:

1. Generic properties (*OSFAMILY*, *ROOT_PARTITION*, *USERS*)
2. Configuration tasks to run (*EXCLUDE_ALL_TASKS*, *EXCLUDE_TASK_<task_name>*)
   (see here for :ref:`valid configuration tasks <image-configuration-tasks>`)

A list of all properties follows:

Mandatory properties (for diskdump only)
++++++++++++++++++++++++++++++++++++++++

108
109
 * **OSFAMILY=linux|windows|freebsd|netbsd|openbsd**
   This specifies whether the image is a Linux, a Windows or a \*BSD Image.
110
111
112
113
114
115
116
117
118
119
   {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...."**
Nikos Skalkotos's avatar
Nikos Skalkotos committed
120
   This is a space-separated list of users, whose password will be reset by
121
122
123
124
125
126
   *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.
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
     * For Linux and \*BSD images, the *root* password is reset.

 * **DO_SYNC=yes**
   By default in ResizeUnmounted task, when ``resize2fs`` is executed to
   enlarge a ext[234] file system, ``fsync()`` is disabled to speed up the
   whole process. I for some reason you need to disable this behavior, use the
   *DO_SYNC* image property.

 * **PASSWORD_HASHING_METHOD=md5|sha1|blowfish|sha256|sha512**
   This property can be used on Unix instances to specify the method to be used
   to hash the users password. By default this is determined by the type of the
   instance. For Linux and FreeBSD instances ``sha512`` is used, for OpenBSD
   ``blowfish`` and for NetBSD ``sha1``. Use this property with care. Most
   systems don't support all hashing methods (see
   `here <http://pythonhosted.org/passlib/modular_crypt_format.html#mcf-identifiers>`_
   for more info).
143

144
145
 * **SWAP=<partition id>:<size>**
   If this property is defined, *snf-image* will create a swap partition with
146
   the specified size in MB. The *partition id* is the number that the Linux
147
   kernel will assign to this partition. For example, if you have a disk with
148
   an MSDOS  partition table on it and one primary partition, the image
149
150
151
152
153
154
155
   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
   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=2 and a logical swap partition with id=5 in it with the same size. This
   property only applies to Linux instances.

156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
 * **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
+++++++++++++++++++++++++++

Image properties are passed to snf_image through the img_properties OS
179
parameter as a simple JSON string like the one below:
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
211
212
213
214

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


A real life example for creating a new Ganeti instance and passing image
properties to snf-image looks like this:

.. code-block:: console

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

.. _image-personality:

Image Personality (img_personality)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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
the image file system.

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)
215
 * **contents**: The content of the file encoded as a Base64 string (string)
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
 * **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.