Statistics
| Branch: | Tag: | Revision:

root / man / ganeti-os-interface.rst @ d1e9c98d

History | View | Annotate | Download (10.8 kB)

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