root / docs / interface.rst @ 37e9c087
History | View | Annotate | Download (9.8 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:`back-end <storage-backends>` |
46 |
to be used. If no prefix is used, it defaults to the local back-end: |
47 |
|
48 |
* **Local back-end**: |
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 back-end**: |
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 back-end**: |
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>/<size>`` |
79 |
|
80 |
* **Null back-end**: |
81 |
To select the Null back-end 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|freebsd|netbsd|openbsd** |
107 |
This specifies whether the image is a Linux, a Windows or a \*BSD 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 \*BSD images, the *root* password is reset. |
126 |
|
127 |
* **DO_SYNC=yes** |
128 |
By default in ResizeUnmounted task, when ``resize2fs`` is executed to |
129 |
enlarge a ext[234] file system, ``fsync()`` is disabled to speed up the |
130 |
whole process. I for some reason you need to disable this behavior, use the |
131 |
*DO_SYNC* image property. |
132 |
|
133 |
* **PASSWORD_HASHING_METHOD=md5|sha1|blowfish|sha256|sha512** |
134 |
This property can be used on Unix instances to specify the method to be used |
135 |
to hash the users password. By default this is determined by the type of the |
136 |
instance. For Linux and FreeBSD instances ``sha512`` is used, for OpenBSD |
137 |
``blowfish`` and for NetBSD ``sha1``. Use this property with care. Most |
138 |
systems don't support all hashing methods (see |
139 |
`here <http://pythonhosted.org/passlib/modular_crypt_format.html#mcf-identifiers>`_ |
140 |
for more info). |
141 |
|
142 |
* **SWAP=<partition id>:<size>** |
143 |
If this property is defined, *snf-image* will create a swap partition with |
144 |
the specified size in MB. The *partition id* is the number that the linux |
145 |
kernel will assign to this partition. For example, if you have a disk with |
146 |
an msdos partition table on it and one primary partition, the image |
147 |
property *SWAP=2:512* would instruct *snf-image* to create a 512MB long |
148 |
primary partition for swap with id=2. On the other hand, if the SWAP |
149 |
property had this form: *SWAP=5:512*, since primary partitions may have an |
150 |
id from 1 to 4, *snf-image* would create a 512MB extended partition with |
151 |
id=2 and a logical swap partition with id=5 in it with the same size. This |
152 |
property only applies to Linux instances. |
153 |
|
154 |
* **EXCLUDE_ALL_TASKS=yes** |
155 |
If this property is defined with a value other than null, then during the |
156 |
deployment, the image will not be configured at all. This is really handy |
157 |
because it gives the ability to deploy images hosting operating systems |
158 |
whose configuration is not supported by snf-image. |
159 |
|
160 |
* **EXCLUDE_TASK_<task_name>=yes** |
161 |
This family of properties gives the ability to exclude individual |
162 |
configuration tasks from running. Hence, if the property |
163 |
*EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to |
164 |
*snf-image*, the aforementioned configuration step will not be executed, and |
165 |
the SSH Keys found in the image will not be removed during the deployment. |
166 |
Task exclusion provides great flexibility, but it needs to be used with |
167 |
great care. Tasks depend on each other and although those dependencies are |
168 |
well documented, automatic task dependency resolution isn't yet supported in |
169 |
*snf-image*. If you exclude task A but not task B which depends on A, you |
170 |
will probably end up with an unsuccessful deployment because B will fail and |
171 |
exit in an abnormal way. You can read more about configuration tasks here. |
172 |
|
173 |
img_properties OS parameter |
174 |
+++++++++++++++++++++++++++ |
175 |
|
176 |
Image properties are passed to snf_image through the img_properties OS |
177 |
parameter as a simple json string like the one below: |
178 |
|
179 |
| { |
180 |
| "PROPERTY1": "VALUE1", |
181 |
| "PROPERTY2": "VALUE2", |
182 |
| "PROPERTY3": "VALUE3", |
183 |
| ... |
184 |
| ... |
185 |
| ... |
186 |
| "PROPERTYn": "VALUEn" |
187 |
| } |
188 |
|
189 |
|
190 |
A real life example for creating a new Ganeti instance and passing image |
191 |
properties to snf-image looks like this: |
192 |
|
193 |
.. code-block:: console |
194 |
|
195 |
``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump,img_id=...`` |
196 |
|
197 |
.. _image-personality: |
198 |
|
199 |
Image Personality (img_personality) |
200 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
201 |
|
202 |
This parameter is an extension of the Server Personality notation proposed by |
203 |
the OpenStack Compute API v1.1 and defines a list of files to be injected into |
204 |
the image file system. |
205 |
|
206 |
Format |
207 |
++++++ |
208 |
|
209 |
The format of this parameter is a JSON array of objects. Each object in the |
210 |
array supports the following keys: |
211 |
|
212 |
* **path**: The absolute path of the file (string) |
213 |
* **contents**: The content of the file encoded as a base64 string (string) |
214 |
* **owner**: The user ownership of the file (string) |
215 |
* **group**: The group ownership of the file (string) |
216 |
* **mode**: The permission mode of the file (number) |
217 |
|
218 |
The first two (path, contents) are mandatory. The others (owner, group, mode) |
219 |
are optional and their default value is root, root and 0440 respectively. |
220 |
|
221 |
Example |
222 |
+++++++ |
223 |
|
224 |
The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose |
225 |
content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and |
226 |
their permissions are ``-rw-r--r--`` [#]_ |
227 |
|
228 |
| [ |
229 |
| { |
230 |
| "path": "/tmp/test1", |
231 |
| "contents": "dGVzdDENCg==", |
232 |
| "owner": "root", |
233 |
| "group": "root", |
234 |
| "mode": 0644 |
235 |
| }, |
236 |
| { |
237 |
| "path": "/tmp/test2", |
238 |
| "contents": "dGVzdDINCg==", |
239 |
| "owner": "root", |
240 |
| "group": "root", |
241 |
| "mode": 420 |
242 |
| } |
243 |
| ] |
244 |
|
245 |
.. [#] The first mode is in octal representation and the second in decimal. |