README

   1 ganeti-instance-debootstrap
   2 ===========================
   3
   4 This is a guest OS definition for Ganeti (http://code.google.com/p/ganeti).
   5 It will install a minimal version of Debian or Ubuntu via debootstrap (thus it
   6 requires network access). This only works if you have a Debian-based node or
   7 you have debootstrap installed by hand on another distribution.
   8
   9 Installation
  10 ------------
  11
  12 In order to install this package from source, you need to determine what
  13 options ganeti itself has been configured with. If ganeti was built
  14 directly from source, then the only place it looks for OS definitions is
  15 ``/srv/ganeti/os``, and you need to install the OS under it::
  16
  17   ./configure --prefix=/usr --localstatedir=/var \
  18     --sysconfdir=/etc \
  19     --with-os-dir=/srv/ganeti/os
  20   make && make install
  21
  22 If ganeti was installed from a package, its default OS path should
  23 already include /usr/share/ganeti/os, so you can just run::
  24
  25   ./configure -prefix=/usr --localstatedir=/var \
  26     --sysconfdir=/etc
  27   make && make install
  28
  29 Note that you need to repeat this procedure on all nodes of the cluster.
  30
  31 The actual path that ganeti has been installed with can be determined by
  32 looking for a file named _autoconf.py under a ganeti directory in the
  33 python modules tree (e.g.
  34 ``/usr/lib/python2.4/site-packages/ganeti/_autoconf.py``). In this file,
  35 a variable named OS_SEARCH_PATH will list all the directories in which
  36 ganeti will look for OS definitions.
  37
  38 Configuration of instance creation
  39 ----------------------------------
  40
  41 Note: the minimum disk size accepted is 256MB, as ``debootstrap``
  42 requires disk space both for downloading the packages and installing
  43 them.
  44
  45 The kind of instance created can be customized via a settings file. This
  46 file is not installed by default, as the instance creation will work
  47 without it. The creation scripts will look for it in
  48 ``$sysconfdir/default/ganeti-instance-debootstrap``, so if you have run
  49 configure with the parameter ``--sysconfdir=/etc``, the final filename
  50 will be ``/etc/default/ganeti-instance-debootstrap``.
  51
  52 The following settings will be examined in this file (see also the file
  53 named 'defaults' in the source distribution for more details):
  54
  55 - PROXY: http proxy to use for non-cached installs
  56 - MIRROR: the mirror to use if not the default one
  57 - ARCH: either i386 or amd64, otherwise your current architecture will
  58   be used
  59 - SUITE: the actual OS to be installed; the current default is Debian
  60   *wheezy*, and you can choose any of the OSes supported deboostrap (on
  61   Debian, look into /usr/share/deboostrap/scripts)
  62 - EXTRAPKGS: most OSes will need some extra packages installed to make
  63   them work nicely under Xen; the example file containts a few
  64   suggestions
  65 - COMPONENTS: if defined, overrides the default debootstrap components
  66   ("main"); this can be helpful e.g. by using "main,contrib,nonfree" for
  67   Debian, or "main,universe" for Ubuntu
  68 - CUSTOMIZE_DIR: a directory containing customization script for the
  69   instance.  (by default $sysconfdir/ganeti/instance-debootstrap/hooks)
  70   See "Customization of the instance" below.
  71 - GENERATE_CACHE: if 'yes' (the default), the installation process will
  72   save and reuse a cache file to speed reinstalls (located under
  73   $localstatedir/cache/ganeti-instance-debootstrap)
  74 - CLEAN_CACHE: if empty, the cached files will never be cleaned and thus
  75   the installation will definitely need to be updated after install;
  76   otherwise, the value of this variable will be taken as the number of
  77   days after which to remove the cache file; the default is 14 (two
  78   weeks)
  79 - PARTITION_STYLE: if 'none' the device will be formatted directly, if 'msdos'
  80   a partition table will be installed on it. You need to have kpartx installed
  81   to use the 'msdos' option. The default is 'msdos' from Ganeti 2.0 onwards,
  82   but still 'none' if installing under Ganeti 1.2
  83
  84 Note that the settings file is important on the node that the instance
  85 is installed on, not the cluster master. This is indeed not a very good
  86 model of using this OS but currently the OS interface in ganeti is
  87 limiting.
  88
  89 Creating OS variants
  90 --------------------
  91
  92 Every Ganeti OS supports variants, so it's possible to define custom OS
  93 variants with instance-debootstrap as well. First, an additional variant has
  94 to be defined in ``$osdir/debootstrap/variants.list`` (with ``$osdir`` being
  95 ``/usr/share/ganeti/os`` by default). Secondly, you can configure this
  96 instance variant in
  97 ``$sysconfdir/ganeti/instance-debootstrap/variants/$variant.conf``, overriding
  98 the settings mentioned in the previous section.
  99
 100 To use the newly created instance variant, specify it in ``gnt-instance`` like
 101 this::
 102
 103   gnt-instance add -o debootstrap+precise ...
 104
 105 Example
 106 +++++++
 107
 108 To create a Ubuntu 12.04 (precise) instance variant, add the following to
 109 ``$osdir/debootstrap/variants.list``::
 110
 111   precise
 112
 113 Now create the file
 114 ``$sysconfdir/ganeti/instance-debootstrap/variants/precise.conf`` with the
 115 following content::
 116
 117   MIRROR="http://archive.ubuntu.com/ubuntu/"
 118   SUITE="precise"
 119   COMPONENTS="main,universe"
 120   ARCH="amd64"
 121
 122 You can create Ubuntu 12.04 instances as follows::
 123
 124   gnt-instance add -t plain -o debootstrap+precise --disk 0:size=10000m -n node1.example.com instance1.example.com
 125
 126 For this to work, make sure that you have the appropriate debootstrap script
 127 for precise (or just create a symlink called ``precise`` to ``gutsy`` in
 128 ``/usr/share/debootstrap/scripts``).
 129
 130 Instance creation parameters
 131 ----------------------------
 132
 133 Some aspects of the created instance can be conrolled via parameters at
 134 instance creation time with the ``-O`` parameter of ``gnt-instance``.
 135
 136 The supported parameters are:
 137
 138 - filesystem: the filesystem type to use for the root partition. This  has to
 139   be a filesystem type supported by ``mke2fs``. The default is 'ext4'.
 140
 141 Customization of the instance
 142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 143
 144 If run-parts is in the os create script, and the CUSTOMIZE_DIR (by
 145 default $sysconfdir/ganeti/instance-debootstrap/hooks,
 146 /etc/ganeti/instance-debootstrap/hooks if you configured the os with
 147 --sysconfdir=/etc) directory exists any executable whose name matches
 148 the run-parts execution rules (quoting run-parts(8): the names must
 149 consist entirely of upper and lower case letters, digits, underscores,
 150 and hyphens) is executed to allow further personalization of the
 151 installation. The following environment variables are passed, in
 152 addition to the ones ganeti passes to the OS scripts:
 153
 154 TARGET: directory in which the filesystem is mounted
 155 SUITE: suite installed by debootstrap (eg: wheezy)
 156 ARCH: target architecture
 157 PARTITION_STYLE: style of the disk partitioning (see above)
 158 EXTRA_PKGS: extra packages installed by debootstrap
 159 BLOCKDEV: ganeti block device
 160 FSYSDEV: device in which the filesystem resides (the one mounted in TARGET)
 161
 162 The scripts in CUSTOMIZE_DIR can exit with an error code to signal an error in
 163 the instance creation, should they fail.
 164
 165 The scripts in CUSTOMIZE_DIR should not start any long-term processes or
 166 daemons using this directory, otherwise the installation will fail because it
 167 won't be able to umount the filesystem from the directory, and hand the
 168 instance back to Ganeti.
 169
 170 Example
 171 +++++++
 172
 173 The root password can be automatically set when the instance is created. In
 174 order to do this, the ``examples/hooks/defaultpasswords`` file has to be copied
 175 to ``$sysconfdir/ganeti/instance-debootstrap/hooks/``, and its data file
 176 ``examples/hooks/confdata/defaultpasswords`` has to be copied to
 177 ``$sysconfdir/ganeti/instance-debootstrap/hooks/confdata/`` and modified
 178 accordingly to one's own need. The file syntax is such that each line represent
 179 a user, with the format::
 180
 181   username:password
 182
 183 After copying the two files, just running the instance creation as usual will
 184 automatically cause their execution.
 185
 186 Caching
 187 ~~~~~~~
 188
 189 As described above, the install process uses a cache file in order to
 190 speed up repeated installs. If you only rarely do installs, this will
 191 not matter to you, but if you want to install 10 instances in a row, the
 192 difference will be visible.
 193
 194 The default settings are to generate a cache, and to clean it up after
 195 two weeks.
 196
 197 Note that the cache will use one file per architecture per suite, so if
 198 you install multiple suites there might be a non-trivial amount of space
 199 used in the cache directory. It is safe to remove manually the files.
 200
 201 It is also possible, if done with care, to modify and regenerate the
 202 cache file (which is simply a tar archive) in order to preseed your
 203 installs with site-specific customizations.
 204
 205 Instance notes
 206 --------------
 207
 208 The instance is a minimal install:
 209
 210  - it has no password for root; simply login at the console
 211  - it has no network interfaces defined (besides lo); add your own
 212    definitions to /etc/network/interfaces
 213  - after configuring the network, it is recommended to run ``apt-get
 214    update`` so that signatures for the release files are picked up
 215
 216 .. vim: set textwidth=72 :
 217 .. Local Variables:
 218 .. mode: rst
 219 .. fill-column: 72
 220 .. End: