Statistics
| Branch: | Tag: | Revision:

root / docs / interface.rst @ d0c154c1

History | View | Annotate | Download (8.2 kB)

1
Interface
2
=========
3

    
4
Ganeti OS Interface
5
^^^^^^^^^^^^^^^^^^^
6

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

    
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
15
   injected to the image
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
21

    
22
.. _image-format:
23

    
24
Image Format (img_format)
25
^^^^^^^^^^^^^^^^^^^^^^^^^
26

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

    
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
32

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

    
39
.. _image-id:
40

    
41
Image ID (img_id)
42
^^^^^^^^^^^^^^^^^
43

    
44
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 backend:
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
  | For example, if we want to deploy the image file:
54
  | ``/var/lib/snf-image/slackware.diskdump``
55
  | We need to assign:
56
  | ``img_id=local://slackware.diskdump``
57

    
58
 * **Network backend**:
59
   If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``,
60
   snf-image will treat the **img_id** as a remote URL and will try to fetch the
61
   image using `cURL <http://curl.haxx.se/>`_.
62

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

    
66
 * **Pithos backend**:
67
   If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
68
   image is considered to reside on a Pithos deployment. For ``pithosmap://``
69
   images, the user needs to have set a valid value for the
70
   ``PITHOS_DATA`` variable in snf-image's configuration file
71
   (``/etc/default/snf-image`` by default). For ``pithos://`` images, in
72
   addition to ``PITHOS_DATA``, the user needs to have set a valid value for the
73
   ``PITHOS_DB`` variable, too.
74

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

    
80
 * **Null backend**:
81
   To select the Null backend and skip the fetching and extraction step, we set
82
   ``img_id=null``.
83

    
84
.. _image-properties:
85

    
86
Image Properties (img_properties)
87
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88

    
89
*snf-image* may use a number of properties to properly configure the image.
90
Those image properties are passed to snf-image by Ganeti through the
91
*img_poroperties* OS parameter (see Ganeti OS Interface). The name of all image
92
properties is case-insensitive. For the diskdump format some properties are
93
mandatory. For {ext,ntfs}dump formats all image properties are optional.
94

    
95
We can group image properties in two categories:
96

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

    
101
A list of all properties follows:
102

    
103
Mandatory properties (for diskdump only)
104
++++++++++++++++++++++++++++++++++++++++
105

    
106
 * **OSFAMILY={linux,windows}**
107
   This specifies whether the image is a Linux or a Windows Image.
108
   {ext,ntfs}dump formats are self descriptive regarding this property.
109
 * **ROOT_PARTITION=n**
110
   This specifies the partition number of the root partition. As mentioned
111
   earlier, for now, only primary partitions are supported. This property is
112
   trivial for {ext,ntfs}dump formats (they only host one partition).
113

    
114
Optional properties
115
+++++++++++++++++++
116

    
117
 * **USERS="username1 username2...."**
118
   This is a space-separated list of users, whose password will be reset by
119
   *snf-image*. The use of this property is optional, but highly recommended.
120
   For now, if this property is missing, the users are chosen according to a
121
   set of rules, but those rules may change or even be dropped in the future.
122
   The rules we currently use are listed below:
123

    
124
     * For Windows images, the *Administrator*'s password is reset.
125
     * For Linux and FreeBSD images, the *root* password is reset.
126

    
127
 * **EXCLUDE_ALL_TASKS=yes**
128
   If this property is defined with a value other than null, then during the
129
   deployment, the image will not be configured at all. This is really handy
130
   because it gives the ability to deploy images hosting operating systems
131
   whose configuration is not supported by snf-image.
132

    
133
 * **EXCLUDE_TASK_<task_name>=yes**
134
   This family of properties gives the ability to exclude individual
135
   configuration tasks from running. Hence, if the property
136
   *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
137
   *snf-image*, the aforementioned configuration step will not be executed, and
138
   the SSH Keys found in the image will not be removed during the deployment.
139
   Task exclusion provides great flexibility, but it needs to be used with
140
   great care. Tasks depend on each other and although those dependencies are
141
   well documented, automatic task dependency resolution isn't yet supported in
142
   *snf-image*. If you exclude task A but not task B which depends on A, you
143
   will probably end up with an unsuccessful deployment because B will fail and
144
   exit in an abnormal way. You can read more about configuration tasks here.
145

    
146
img_properties OS parameter
147
+++++++++++++++++++++++++++
148

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

    
152
| {
153
|     "PROPERTY1": "VALUE1",
154
|     "PROPERTY2": "VALUE2",
155
|     "PROPERTY3": "VALUE3",
156
|     ...
157
|     ...
158
|     ...
159
|     "PROPERTYn": "VALUEn"
160
| }
161

    
162

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

    
166
.. code-block:: console
167

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

    
170
.. _image-personality:
171

    
172
Image Personality (img_personality)
173
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
174

    
175
This parameter is an extension of the Server Personality notation proposed by
176
the OpenStack Compute API v1.1 and defines a list of files to be injected into
177
the image file system.
178

    
179
Format
180
++++++
181

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

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

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

    
194
Example
195
+++++++
196

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

    
201
| [
202
|     {
203
|         "path": "/tmp/test1",
204
|         "contents": "dGVzdDENCg==",
205
|         "owner": "root",
206
|         "group": "root",
207
|         "mode": 0644
208
|     },
209
|     {
210
|         "path": "/tmp/test2",
211
|         "contents": "dGVzdDINCg==",
212
|         "owner": "root",
213
|         "group": "root",
214
|         "mode": 420
215
|     }
216
| ]
217

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