Statistics
| Branch: | Tag: | Revision:

root / man / ganeti-os-interface.rst @ 5a7cb9d3

History | View | Annotate | Download (11.4 kB)

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_FRONTEND_TYPE
80
    (Optional) If applicable to the current hypervisor type: the type
81
    of the device exported by the hypervisor. For example, the Xen HVM
82
    hypervisor can export disks as either ``paravirtual`` or
83
    ``ioemu``.
84

    
85
DISK_%N_BACKEND_TYPE
86
    How files are visible on the node side. This can be either
87
    ``block`` (when using block devices) or ``file:type``, where
88
    ``type`` is either ``loop`` or ``blktap`` depending on how the
89
    hypervisor will be configured.  Note that not all backend types
90
    apply to all hypervisors.
91

    
92
NIC_COUNT
93
    Similar to the ``DISK_COUNT``, this represents the number of NICs
94
    of the instance.
95

    
96
NIC_%N_MAC
97
    The MAC address associated with this interface.
98

    
99
NIC_%N_IP
100
    The IP address, if any, associated with the N-th NIC of the
101
    instance.
102

    
103
NIC_%N_MODE
104
    The NIC mode, either routed or bridged
105

    
106
NIC_%N_BRIDGE
107
    The bridge to which this NIC will be attached. This variable is
108
    defined only when the NIC is in bridged mode.
109

    
110
NIC_%N_LINK
111
    If the NIC is in bridged mode, this is the same as
112
    ``NIC_%N_BRIDGE``.  If it is in routed mode, the routing table
113
    which will be used by the hypervisor to insert the appropriate
114
    routes.
115

    
116
NIC_%N_FRONTEND_TYPE
117
    (Optional) If applicable, the type of the exported NIC to the
118
    instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
119
    ``ne2k_isa``, ``paravirtual``.
120

    
121
OSP_*name*
122
    Each OS parameter (see below) will be exported in its own
123
    variable, prefixed with ``OSP_``, and upper-cased. For example, a
124
    ``dhcp`` parameter will be exported as ``OSP_DHCP``.
125

    
126
DEBUG_LEVEL
127
    If non-zero, this should cause the OS script to generate verbose
128
    logs of its execution, for troubleshooting purposes. Currently
129
    only ``0`` and ``1`` are valid values.
130

    
131

    
132
EXECUTABLE SCRIPTS
133
------------------
134

    
135

    
136
create
137
~~~~~~
138

    
139
The **create** command is used for creating a new instance from
140
scratch. It has no additional environment variables bside the
141
common ones.
142

    
143
The ``INSTANCE_NAME`` variable denotes the name of the instance,
144
which is guaranteed to resolve to an IP address. The create script
145
should configure the instance according to this name. It can
146
configure the IP statically or not, depending on the deployment
147
environment.
148

    
149
The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
150
request is reinstalling an existing instance, rather than creating
151
one anew. This can be used, for example, to preserve some data in the
152
old instance in an OS-specific way.
153

    
154
export
155
~~~~~~
156

    
157
This command is used in order to make a backup of a given disk of
158
the instance. The command should write to stdout a dump of the
159
given block device. The output of this program will be passed
160
during restore to the **import** command.
161

    
162
The specific disk to backup is denoted by two additional environment
163
variables: ``EXPORT_INDEX`` which denotes the index in the instance
164
disks structure (and could be used for example to skip the second disk
165
if not needed for backup) and ``EXPORT_DEVICE`` which has the same value
166
as ``DISK_N_PATH`` but is duplicated here for easier usage by shell
167
scripts (rather than parse the ``DISK_...`` variables).
168

    
169
To provide the user with an estimate on how long the export will take,
170
a predicted size can be written to the file descriptor passed in the
171
variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated
172
by a newline character (``\n``). Older versions of Ganeti don't
173
support this feature, hence the variable should be checked before
174
use. Example::
175

    
176
    if test -n "$EXP_SIZE_FD"; then
177
      blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
178
    fi
179

    
180
import
181
~~~~~~
182

    
183
The **import** command is used for restoring an instance from a
184
backup as done by **export**. The arguments are the similar to
185
those passed to **export**, whose output will be provided on
186
stdin.
187

    
188
The difference in variables is that the current disk is denoted by
189
``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
190

    
191
rename
192
~~~~~~
193

    
194
This command is used in order to perform a rename at the instance
195
OS level, after the instance has been renamed in Ganeti. The
196
command should do whatever steps are required to ensure that the
197
instance is updated to use the new name, if the operating system
198
supports it.
199

    
200
Note that it is acceptable for the rename script to do nothing at
201
all, however be warned that in this case, there will be a
202
desynchronization between what gnt-instance list shows you and the
203
actual hostname of the instance.
204

    
205
The script will be passed one additional environment variable
206
called ``OLD_INSTANCE_NAME`` which holds the old instance name. The
207
``INSTANCE_NAME`` variable holds the new instance name.
208

    
209
A very simple rename script should at least change the hostname and
210
IP address of the instance, leaving the administrator to update the
211
other services.
212

    
213
verify
214
~~~~~~
215

    
216
The *verify* script is used to verify consistency of the OS parameters
217
(see below). The command should take one or more arguments denoting
218
what checks should be performed, and return a proper exit code
219
depending on whether the validation failed or succeeded.
220

    
221
Currently (API version 20), only one parameter is supported:
222
``parameters``. This should validate the ``OSP_`` variables from the
223
environment, and output diagnostic messages in case the validation
224
fails.
225

    
226
.. highlight:: sh
227

    
228
For the ``dhcp`` parameter given as example above, a verification
229
script could be::
230

    
231
    #!/bin/sh
232

    
233
    case $OSP_DHCP in
234
      ""|yes|no)
235
          ;;
236
      *)
237
        echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
238
        exit 1;
239
        ;;
240
    esac
241

    
242
    exit 0
243

    
244

    
245
TEXT FILES
246
----------
247

    
248

    
249
ganeti_api_version
250
~~~~~~~~~~~~~~~~~~
251

    
252
The ganeti_api_version file is a plain text file containing the
253
version(s) of the guest OS API that this OS definition complies
254
with, one per line. The version documented by this man page is 20,
255
so this file must contain the number 20 followed by a newline if
256
only this version is supported. A script compatible with more than
257
one Ganeti version should contain the most recent version first
258
(i.e. 20), followed by the old version(s) (in this case 15 and/or
259
10).
260

    
261
variants.list
262
~~~~~~~~~~~~~
263

    
264
variants.list is a plain text file containing all the declared supported
265
variants for this OS, one per line. If this file is missing or empty,
266
then the OS won't be considered to support variants.
267

    
268
Empty lines and lines starting with a hash (``#``) are ignored.
269

    
270
parameters.list
271
~~~~~~~~~~~~~~~
272

    
273
This file declares the parameters supported by the OS, one parameter
274
per line, with name and description (space and/or tab separated). For
275
example::
276

    
277
    dhcp Whether to enable (yes) or disable (no) dhcp
278
    root_size The size of the root partition, in GiB
279

    
280
The parameters can then be used in instance add or modification, as
281
follows::
282

    
283
    # gnt-instance add -O dhcp=no,root_size=8 ...
284

    
285

    
286
NOTES
287
-----
288

    
289
Backwards compatibility
290
~~~~~~~~~~~~~~~~~~~~~~~
291

    
292
Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
293
parameters and related scripts (verify) are only supported in
294
version 20. The variants functionality (variants.list, and OS_VARIANT
295
env. var) are supported/present only in version 15 and up.
296

    
297
Common behaviour
298
~~~~~~~~~~~~~~~~
299

    
300
All the scripts should display an usage message when called with a
301
wrong number of arguments or when the first argument is ``-h`` or
302
``--help``.
303

    
304
Upgrading from old versions
305
~~~~~~~~~~~~~~~~~~~~~~~~~~~
306

    
307
Version 15 to 20
308
^^^^^^^^^^^^^^^^
309

    
310
The ``parameters.list`` file and ``verify`` script have been
311
added. For no parameters, an empty parameters file and an empty verify
312
script which returns success can be used.
313

    
314
Version 10 to 15
315
^^^^^^^^^^^^^^^^
316

    
317
The ``variants.list`` file has been added, so OSes should support at
318
least one variant, declaring it in that file and must be prepared to
319
parse the OS_VARIANT environment variable. OSes are free to support more
320
variants than just the declared ones. Note that this file is optional;
321
without it, the variants functionality is disabled.
322

    
323
Version 5 to 10
324
^^^^^^^^^^^^^^^
325

    
326
The method for passing data has changed from command line options
327
to environment variables, so scripts should be modified to use
328
these. For an example of how this can be done in a way compatible
329
with both versions, feel free to look at the debootstrap instance's
330
common.sh auxiliary script.
331

    
332
Also, instances can have now a variable number of disks, not only
333
two, and a variable number of NICs (instead of fixed one), so the
334
scripts should deal with this. The biggest change is in the
335
import/export, which are called once per disk, instead of once per
336
instance.
337

    
338
Version 4 to 5
339
^^^^^^^^^^^^^^
340

    
341
The rename script has been added. If you don't want to do any
342
changes on the instances after a rename, you can migrate the OS
343
definition to version 5 by creating the rename script simply as::
344

    
345
    #!/bin/sh
346

    
347
    exit 0
348

    
349
Note that the script must be executable.
350

    
351
.. vim: set textwidth=72 :
352
.. Local Variables:
353
.. mode: rst
354
.. fill-column: 72
355
.. End: