DESCRIPTION
-----------
-The method of supporting guest operating systems in Ganeti is to
-have, for each guest OS type, a directory containing a number of
-required files.
+The method of supporting guest operating systems in Ganeti is to have,
+for each guest OS type, a directory containing a number of required
+files. This directory must be present across all nodes (Ganeti doesn't
+replicate it) in order for the OS to be usable by Ganeti.
+
REFERENCE
---------
-There are six required files: *create*, *import*, *export*, *rename*
-(executables), *ganeti_api_version* and *variants.list* (text files).
+There are eight required files: *create*, *import*, *export*, *rename*,
+*verify* (executables), *ganeti_api_version*, *variants.list* and
+*parameters.list* (text files).
Common environment
~~~~~~~~~~~~~~~~~~
of them might have extra ones. Note that all counts are
zero-based.
-
+Since Ganeti version 2.5, the environment will be cleaned up before
+being passed to scripts, therefore they will not inherit the environment
+in with which the ganeti node daemon was started. If you depend on any
+environment variables (non-Ganeti), then you will need to define or
+source them appropriately.
OS_API_VERSION
The OS API version that the rest of the environment conforms to.
instance.
NIC_%N_MODE
- The NIC mode, either routed or bridged
+ The NIC mode, routed, bridged or openvswitch
NIC_%N_BRIDGE
The bridge to which this NIC will be attached. This variable is
defined only when the NIC is in bridged mode.
NIC_%N_LINK
- If the NIC is in bridged mode, this is the same as
- ``NIC_%N_BRIDGE``. If it is in routed mode, the routing table
- which will be used by the hypervisor to insert the appropriate
- routes.
+ In bridged or openvswitch mode, this is the interface to which the
+ NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In
+ routed mode it is the routing table which will be used by the
+ hypervisor to insert the appropriate routes.
NIC_%N_FRONTEND_TYPE
(Optional) If applicable, the type of the exported NIC to the
instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
``ne2k_isa``, ``paravirtual``.
+NIC_%d_NETWORK_NAME
+ (Optional) If a NIC network is specified, the network's name.
+
+NIC_%d_NETWORK_UUID
+ (Optional) If a NIC network is specified, the network's uuid.
+
+NIC_%d_NETWORK_FAMILY
+ (Optional) If a NIC network is specified, the network's family.
+
+NIC_%d_NETWORK_SUBNET
+ (Optional) If a NIC network is specified, the network's IPv4 subnet.
+
+NIC_%d_NETWORK_GATEWAY
+ (Optional) If a NIC network is specified, the network's IPv4
+ gateway.
+
+NIC_%d_NETWORK_SUBNET6
+ (Optional) If a NIC network is specified, the network's IPv6 subnet.
+
+NIC_%d_NETWORK_GATEWAY6
+ (Optional) If a NIC network is specified, the network's IPv6
+ gateway.
+
+NIC_%d_NETWORK_MAC_PREFIX
+ (Optional) If a NIC network is specified, the network's mac prefix.
+
+NIC_%d_NETWORK_TAGS
+ (Optional) If a NIC network is specified, the network's tags, space
+ separated.
+
+OSP_*name*
+ Each OS parameter (see below) will be exported in its own
+ variable, prefixed with ``OSP_``, and upper-cased. For example, a
+ ``dhcp`` parameter will be exported as ``OSP_DHCP``.
+
DEBUG_LEVEL
If non-zero, this should cause the OS script to generate verbose
logs of its execution, for troubleshooting purposes. Currently
only ``0`` and ``1`` are valid values.
+EXECUTABLE SCRIPTS
+------------------
+
+
create
~~~~~~
environment.
The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
-request is reinstalling and existing instance, rather than creating
+request is reinstalling an existing instance, rather than creating
one anew. This can be used, for example, to preserve some data in the
old instance in an OS-specific way.
The specific disk to backup is denoted by two additional environment
variables: ``EXPORT_INDEX`` which denotes the index in the instance
disks structure (and could be used for example to skip the second disk
-if not needed for backup) and ``EXPORT_PATH`` which has the same value
-as ``DISK_N_PATH`` but is duplicate here for easier usage by shell
+if not needed for backup) and ``EXPORT_DEVICE`` which has the same value
+as ``DISK_N_PATH`` but is duplicated here for easier usage by shell
scripts (rather than parse the ``DISK_...`` variables).
To provide the user with an estimate on how long the export will take,
those passed to **export**, whose output will be provided on
stdin.
-The difference in variables is that the current disk is called by
+The difference in variables is that the current disk is denoted by
``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
rename
IP address of the instance, leaving the administrator to update the
other services.
+verify
+~~~~~~
+
+The *verify* script is used to verify consistency of the OS parameters
+(see below). The command should take one or more arguments denoting
+what checks should be performed, and return a proper exit code
+depending on whether the validation failed or succeeded.
+
+Currently (API version 20), only one parameter is supported:
+``parameters``. This should validate the ``OSP_`` variables from the
+environment, and output diagnostic messages in case the validation
+fails.
+
+For the ``dhcp`` parameter given as example above, a verification
+script could be:
+
+.. code-block:: bash
+
+ #!/bin/sh
+
+ case $OSP_DHCP in
+ ""|yes|no)
+ ;;
+ *)
+ echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
+ exit 1;
+ ;;
+ esac
+
+ exit 0
+
+
+TEXT FILES
+----------
+
+
ganeti_api_version
~~~~~~~~~~~~~~~~~~
The ganeti_api_version file is a plain text file containing the
version(s) of the guest OS API that this OS definition complies
-with, one per line. The version documented by this man page is 15,
-so this file must contain the number 15 followed by a newline if
+with, one per line. The version documented by this man page is 20,
+so this file must contain the number 20 followed by a newline if
only this version is supported. A script compatible with more than
one Ganeti version should contain the most recent version first
-(i.e. 15), followed by the old version(s) (in this case 10 and/or
-5).
+(i.e. 20), followed by the old version(s) (in this case 15 and/or
+10).
variants.list
~~~~~~~~~~~~~
-variants.list is a plain text file containing all the declared
-supported variants for this OS, one per line. At least one variant
-must be supported.
+variants.list is a plain text file containing all the declared supported
+variants for this OS, one per line. If this file is missing or empty,
+then the OS won't be considered to support variants.
+
+Empty lines and lines starting with a hash (``#``) are ignored.
+
+parameters.list
+~~~~~~~~~~~~~~~
+
+This file declares the parameters supported by the OS, one parameter
+per line, with name and description (space and/or tab separated). For
+example::
+
+ dhcp Whether to enable (yes) or disable (no) dhcp
+ root_size The size of the root partition, in GiB
+
+The parameters can then be used in instance add or modification, as
+follows::
+
+ # gnt-instance add -O dhcp=no,root_size=8 ...
+
NOTES
-----
Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~
-Ganeti 2.2 is compatible with both API version 10, and 15. In API
-version 10 the variants.list file is ignored and no OS_VARIANT
-environment variable is passed.
+Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
+parameters and related scripts (verify) are only supported in
+version 20. The variants functionality (variants.list, and OS_VARIANT
+env. var) are supported/present only in version 15 and up.
Common behaviour
~~~~~~~~~~~~~~~~
Upgrading from old versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Version 15 to 20
+^^^^^^^^^^^^^^^^
+
+The ``parameters.list`` file and ``verify`` script have been
+added. For no parameters, an empty parameters file and an empty verify
+script which returns success can be used.
+
Version 10 to 15
^^^^^^^^^^^^^^^^
The ``variants.list`` file has been added, so OSes should support at
least one variant, declaring it in that file and must be prepared to
-parse the OS_VARIANT environment variable. OSes are free to support
-more variants than just the declared ones.
+parse the OS_VARIANT environment variable. OSes are free to support more
+variants than just the declared ones. Note that this file is optional;
+without it, the variants functionality is disabled.
Version 5 to 10
^^^^^^^^^^^^^^^
The rename script has been added. If you don't want to do any
changes on the instances after a rename, you can migrate the OS
-definition to version 5 by creating the rename script simply as::
+definition to version 5 by creating the rename script simply as:
+
+.. code-block:: bash
#!/bin/sh
exit 0
Note that the script must be executable.
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End:
projects / ganeti-local / blobdiff