configuration.rst 9.14 KB
Newer Older
1 2 3
Configuration
=============

4
The user may configure the behavior of *snf-image* by uncommenting and
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41
overwriting the default value for some configuration parameters and the path of
some external programs in ``/etc/default/snf-image``:

.. code-block:: console

  # snf-image defaults file

  # IMAGE_DIR: directory location for disk images
  # IMAGE_DIR="/var/lib/snf-image"

  # IMAGE_DEBUG: turn on debugging output for the scripts
  # IMAGE_DEBUG=no

  # VERSION_CHECK: Check if snf-image and snf-image-helper have the same version.
  # This is useful if snf-image is installed as Debian package and not from
  # source.
  # VERSION_CHECK="yes"

  # HELPER_DIR: Directory hosting the helper files
  # HELPER_DIR="/var/lib/snf-image/helper/"

  # HELPER_TIMEOUT: Soft and hard timeout limits for helper instance. The helper
  # instance will be terminated after a given time if it hasn't exited by itself.
  # A TERM signal will be send if the instance is running after a
  # HELPER_SOFT_TIMEOUT interval. A KILL signal will be sent, if the instance is
  # still running after a HELPER_HARD_TIMEOUT interval since the initial signal
  # was sent. The timeout values are integer numbers with an optional suffix: `s'
  # for seconds (the default), `m' for minutes, `h' for hours or `d' for days.
  # HELPER_SOFT_TIMEOUT="120"
  # HELPER_HARD_TIMEOUT="5"

  # HELPER_USER: For security reasons, it is recommended that the helper VM
  # runs as an unprivileged user. KVM drops root privileges and runs as
  # HELPER_USER immediately before starting execution of the helper VM.
  # HELPER_USER="nobody"

  # HELPER_MEMORY: Virtual RAM size in megabytes to be given to the helper VM.
42
  # HELPER_MEMORY="512"
43

44 45 46 47 48 49 50 51 52 53 54 55 56 57
  # HELPER_DEBUG: When enabled, the helper VM will drop to a root shell
  # whenever a task fails. This allows the administrator or a developer
  # to examine its internal state for debugging purposes.
  # To access the shell, use a program like 'minicom' to connect to /dev/pts/X on
  # the host, where /dev/pts/X is the name of the device reported in the Ganeti
  # OS installation logs for helper's 3rd serial port, e.g.,
  # "char device redirected to /dev/pts/9 (label serial3)".
  # This feature is KVM-specific for the time being.
  # For HELPER_DEBUG to be useful, you also need to set HELPER_SOFT_TIMEOUT
  # to a much higher value.
  # WARNING: DO NOT ENABLE THIS FEATURE IN PRODUCTION. Every failure to deploy
  # an Image will cause the helper VM to hang.
  # HELPER_DEBUG="no"

58 59 60 61 62 63 64 65 66
  # MULTISTRAP_CONFIG: Configuration file to be used with multistrap to create
  # the rootfs of the helper image.
  # MULTISTRAP_CONFIG="/etc/snf-image/multistrap.conf"

  # MULTISTRAP_APTPREFDIR: Directory where APT preference files are hosted. Those
  # files will be injected to the helper image before multistrap is called.
  # MULTISTRAP_APTPREFDIR="/etc/snf-image/apt.pref.d"

  # XEN_SCRIPTS_DIR: Directory where the Xen scripts are stored
67
  # XEN_SCRIPTS_DIR="/etc/xen/scripts"
68

69 70 71 72 73 74
  # XEN_CMD: This variable specifies the Xen CLI tool snf-image should use. This
  # depends on the XEN version and configuration and should probably coincide
  # with the Ganeti's xen_cmd hypervisor parameter for xen-hvm or xen-pvm. Right
  # now the supported ones are 'xm' and 'xl'.
  # XEN_CMD="xl"

75 76 77
  # PITHOS_DB: Pithos database in SQLAlchemy format
  # PITHOS_DB="sqlite://///var/lib/pithos/backend.db"

Chrysostomos Nanakos's avatar
Chrysostomos Nanakos committed
78 79 80
  # PITHOS_BACKEND_STORAGE: Select Pithos backend storage. Possible values are
  # 'nfs' and 'rados'. According to the value you select, you need to set the
  # corresponding variables that follow.
81 82
  # If you select 'nfs' that's 'PITHOS_DATA'. If you select 'rados' then you need
  # to set all the "*_RADOS_*" ones.
Chrysostomos Nanakos's avatar
Chrysostomos Nanakos committed
83 84
  # PITHOS_BACKEND_STORAGE="nfs"

85 86 87
  # PITHOS_DATA: Directory where Pithos data are hosted
  # PITHOS_DATA="//var/lib/pithos/data"

Chrysostomos Nanakos's avatar
Chrysostomos Nanakos committed
88
  # PITHOS_RADOS_CEPH_CONF: RADOS configuration file
89
  # PITHOS_RADOS_CEPH_CONF="/etc/ceph/ceph.conf"
Chrysostomos Nanakos's avatar
Chrysostomos Nanakos committed
90 91 92 93 94 95 96

  # PITHOS_RADOS_POOL_MAPS: RADOS pool for storing Pithos maps
  # PITHOS_RADOS_POOL_MAPS="maps"

  # PITHOS_RADOS_POOL_BLOCKS: RADOS pool for storing Pithos blocks
  # PITHOS_RADOS_POOL_BLOCKS="blocks"

97 98 99
  # PITHOS_ARCHIPELAGO_CONF: Archipelago configuration file
  # PITHOS_ARCHIPELAGO_CONF="/etc/archipelago/archipelago.conf"

100 101 102 103
  # PITHCAT_UMASK: If set, it will change the file mode mask of the pithcat
  # process to the specified one.
  # PITHCAT_UMASK=<not set>

104 105 106
  # PROGRESS_MONITOR: External program that monitors the progress of the image
  # deployment. The snf-image monitor messages will be redirected to the standard
  # input of this program.
107 108
  # PROGRESS_MONITOR=""

109
  # DHCP_TAGS: Space separated list of Ganeti network tags. snf-image will
110 111 112 113
  # configure a VM's NIC to use DHCP if the card is expected to have an IPv4
  # address and any of those tags is present in the card's NETWORK_TAGS variable.
  # DHCP_TAGS="auto dhcp nfdhcpd"

114
  # STATEFUL_DHCPV6_TAGS: Space separated list of Ganeti network tags. snf-image
115 116 117 118 119
  # will configure a VM's NIC to use DHCPv6 if the card is expected to have an
  # IPv6 address and any of those tags is present in the card's NETWORK_TAGS
  # variable.
  # STATEFUL_DHCPV6_TAGS="dhcpv6 stateful_dhcpv6"

120
  # STATELESS_DHCPV6_TAGS: Space separated list of Ganeti network tags. snf-image
121 122 123
  # will configure a VM's NIC to perform SLAAC and Stateless DHCPv6 if the card
  # is expected to have an IPv6 address and any of those tags is present in the
  # card's NETWORK_TAGS variable.
124
  # STATELESS_DHCPV6_TAGS="nfdhcpd stateless_dhcpv6"
125

126 127 128 129 130 131 132 133 134 135 136 137 138 139
  # DEFAULT_NIC_CONFIG: This option defines the network configuration to be
  # performed if there is a default NIC attached to the instance with no further
  # information associated with it. This will happen if the user creates an
  # instance and does not define any of the --net and --no-nics input arguments.
  # In this case Ganeti will create a NIC with a random MAC and set up according
  # to the cluster level NIC parameters. The user may want to leave this NIC
  # unconfigured (by leaving this option empty), perform "dhcp" or use one of the
  # various IPv6 auto configuration methods. The supported IPv6 methods are:
  # "dhcpv6" (Stateful DHCPv6), "slaac_dhcp" (Stateless DHCPv6) and "slaac"
  # (Stateless Autoconfiguration). IPv4 and IPv6 configuration methods can be
  # defined in conjunction using the plus (`+') sign. IPv4 must precede (e.g.:
  # "dhcp+slaac_dhcp").
  # DEFAULT_NIC_CONFIG="dhcp"

140
  # UNATTEND: This variable overwrites the unattend.xml file used when deploying
141
  # a Windows image. snf-image-helper will use its own unattend.xml file if this
142 143 144 145
  # variable is empty.
  # WARNING: This variable is DEPRECATED. If you need to define an answer file
  # different that the one shipped with snf-image, which is very likely, put it
  # inside the image or use the os_answer_file OS parameter.
146 147
  # UNATTEND=""

148 149 150 151 152 153 154 155
  # WINDOWS_TIMEZONE: This variable is used to specify the time zone when
  # deploying a Windows image. This will only work if you are using snf-image's
  # default OS answer file. If the Windows image already contains an answer file
  # or the os_answer_file OS parameter is used to define one, this variable will
  # be completely ignored. For a list of available time zones, check here:
  # https://msdn.microsoft.com/en-us/library/ms912391%28v=winembedded.11%29.aspx
  # WINDOWS_TIMEZONE="GMT Standard Time"

156 157
  # Paths for needed programs. Uncomment and change the variables below if you
  # don't want to use the default one.
158
  # MD5SUM="md5sum"
159
  # KVM="kvm"
160 161 162 163 164 165 166 167
  # LOSETUP="losetup"
  # KPARTX="kpartx"
  # SFDISK="sfdisk"
  # INSTALL_MBR="install-mbr"
  # TIMEOUT="timeout"
  # CURL="curl"
  # TAR="tar"

168 169
.. _configuration-parameters:

170 171 172 173 174 175 176 177
Configuration parameters
^^^^^^^^^^^^^^^^^^^^^^^^

The most common configuration parameters the user may need to overwrite are:

 * **IMAGE_DIR**: To specify the directory where the local images are hosted
 * **HELPER_SOFT_TIMEOUT**: To increase the allowed deployment time
 * **PITHOS_DB**: To specify the Pithos database and credentials, in case the
178 179 180
   user is accessing Pithos-hosted images
 * **PITHOS_DATA**: To specify the directory where the Pithos data blocks are
   hosted, in case the user is accessing Pithos-hosted images
181
 * **PROGRESS_MONITOR**: To specify an executable that will handle the
182
   monitoring messages exported by *snf-image*
183
 * **DHCP_TAGS**: To specify which Ganeti networks support DHCP
184 185 186
 * **DEFAULT_NIC_CONFIG**: To specify a configuration method for the default
   NIC Ganeti will attach on instances that were created without using the
   *--net* or *--no-nics* input arguments.
187
 * **STATELESS_DHCPV6_TAGS**: To specify which Ganeti networks support SLAAC
188
   and stateless DHCPv6
189
 * **STATEFUL_DHCPV6_TAGS**: To specify which Ganeti networks support DHCPv6
190 191 192
 * **WINDOWS_TIMEZONE**: To specify a time zone to use when deploying Windows
   images that do not host an Unattend.xml file and depend on the one provided
   by *snf-image*.
193 194 195 196 197

Paths of external programs
^^^^^^^^^^^^^^^^^^^^^^^^^^

In ``/etc/default/snf-image`` the user may also overwrite the path of some
198 199 200 201
external programs *snf-image* uses, or add default options to them. For
example, if the user wants to access network based images via insecure SSL
connections, he/she will need to overwrite the value of the *CURL* variable
like this: ``CURL="curl -k"``
202