X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/4db3647e4424135de3a8f39517ec9de20852580c..802ed2aa856d2cee888f8972e5ac7e865f1d936c:/man/ganeti-os-interface.rst diff --git a/man/ganeti-os-interface.rst b/man/ganeti-os-interface.rst index 082f37e..ec8ec86 100644 --- a/man/ganeti-os-interface.rst +++ b/man/ganeti-os-interface.rst @@ -9,15 +9,18 @@ ganeti-os-interface - Specifications for guest OS types 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 ~~~~~~~~~~~~~~~~~~ @@ -27,7 +30,11 @@ common set of variables will be exported for all commands, and some 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. @@ -94,29 +101,68 @@ NIC_%N_IP 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 ~~~~~~ @@ -131,7 +177,7 @@ configure the IP statically or not, depending on the deployment 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. @@ -146,8 +192,8 @@ during restore to the **import** command. 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, @@ -169,7 +215,7 @@ backup as done by **export**. The arguments are the similar to 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 @@ -194,24 +240,78 @@ A very simple rename script should at least change the hostname and 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 ----- @@ -219,9 +319,10 @@ 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 ~~~~~~~~~~~~~~~~ @@ -233,13 +334,21 @@ wrong number of arguments or when the first argument is ``-h`` or 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 ^^^^^^^^^^^^^^^ @@ -261,10 +370,18 @@ Version 4 to 5 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: