REFERENCE
---------
-There are six required files: *create*, *import*, *export*, *rename*,
+There are eight required files: *create*, *import*, *export*, *rename*,
*verify* (executables), *ganeti_api_version*, *variants.list* and
*parameters.list* (text files).
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.
The hypervisor of this instance.
DISK_COUNT
- The number of disks the instance has. The actual disk defitions are
+ The number of disks the instance has. The actual disk definitions are
in a set of additional variables. The instance's disk will be
numbered from 0 to this value minus one.
This is how the hypervisor will export the instance disks: either
read-write (``rw``) or read-only (``ro``).
+DISK_%N_UUID
+ The uuid associated with the N-th disk of the instance.
+
+DISK_%N_NAME
+ (Optional) The name, if any, associated with the N-th disk of the instance.
+
DISK_%N_FRONTEND_TYPE
(Optional) If applicable to the current hypervisor type: the type
of the device exported by the hypervisor. For example, the Xen HVM
NIC_%N_MAC
The MAC address associated with this interface.
+NIC_%N_UUID
+ The uuid associated with the N-th NIC of the instance.
+
+NIC_%N_NAME
+ (Optional) The name, if any, associated with the N-th NIC of the instance.
+
NIC_%N_IP
The IP address, if any, associated with the N-th NIC of the
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
+ variable, prefixed with ``OSP_``, and upper-cased. For example, a
``dhcp`` parameter will be exported as ``OSP_DHCP``.
DEBUG_LEVEL
environment.
The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
-request is reinstalling and existing instance, rather than creating
-one anew. This can be used, for example, to preserve some data in the
+request is reinstalling an existing instance, rather than creating
+a new one. This can be used, for example, to preserve some data in the
old instance in an OS-specific way.
export
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
Currently (API version 20), only one parameter is supported:
``parameters``. This should validate the ``OSP_`` variables from the
-environment, and output diagnostic message in case the validation
+environment, and output diagnostic messages in case the validation
fails.
-.. highlight:: sh
-
For the ``dhcp`` parameter given as example above, a verification
-script could be::
+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;
- ;;
+ ""|yes|no)
+ ;;
+ *)
+ echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
+ exit 1;
+ ;;
esac
exit 0
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
~~~~~~~~~~~~~~~
Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~
-Ganeti 2.3 and up is compatible with API version 10, 15 and 20. The OS
+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.
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