Export device UUIDs to hooks and OS scripts
[ganeti-github.git] / man / ganeti-os-interface.rst
1 ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
2 ========================================================
3
4 Name
5 ----
6
7 ganeti-os-interface - Specifications for guest OS types
8
9 DESCRIPTION
10 -----------
11
12 The method of supporting guest operating systems in Ganeti is to have,
13 for each guest OS type, a directory containing a number of required
14 files. This directory must be present across all nodes (Ganeti doesn't
15 replicate it) in order for the OS to be usable by Ganeti.
16
17
18 REFERENCE
19 ---------
20
21 There are eight required files: *create*, *import*, *export*, *rename*,
22 *verify* (executables), *ganeti_api_version*, *variants.list* and
23 *parameters.list* (text files).
24
25 Common environment
26 ~~~~~~~~~~~~~~~~~~
27
28 All commands will get their input via environment variables. A
29 common set of variables will be exported for all commands, and some
30 of them might have extra ones. Note that all counts are
31 zero-based.
32
33 Since Ganeti version 2.5, the environment will be cleaned up before
34 being passed to scripts, therefore they will not inherit the environment
35 in with which the ganeti node daemon was started. If you depend on any
36 environment variables (non-Ganeti), then you will need to define or
37 source them appropriately.
38
39 OS_API_VERSION
40     The OS API version that the rest of the environment conforms to.
41
42 INSTANCE_NAME
43     The instance name the script should operate on.
44
45 INSTANCE_OS, OS_NAME
46     Both names point to the name of the instance's OS as Ganeti knows
47     it. This can simplify the OS scripts by providing the same scripts
48     under multiple names, and then the scripts can use this name to
49     alter their behaviour.
50
51     With OS API 15 changing the script behavior based on this variable
52     is deprecated: OS_VARIANT should be used instead (see below).
53
54 OS_VARIANT
55     The variant of the OS which should be installed. Each OS must
56     support all variants listed under its variants.list file, and may
57     support more. Any more supported variants should be properly
58     documented in the per-OS documentation.
59
60 HYPERVISOR
61     The hypervisor of this instance.
62
63 DISK_COUNT
64     The number of disks the instance has. The actual disk defitions are
65     in a set of additional variables. The instance's disk will be
66     numbered from 0 to this value minus one.
67
68 DISK_%N_PATH
69     The path to the storage for disk N of the instance. This might be
70     either a block device or a regular file, in which case the OS
71     scripts should use ``losetup`` (if they need to mount it). E.g. the
72     first disk of the instance might be exported as
73     ``DISK_0_PATH=/dev/drbd0``.
74
75 DISK_%N_ACCESS
76     This is how the hypervisor will export the instance disks: either
77     read-write (``rw``) or read-only (``ro``).
78
79 DISK_%N_UUID
80     The uuid associated with the N-th disk of the instance.
81
82 DISK_%N_NAME
83     (Optional) The name, if any, associated with the N-th disk of the instance.
84
85 DISK_%N_FRONTEND_TYPE
86     (Optional) If applicable to the current hypervisor type: the type
87     of the device exported by the hypervisor. For example, the Xen HVM
88     hypervisor can export disks as either ``paravirtual`` or
89     ``ioemu``.
90
91 DISK_%N_BACKEND_TYPE
92     How files are visible on the node side. This can be either
93     ``block`` (when using block devices) or ``file:type``, where
94     ``type`` is either ``loop`` or ``blktap`` depending on how the
95     hypervisor will be configured.  Note that not all backend types
96     apply to all hypervisors.
97
98 NIC_COUNT
99     Similar to the ``DISK_COUNT``, this represents the number of NICs
100     of the instance.
101
102 NIC_%N_MAC
103     The MAC address associated with this interface.
104
105 NIC_%N_UUID
106     The uuid associated with the N-th NIC of the instance.
107
108 NIC_%N_NAME
109     (Optional) The name, if any, associated with the N-th NIC of the instance.
110
111 NIC_%N_IP
112     The IP address, if any, associated with the N-th NIC of the
113     instance.
114
115 NIC_%N_MODE
116     The NIC mode, routed, bridged or openvswitch
117
118 NIC_%N_BRIDGE
119     The bridge to which this NIC will be attached. This variable is
120     defined only when the NIC is in bridged mode.
121
122 NIC_%N_LINK
123     In bridged or openvswitch mode, this is the interface to which the
124     NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In
125     routed mode it is the routing table which will be used by the
126     hypervisor to insert the appropriate routes.
127
128 NIC_%N_FRONTEND_TYPE
129     (Optional) If applicable, the type of the exported NIC to the
130     instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
131     ``ne2k_isa``, ``paravirtual``.
132
133 NIC_%d_NETWORK_NAME
134     (Optional) If a NIC network is specified, the network's name.
135
136 NIC_%d_NETWORK_UUID
137     (Optional) If a NIC network is specified, the network's uuid.
138
139 NIC_%d_NETWORK_FAMILY
140     (Optional) If a NIC network is specified, the network's family.
141
142 NIC_%d_NETWORK_SUBNET
143     (Optional) If a NIC network is specified, the network's IPv4 subnet.
144
145 NIC_%d_NETWORK_GATEWAY
146     (Optional) If a NIC network is specified, the network's IPv4
147     gateway.
148
149 NIC_%d_NETWORK_SUBNET6
150     (Optional) If a NIC network is specified, the network's IPv6 subnet.
151
152 NIC_%d_NETWORK_GATEWAY6
153     (Optional) If a NIC network is specified, the network's IPv6
154     gateway.
155
156 NIC_%d_NETWORK_MAC_PREFIX
157     (Optional) If a NIC network is specified, the network's mac prefix.
158
159 NIC_%d_NETWORK_TAGS
160     (Optional) If a NIC network is specified, the network's tags, space
161     separated.
162
163 OSP_*name*
164     Each OS parameter (see below) will be exported in its own
165     variable, prefixed with ``OSP_``, and upper-cased. For example, a
166     ``dhcp`` parameter will be exported as ``OSP_DHCP``.
167
168 DEBUG_LEVEL
169     If non-zero, this should cause the OS script to generate verbose
170     logs of its execution, for troubleshooting purposes. Currently
171     only ``0`` and ``1`` are valid values.
172
173
174 EXECUTABLE SCRIPTS
175 ------------------
176
177
178 create
179 ~~~~~~
180
181 The **create** command is used for creating a new instance from
182 scratch. It has no additional environment variables bside the
183 common ones.
184
185 The ``INSTANCE_NAME`` variable denotes the name of the instance,
186 which is guaranteed to resolve to an IP address. The create script
187 should configure the instance according to this name. It can
188 configure the IP statically or not, depending on the deployment
189 environment.
190
191 The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
192 request is reinstalling an existing instance, rather than creating
193 one anew. This can be used, for example, to preserve some data in the
194 old instance in an OS-specific way.
195
196 export
197 ~~~~~~
198
199 This command is used in order to make a backup of a given disk of
200 the instance. The command should write to stdout a dump of the
201 given block device. The output of this program will be passed
202 during restore to the **import** command.
203
204 The specific disk to backup is denoted by two additional environment
205 variables: ``EXPORT_INDEX`` which denotes the index in the instance
206 disks structure (and could be used for example to skip the second disk
207 if not needed for backup) and ``EXPORT_DEVICE`` which has the same value
208 as ``DISK_N_PATH`` but is duplicated here for easier usage by shell
209 scripts (rather than parse the ``DISK_...`` variables).
210
211 To provide the user with an estimate on how long the export will take,
212 a predicted size can be written to the file descriptor passed in the
213 variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated
214 by a newline character (``\n``). Older versions of Ganeti don't
215 support this feature, hence the variable should be checked before
216 use. Example::
217
218     if test -n "$EXP_SIZE_FD"; then
219       blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
220     fi
221
222 import
223 ~~~~~~
224
225 The **import** command is used for restoring an instance from a
226 backup as done by **export**. The arguments are the similar to
227 those passed to **export**, whose output will be provided on
228 stdin.
229
230 The difference in variables is that the current disk is denoted by
231 ``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
232
233 rename
234 ~~~~~~
235
236 This command is used in order to perform a rename at the instance
237 OS level, after the instance has been renamed in Ganeti. The
238 command should do whatever steps are required to ensure that the
239 instance is updated to use the new name, if the operating system
240 supports it.
241
242 Note that it is acceptable for the rename script to do nothing at
243 all, however be warned that in this case, there will be a
244 desynchronization between what gnt-instance list shows you and the
245 actual hostname of the instance.
246
247 The script will be passed one additional environment variable
248 called ``OLD_INSTANCE_NAME`` which holds the old instance name. The
249 ``INSTANCE_NAME`` variable holds the new instance name.
250
251 A very simple rename script should at least change the hostname and
252 IP address of the instance, leaving the administrator to update the
253 other services.
254
255 verify
256 ~~~~~~
257
258 The *verify* script is used to verify consistency of the OS parameters
259 (see below). The command should take one or more arguments denoting
260 what checks should be performed, and return a proper exit code
261 depending on whether the validation failed or succeeded.
262
263 Currently (API version 20), only one parameter is supported:
264 ``parameters``. This should validate the ``OSP_`` variables from the
265 environment, and output diagnostic messages in case the validation
266 fails.
267
268 For the ``dhcp`` parameter given as example above, a verification
269 script could be:
270
271 .. code-block:: bash
272
273     #!/bin/sh
274
275     case $OSP_DHCP in
276       ""|yes|no)
277           ;;
278       *)
279         echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
280         exit 1;
281         ;;
282     esac
283
284     exit 0
285
286
287 TEXT FILES
288 ----------
289
290
291 ganeti_api_version
292 ~~~~~~~~~~~~~~~~~~
293
294 The ganeti_api_version file is a plain text file containing the
295 version(s) of the guest OS API that this OS definition complies
296 with, one per line. The version documented by this man page is 20,
297 so this file must contain the number 20 followed by a newline if
298 only this version is supported. A script compatible with more than
299 one Ganeti version should contain the most recent version first
300 (i.e. 20), followed by the old version(s) (in this case 15 and/or
301 10).
302
303 variants.list
304 ~~~~~~~~~~~~~
305
306 variants.list is a plain text file containing all the declared supported
307 variants for this OS, one per line. If this file is missing or empty,
308 then the OS won't be considered to support variants.
309
310 Empty lines and lines starting with a hash (``#``) are ignored.
311
312 parameters.list
313 ~~~~~~~~~~~~~~~
314
315 This file declares the parameters supported by the OS, one parameter
316 per line, with name and description (space and/or tab separated). For
317 example::
318
319     dhcp Whether to enable (yes) or disable (no) dhcp
320     root_size The size of the root partition, in GiB
321
322 The parameters can then be used in instance add or modification, as
323 follows::
324
325     # gnt-instance add -O dhcp=no,root_size=8 ...
326
327
328 NOTES
329 -----
330
331 Backwards compatibility
332 ~~~~~~~~~~~~~~~~~~~~~~~
333
334 Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
335 parameters and related scripts (verify) are only supported in
336 version 20. The variants functionality (variants.list, and OS_VARIANT
337 env. var) are supported/present only in version 15 and up.
338
339 Common behaviour
340 ~~~~~~~~~~~~~~~~
341
342 All the scripts should display an usage message when called with a
343 wrong number of arguments or when the first argument is ``-h`` or
344 ``--help``.
345
346 Upgrading from old versions
347 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
348
349 Version 15 to 20
350 ^^^^^^^^^^^^^^^^
351
352 The ``parameters.list`` file and ``verify`` script have been
353 added. For no parameters, an empty parameters file and an empty verify
354 script which returns success can be used.
355
356 Version 10 to 15
357 ^^^^^^^^^^^^^^^^
358
359 The ``variants.list`` file has been added, so OSes should support at
360 least one variant, declaring it in that file and must be prepared to
361 parse the OS_VARIANT environment variable. OSes are free to support more
362 variants than just the declared ones. Note that this file is optional;
363 without it, the variants functionality is disabled.
364
365 Version 5 to 10
366 ^^^^^^^^^^^^^^^
367
368 The method for passing data has changed from command line options
369 to environment variables, so scripts should be modified to use
370 these. For an example of how this can be done in a way compatible
371 with both versions, feel free to look at the debootstrap instance's
372 common.sh auxiliary script.
373
374 Also, instances can have now a variable number of disks, not only
375 two, and a variable number of NICs (instead of fixed one), so the
376 scripts should deal with this. The biggest change is in the
377 import/export, which are called once per disk, instead of once per
378 instance.
379
380 Version 4 to 5
381 ^^^^^^^^^^^^^^
382
383 The rename script has been added. If you don't want to do any
384 changes on the instances after a rename, you can migrate the OS
385 definition to version 5 by creating the rename script simply as:
386
387 .. code-block:: bash
388
389     #!/bin/sh
390
391     exit 0
392
393 Note that the script must be executable.
394
395 .. vim: set textwidth=72 :
396 .. Local Variables:
397 .. mode: rst
398 .. fill-column: 72
399 .. End: