root / man / ganeti-os-interface.sgml @ 96b39bcc
History | View | Annotate | Download (15.2 kB)
1 |
<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ |
---|---|
2 |
|
3 |
<!-- Fill in your name for FIRSTNAME and SURNAME. --> |
4 |
<!-- Please adjust the date whenever revising the manpage. --> |
5 |
<!ENTITY dhdate "<date>October 02, 2009</date>"> |
6 |
<!-- SECTION should be 1-8, maybe w/ subsection other parameters are |
7 |
allowed: see man(7), man(1). --> |
8 |
<!ENTITY dhsection "<manvolnum>7</manvolnum>"> |
9 |
<!ENTITY dhucpackage "<refentrytitle>ganeti-os-interface</refentrytitle>"> |
10 |
<!ENTITY dhpackage "ganeti"> |
11 |
|
12 |
<!ENTITY debian "<productname>Debian</productname>"> |
13 |
<!ENTITY gnu "<acronym>GNU</acronym>"> |
14 |
<!ENTITY gpl "&gnu; <acronym>GPL</acronym>"> |
15 |
<!ENTITY footer SYSTEM "footer.sgml"> |
16 |
]> |
17 |
|
18 |
<refentry> |
19 |
<refentryinfo> |
20 |
<copyright> |
21 |
<year>2006</year> |
22 |
<year>2007</year> |
23 |
<year>2008</year> |
24 |
<year>2009</year> |
25 |
<year>2010</year> |
26 |
<holder>Google Inc.</holder> |
27 |
</copyright> |
28 |
&dhdate; |
29 |
</refentryinfo> |
30 |
<refmeta> |
31 |
&dhucpackage; |
32 |
|
33 |
&dhsection; |
34 |
<refmiscinfo>ganeti 2.1</refmiscinfo> |
35 |
</refmeta> |
36 |
<refnamediv> |
37 |
<refname>ganeti-os-interface</refname> |
38 |
|
39 |
<refpurpose>specifications for guest OS types |
40 |
</refpurpose> |
41 |
|
42 |
</refnamediv> |
43 |
|
44 |
<refsect1> |
45 |
<title>DESCRIPTION</title> |
46 |
|
47 |
<para> |
48 |
The method of supporting guest operating systems in Ganeti is to |
49 |
have, for each guest OS type, a directory containing a number of |
50 |
required files. |
51 |
</para> |
52 |
|
53 |
|
54 |
</refsect1> |
55 |
<refsect1> |
56 |
<title>REFERENCE</title> |
57 |
|
58 |
<para> |
59 |
There are six required files: <filename>create</filename>, |
60 |
<filename>import</filename>, <filename>export</filename>, |
61 |
<filename>rename</filename> (executables), |
62 |
<filename>ganeti_api_version</filename> and |
63 |
<filename>variants.list</filename> (text file). |
64 |
</para> |
65 |
|
66 |
<refsect2> |
67 |
<title>Common environment</title> |
68 |
<para> |
69 |
All commands will get their input via environment variables. A |
70 |
common set of variables will be exported for all commands, and |
71 |
some of them might have extra ones. Note that all counts are |
72 |
zero-based. |
73 |
</para> |
74 |
<variablelist> |
75 |
<varlistentry> |
76 |
<term>OS_API_VERSION</term> |
77 |
<listitem> |
78 |
<simpara>The OS api version that the rest of the |
79 |
environment conforms to.</simpara> |
80 |
</listitem> |
81 |
</varlistentry> |
82 |
<varlistentry> |
83 |
<term>INSTANCE_NAME</term> |
84 |
<listitem> |
85 |
<simpara>The instance name the script should operate |
86 |
on.</simpara> |
87 |
</listitem> |
88 |
</varlistentry> |
89 |
<varlistentry> |
90 |
<term>INSTANCE_OS</term> |
91 |
<listitem> |
92 |
<simpara>The name os the instance's OS as Ganeti knows |
93 |
it. This can simplify the OS scripts by providing the same |
94 |
scripts under multiple names, and then the scripts can use |
95 |
this name to alter their behaviour.</simpara> |
96 |
<simpara>Under OS api 15 changing the script behavior based |
97 |
on this variable is deprecated: OS_VARIANT should be used |
98 |
instead (see below).</simpara> |
99 |
</listitem> |
100 |
</varlistentry> |
101 |
<varlistentry> |
102 |
<term>OS_VARIANT</term> |
103 |
<listitem> |
104 |
<simpara>The variant of the OS which should be installed. Each OS |
105 |
must support all variants listed under its |
106 |
<filename>variants.list</filename> file, and may support more. |
107 |
Any more supported variants should be properly documented in the |
108 |
per-os documentation.</simpara> |
109 |
</listitem> |
110 |
</varlistentry> |
111 |
<varlistentry> |
112 |
<term>HYPERVISOR</term> |
113 |
<listitem> |
114 |
<simpara>The hypervisor of this instance.</simpara> |
115 |
</listitem> |
116 |
</varlistentry> |
117 |
<varlistentry> |
118 |
<term>DISK_COUNT</term> |
119 |
<listitem> |
120 |
<simpara>The number of disks the instance has. The actual |
121 |
disk defitions are in a set of additional variables. The |
122 |
instance's disk will be numbered from 0 to this value |
123 |
minus one.</simpara> |
124 |
</listitem> |
125 |
</varlistentry> |
126 |
<varlistentry> |
127 |
<term>DISK_%N_PATH</term> |
128 |
<listitem> |
129 |
<simpara>The path to the storage for disk N of the |
130 |
instance. This might be either a block device or a regular |
131 |
file, in which case the OS scripts should use |
132 |
<emphasis>losetup</emphasis> (if they need to mount |
133 |
it). E.g. the first disk of the instance might be exported |
134 |
as <envar>DISK_0_PATH=/dev/drbd0</envar>.</simpara> |
135 |
</listitem> |
136 |
</varlistentry> |
137 |
<varlistentry> |
138 |
<term>DISK_%N_ACCESS</term> |
139 |
<listitem> |
140 |
<simpara>This is how the hypervisor will export the |
141 |
instance disks: either read-write (<emphasis>rw</emphasis>) or |
142 |
read-only (<emphasis>ro</emphasis>).</simpara> |
143 |
</listitem> |
144 |
</varlistentry> |
145 |
<varlistentry> |
146 |
<term>DISK_%N_FRONTEND_TYPE</term> |
147 |
<listitem> |
148 |
<simpara>(Optional) If applicable to the current |
149 |
hypervisor type: the type of the device exported by the |
150 |
hypervisor. For example, the Xen HVM hypervisor can export |
151 |
disks as either <emphasis>paravirtual</emphasis> or |
152 |
<emphasis>ioemu</emphasis>.</simpara> |
153 |
</listitem> |
154 |
</varlistentry> |
155 |
<varlistentry> |
156 |
<term>DISK_%N_BACKEND_TYPE</term> |
157 |
<listitem> |
158 |
<simpara>How files are visible on the node side. This can |
159 |
be either <emphasis>block</emphasis> (when using block |
160 |
devices) or <emphasis>file:type</emphasis>, where |
161 |
<emphasis>type</emphasis> is either |
162 |
<emphasis>loop</emphasis> <emphasis>blktap</emphasis> |
163 |
depending on how the hypervisor will be configured. Note |
164 |
that not all backend types apply to all |
165 |
hypervisors.</simpara> |
166 |
</listitem> |
167 |
</varlistentry> |
168 |
<varlistentry> |
169 |
<term>NIC_COUNT</term> |
170 |
<listitem> |
171 |
<simpara>Similar to the <envar>DISK_COUNT</envar>, this |
172 |
represents the number of NICs of the instance.</simpara> |
173 |
</listitem> |
174 |
</varlistentry> |
175 |
<varlistentry> |
176 |
<term>NIC_%N_MAC</term> |
177 |
<listitem> |
178 |
<simpara>The MAC address associated with this |
179 |
interface.</simpara> |
180 |
</listitem> |
181 |
</varlistentry> |
182 |
<varlistentry> |
183 |
<term>NIC_%N_IP</term> |
184 |
<listitem> |
185 |
<simpara>The IP address, if any, associated with the N-th |
186 |
NIC of the instance.</simpara> |
187 |
</listitem> |
188 |
</varlistentry> |
189 |
<varlistentry> |
190 |
<term>NIC_%N_BRIDGE</term> |
191 |
<listitem> |
192 |
<simpara>The bridge to which this NIC will be attached |
193 |
to.</simpara> |
194 |
</listitem> |
195 |
</varlistentry> |
196 |
<varlistentry> |
197 |
<term>NIC_%N_FRONTEND_TYPE</term> |
198 |
<listitem> |
199 |
<para>(Optional) If applicable, the type of the exported |
200 |
NIC to the instance, this can be one of of: <simplelist |
201 |
type="inline"> <member>rtl8139</member> |
202 |
<member>ne2k_pci</member> <member>ne2k_isa</member> |
203 |
<member>paravirtual</member> </simplelist>. |
204 |
</para> |
205 |
</listitem> |
206 |
</varlistentry> |
207 |
<varlistentry> |
208 |
<term>DEBUG_LEVEL</term> |
209 |
<listitem> |
210 |
<simpara>If non-zero, this should cause the OS script to |
211 |
generate verbose logs of its execution, for |
212 |
troubleshooting purposes. Currently only |
213 |
<emphasis>0</emphasis> and <emphasis>1</emphasis> are |
214 |
valid values.</simpara> |
215 |
</listitem> |
216 |
</varlistentry> |
217 |
</variablelist> |
218 |
</refsect2> |
219 |
|
220 |
<refsect2> |
221 |
<title>create</title> |
222 |
|
223 |
<para>The <command>create</command> command is used for creating |
224 |
a new instance from scratch. It has no additional environment |
225 |
variables bside the common ones.</para> |
226 |
|
227 |
<para>The <envar>INSTANCE_NAME</envar> variable denotes the name |
228 |
of the instance, which is guaranteed to resolve to an IP |
229 |
address. The create script should configure the instance |
230 |
according to this name. It can configure the IP statically or |
231 |
not, depending on the deployment environment.</para> |
232 |
|
233 |
<para>The <envar>INSTANCE_REINSTALL</envar> variable is set to '1' when |
234 |
this create request is reinstalling and existing instance, rather than |
235 |
creating one anew. This can be used, for example, to preserve some |
236 |
data in the old instance in an os-specific way.</para> |
237 |
|
238 |
</refsect2> |
239 |
|
240 |
<refsect2> |
241 |
<title>export</title> |
242 |
|
243 |
<para> |
244 |
This command is used in order to make a backup of a given disk |
245 |
of the instance. The command should write to stdout a dump of |
246 |
the given block device. The output of this program will be |
247 |
passed during restore to the <command>import</command> |
248 |
command. |
249 |
</para> |
250 |
|
251 |
<para> |
252 |
The specific disk to backup is denoted by two additional |
253 |
environment variables: <envar>EXPORT_INDEX</envar> which |
254 |
denotes the index in the instance disks structure (and could |
255 |
be used for example to skip the second disk if not needed for |
256 |
backup) and <envar>EXPORT_PATH</envar> which has the same |
257 |
value as <emphasis>DISK_N_PATH</emphasis> but is duplicate |
258 |
here for easier usage by shell scripts (rather than parse the |
259 |
DISK_... variables). |
260 |
</para> |
261 |
|
262 |
</refsect2> |
263 |
|
264 |
<refsect2> |
265 |
<title>import</title> |
266 |
|
267 |
<para> |
268 |
The <command>import</command> command is used for restoring an |
269 |
instance from a backup as done by |
270 |
<command>export</command>. The arguments are the similar to |
271 |
those passed to <command>export</command>, whose output will |
272 |
be provided on <acronym>stdin</acronym>. |
273 |
</para> |
274 |
|
275 |
<para> |
276 |
The difference in variables is that the current disk is called |
277 |
by <envar>IMPORT_DEVICE</envar> and <envar>IMPORT_INDEX</envar> |
278 |
(instead of <emphasis>EXPORT_</emphasis>). |
279 |
</para> |
280 |
|
281 |
</refsect2> |
282 |
|
283 |
<refsect2> |
284 |
<title>rename</title> |
285 |
|
286 |
<para> |
287 |
This command is used in order to perform a rename at the |
288 |
instance OS level, after the instance has been renamed in |
289 |
Ganeti. The command should do whatever steps are required to |
290 |
ensure that the instance is updated to use the new name, if |
291 |
the operating system supports it. |
292 |
</para> |
293 |
|
294 |
<para> |
295 |
Note that it is acceptable for the rename script to do nothing |
296 |
at all, however be warned that in this case, there will be a |
297 |
desynchronization between what <computeroutput>gnt-instance |
298 |
list</computeroutput> shows you and the actual hostname of the |
299 |
instance. |
300 |
</para> |
301 |
|
302 |
<para>The script will be passed one additional environment |
303 |
variable called <envar>OLD_INSTANCE_NAME</envar> which holds the |
304 |
old instance name. The <envar>INSTANCE_NAME</envar> variable |
305 |
holds the new instance name.</para> |
306 |
|
307 |
<para> |
308 |
A very simple rename script should at least change the |
309 |
hostname and IP address of the instance, leaving the |
310 |
administrator to update the other services. |
311 |
</para> |
312 |
</refsect2> |
313 |
|
314 |
<refsect2> |
315 |
<title>ganeti_api_version</title> |
316 |
<para> |
317 |
The <filename>ganeti_api_version</filename> file is a plain |
318 |
text file containing the version(s) of the guest OS api that |
319 |
this OS definition complies with, one per line. The version |
320 |
documented by this man page is 15, so this file must contain |
321 |
the number 15 followed by a newline if only this version is |
322 |
supported. A script compatible more than one ganeti version |
323 |
should contain the most recent version first (i.e. 15), |
324 |
followed by the old version(s) (in this case 10 and/or 5). |
325 |
</para> |
326 |
</refsect2> |
327 |
|
328 |
<refsect2> |
329 |
<title>variants.list</title> |
330 |
<para> |
331 |
<filename>variants.list</filename> is a plain text file |
332 |
containing all the declared supported variants for this |
333 |
OS, one per line. At least one variant must be supported. |
334 |
</para> |
335 |
</refsect2> |
336 |
|
337 |
</refsect1> |
338 |
|
339 |
<refsect1> |
340 |
<title>NOTES</title> |
341 |
|
342 |
<refsect2> |
343 |
<title>Retrocompatibility</title> |
344 |
|
345 |
<para> |
346 |
Ganeti 2.1 is compatible with both api version 10, and 15. |
347 |
In api version 10 the <filename>variants.list</filename> |
348 |
file is ignored and no OS_VARIANT environment variable is |
349 |
passed. |
350 |
</para> |
351 |
</refsect2> |
352 |
|
353 |
<refsect2> |
354 |
<title>Common behaviour</title> |
355 |
|
356 |
<para>All the scripts should display an usage message when |
357 |
called with a wrong number of arguments or when the first |
358 |
argument is <option>-h</option> or |
359 |
<option>--help</option>.</para> |
360 |
|
361 |
</refsect2> |
362 |
|
363 |
<refsect2> |
364 |
<title>Upgrading from old versions</title> |
365 |
<refsect3> |
366 |
|
367 |
<title>Version 10 to 15</title> |
368 |
|
369 |
<para> |
370 |
The <filename>variants.list</filename> file has been |
371 |
added, so OSes should support at least one variant, |
372 |
declaring it in that file and must be prepared to parse |
373 |
the OS_VARIANT environment variable. OSes are free to |
374 |
support more variants than just the declared ones. |
375 |
</para> |
376 |
|
377 |
</refsect3> |
378 |
|
379 |
<refsect3> |
380 |
|
381 |
<title>Version 5 to 10</title> |
382 |
|
383 |
<para> |
384 |
The method os passing data has changed from command line |
385 |
options to environment variables, so scripts should be |
386 |
modified to use these. For an example of how this can be |
387 |
done in a way compatible with both versions, feel free to |
388 |
look at the debootstrap instance's |
389 |
<filename>common.sh</filename> auxiliary script. |
390 |
</para> |
391 |
|
392 |
<para> |
393 |
Also, instances can have now a variable number of disks, not |
394 |
only two, and a variable number of NICs (instead of fixed |
395 |
one), so the scripts should deal with this. The biggest |
396 |
change is in the import/export, which are called once per |
397 |
disk, instead of once per instance. |
398 |
</para> |
399 |
|
400 |
</refsect3> |
401 |
|
402 |
<refsect3> |
403 |
<title>Version 4 to 5</title> |
404 |
<para> |
405 |
The <filename>rename</filename> script has been added. If |
406 |
you don't want to do any changes on the instances after a |
407 |
rename, you can migrate the OS definition to version 5 by |
408 |
creating the <filename>rename</filename> script simply as: |
409 |
<screen> |
410 |
#!/bin/sh |
411 |
|
412 |
exit 0 |
413 |
</screen> |
414 |
</para> |
415 |
|
416 |
<para>Note that the script must be executable.</para> |
417 |
</refsect3> |
418 |
</refsect2> |
419 |
|
420 |
<!-- |
421 |
<refsect2> |
422 |
|
423 |
<title>Export/import format</title> |
424 |
|
425 |
<para> |
426 |
It is up to the export and import scripts to define the format |
427 |
they use. It is only required for these two to work |
428 |
together. It is not recommended that |
429 |
</para> |
430 |
|
431 |
</refsect2> |
432 |
--> |
433 |
|
434 |
</refsect1> |
435 |
|
436 |
&footer; |
437 |
|
438 |
</refentry> |
439 |
|
440 |
<!-- Keep this comment at the end of the file |
441 |
Local variables: |
442 |
mode: sgml |
443 |
sgml-omittag:t |
444 |
sgml-shorttag:t |
445 |
sgml-minimize-attributes:nil |
446 |
sgml-always-quote-attributes:t |
447 |
sgml-indent-step:2 |
448 |
sgml-indent-data:t |
449 |
sgml-parent-document:nil |
450 |
sgml-default-dtd-file:nil |
451 |
sgml-exposed-tags:nil |
452 |
sgml-local-catalogs:nil |
453 |
sgml-local-ecat-files:nil |
454 |
End: |
455 |
--> |