Merge branch 'stable-2.16' into stable-2.17
[ganeti-github.git] / INSTALL
1 Ganeti quick installation guide
2 ===============================
3
4 Please note that a more detailed installation procedure is described in
5 the :doc:`install`. Refer to it if you are setting up Ganeti the first time.
6 This quick installation guide is mainly meant as reference for experienced
7 users. A glossary of terms can be found in the :doc:`glossary`.
8
9
10 Software Requirements
11 ---------------------
12
13 .. highlight:: shell-example
14
15 Before installing, please verify that you have the following programs:
16
17 - `Xen Hypervisor <http://www.xen.org/>`_, version 3.0 or above, if
18   running on Xen
19 - `KVM Hypervisor <http://www.linux-kvm.org>`_, version 72 or above, if
20   running on KVM. In order to use advanced features, such as live
21   migration, virtio, etc, an even newer version is recommended (qemu-kvm
22   versions 0.11.X and above have shown good behavior).
23 - `DRBD <http://www.drbd.org/>`_, kernel module and userspace utils,
24   version 8.0.7 or above, up to 8.4.x.
25 - `RBD <http://ceph.newdream.net/>`_, kernel modules
26   (``rbd.ko``/``libceph.ko``) and userspace utils (``ceph-common``)
27 - `LVM2 <http://sourceware.org/lvm2/>`_
28 - `OpenSSH <http://www.openssh.com/portable.html>`_
29 - `bridge utilities <http://www.linuxfoundation.org/en/Net:Bridge>`_
30 - `iproute2 <http://www.linuxfoundation.org/en/Net:Iproute2>`_
31 - `arping <http://www.skbuff.net/iputils/>`_ (part of iputils)
32 - `ndisc6 <http://www.remlab.net/ndisc6/>`_ (if using IPv6)
33 - `Python <http://www.python.org/>`_, version 2.6 or above, not 3.0
34 - `Python OpenSSL bindings <http://pyopenssl.sourceforge.net/>`_
35 - `simplejson Python module <http://code.google.com/p/simplejson/>`_
36 - `pyparsing Python module <http://pyparsing.wikispaces.com/>`_, version
37   1.4.6 or above
38 - `pyinotify Python module <https://github.com/seb-m/pyinotify>`_
39 - `PycURL Python module <http://pycurl.sourceforge.net/>`_
40 - `socat <http://www.dest-unreach.org/socat/>`_, see :ref:`note
41   <socat-note>` below
42 - `Paramiko <http://www.lag.net/paramiko/>`_, if you want to use
43   ``ganeti-listrunner``
44 - `psutil Python module <https://github.com/giampaolo/psutil>`_,
45   optional python package for supporting CPU pinning under KVM, versions
46   2.x.x only; beware that versions from 2.0.0 to before 2.2.0 had a
47   number of file handle leaks, so running at least 2.2.0 is advised
48 - `fdsend Python module <https://gitorious.org/python-fdsend>`_,
49   optional Python package for supporting NIC hotplugging under KVM
50 - `qemu-img <http://qemu.org/>`_, if you want to use ``ovfconverter``
51 - `fping <http://fping.sourceforge.net/>`_
52 - `Python IP address manipulation library
53   <http://code.google.com/p/ipaddr-py/>`_
54 - `Bitarray Python library <http://pypi.python.org/pypi/bitarray/>`_
55 - `GNU Make <http://www.gnu.org/software/make/>`_
56 - `GNU M4 <http://www.gnu.org/software/m4/>`_
57
58 These programs are supplied as part of most Linux distributions, so
59 usually they can be installed via the standard package manager. Also
60 many of them will already be installed on a standard machine. On
61 Debian/Ubuntu, you can use this command line to install all required
62 packages, except for RBD, DRBD and Xen::
63
64   $ apt-get install lvm2 ssh bridge-utils iproute iputils-arping make m4 \
65                     ndisc6 python python-openssl openssl \
66                     python-pyparsing python-simplejson python-bitarray \
67                     python-pyinotify python-pycurl python-ipaddr socat fping
68
69 Note that the previous instructions don't install optional packages.
70 To install the optional package, run the following line.::
71
72   $ apt-get install python-paramiko python-psutil qemu-utils
73
74 If some of the python packages are not available in your system,
75 you can try installing them using ``easy_install`` command.
76 For example::
77
78   $ apt-get install python-setuptools python-dev
79   $ cd / && easy_install \
80             psutil \
81             bitarray \
82             ipaddr
83
84
85 On Fedora to install all required packages except RBD, DRBD and Xen::
86
87   $ yum install openssh openssh-clients bridge-utils iproute ndisc6 make \
88                 pyOpenSSL pyparsing python-simplejson python-inotify \
89                 python-lxm socat fping python-bitarray python-ipaddr
90
91 For optional packages use the command::
92
93   $ yum install python-paramiko python-psutil qemu-img
94
95 If you want to build from source, please see doc/devnotes.rst for more
96 dependencies.
97
98 .. _socat-note:
99 .. note::
100   Ganeti's import/export functionality uses ``socat`` with OpenSSL for
101   transferring data between nodes. By default, OpenSSL 0.9.8 and above
102   employ transparent compression of all data using zlib if supported by
103   both sides of a connection. In cases where a lot of data is
104   transferred, this can lead to an increased CPU usage. Additionally,
105   Ganeti already compresses all data using ``gzip`` where it makes sense
106   (for inter-cluster instance moves).
107
108   To remedey this situation, patches implementing a new ``socat`` option
109   for disabling OpenSSL compression have been contributed and will
110   likely be included in the next feature release. Until then, users or
111   distributions need to apply the patches on their own.
112
113   Ganeti will use the option if it's detected by the ``configure``
114   script; auto-detection can be disabled by explicitly passing
115   ``--enable-socat-compress`` (use the option to disable compression) or
116   ``--disable-socat-compress`` (don't use the option).
117
118   The patches and more information can be found on
119   http://www.dest-unreach.org/socat/contrib/socat-opensslcompress.html.
120
121 Haskell requirements
122 ~~~~~~~~~~~~~~~~~~~~
123
124 Starting with Ganeti 2.7, the Haskell GHC compiler and a few base
125 libraries are required in order to build Ganeti (but not to run and
126 deploy Ganeti on production machines). More specifically:
127
128 - `GHC <http://www.haskell.org/ghc/>`_ version 7 or higher
129 - or even better, `The Haskell Platform
130   <http://hackage.haskell.org/platform/>`_ which gives you a simple way
131   to bootstrap Haskell
132 - `cabal-install <http://hackage.haskell.org/package/json>`_ and
133   `Cabal <http://hackage.haskell.org/package/json>`_, the Common Architecture
134   for Building Haskell Applications and Libraries (executable and library)
135 - `json <http://hackage.haskell.org/package/json>`_, a JSON library
136 - `network <http://hackage.haskell.org/package/network>`_, a basic
137   network library
138 - `parallel <http://hackage.haskell.org/package/parallel>`_, a parallel
139   programming library (note: tested with up to version 3.x)
140 - `bytestring <http://hackage.haskell.org/package/bytestring>`_ and
141   `utf8-string <http://hackage.haskell.org/package/utf8-string>`_
142   libraries; these usually come with the GHC compiler
143 - `text <http://hackage.haskell.org/package/text>`_
144 - `deepseq <http://hackage.haskell.org/package/deepseq>`_,
145   usually comes with the GHC compiler
146 - `curl <http://hackage.haskell.org/package/curl>`_, tested with
147   versions 1.3.4 and above
148 - `hslogger <http://software.complete.org/hslogger>`_, version 1.1 and
149   above.
150 - `hinotify <http://hackage.haskell.org/package/hinotify>`_, tested with
151   version 0.3.2
152 - `Crypto <http://hackage.haskell.org/package/Crypto>`_, tested with
153   version 4.2.4
154 - `regex-pcre <http://hackage.haskell.org/package/regex-pcre>`_,
155   bindings for the ``pcre`` library
156 - `attoparsec <http://hackage.haskell.org/package/attoparsec>`_,
157   version 0.10 and above
158 - `vector <http://hackage.haskell.org/package/vector>`_
159 - `process <http://hackage.haskell.org/package/process>`_, version 1.0.1.1 and
160   above; usually comes with the GHC compiler
161 - `base64-bytestring
162   <http://hackage.haskell.org/package/base64-bytestring>`_,
163   version 1.0.0.0 and above
164 - `lifted-base <http://hackage.haskell.org/package/lifted-base>`_,
165   version 0.1.1 and above.
166 - `lens <http://hackage.haskell.org/package/lens>`_,
167   version 3.10 and above.
168
169 Some of these are also available as package in Debian/Ubuntu::
170
171   $ apt-get install ghc cabal-install libghc-cabal-dev \
172                     libghc-json-dev libghc-network-dev \
173                     libghc-parallel-dev \
174                     libghc-utf8-string-dev libghc-curl-dev \
175                     libghc-hslogger-dev \
176                     libghc-crypto-dev libghc-text-dev \
177                     libghc-hinotify-dev libghc-regex-pcre-dev \
178                     libpcre3-dev \
179                     libghc-attoparsec-dev libghc-vector-dev \
180                     libghc-zlib-dev
181
182 Debian Jessie also includes recent enough versions of these libraries::
183
184   $ apt-get install libghc-base64-bytestring-dev \
185                     libghc-lens-dev \
186                     libghc-lifted-base-dev
187
188 In Fedora, some of them are available via packages as well::
189
190   $ yum install ghc ghc-json-devel ghc-network-devel \
191                     ghc-parallel-devel ghc-deepseq-devel \
192                     ghc-hslogger-devel ghc-text-devel \
193                     ghc-regex-pcre-devel
194
195 The most recent Fedora doesn't provide ``crypto``, ``inotify``. So these
196 need to be installed using ``cabal``.
197
198 If using a distribution which does not provide these libraries, first
199 install the Haskell platform. Then run::
200
201   $ cabal update
202
203 Then install the additional native libraries::
204
205   $ apt-get install libpcre3-dev libcurl4-openssl-dev
206
207 And finally the libraries required for building the packages via ``cabal``
208 (it will automatically pick only those that are not already installed via your
209 distribution packages)::
210
211   $ cabal install --only-dependencies cabal/ganeti.template.cabal
212
213 Haskell optional features
214 ~~~~~~~~~~~~~~~~~~~~~~~~~
215
216 Optionally, more functionality can be enabled if your build machine has
217 a few more Haskell libraries enabled: the ``ganeti-confd`` daemon
218 (``--enable-confd``), the monitoring daemon (``--enable-monitoring``) and
219 the meta-data daemon (``--enable-metadata``).
220 The extra dependencies for these are:
221
222 - `snap-server` <http://hackage.haskell.org/package/snap-server>`_, version
223   0.8.1 and above.
224 - `case-insensitive`
225   <http://hackage.haskell.org/package/case-insensitive>`_, version
226   0.4.0.1 and above (it's also a dependency of ``snap-server``).
227 - `PSQueue <http://hackage.haskell.org/package/PSQueue>`_,
228   version 1.0 and above.
229
230 These libraries are available in Debian Wheezy or later, so you can use
231 either apt::
232
233   $ apt-get install libghc-snap-server-dev libghc-psqueue-dev
234
235 or ``cabal``::
236
237   $ cabal install --only-dependencies cabal/ganeti.template.cabal \
238                   --flags="confd mond metad"
239
240 to install them.
241
242 .. _cabal-note:
243 .. note::
244   Make sure that your ``~/.cabal/bin`` directory (or whatever else
245   is defined as ``bindir``) is in your ``PATH``.
246
247 Installation of the software
248 ----------------------------
249
250 To install, simply run the following command::
251
252   $ ./configure --localstatedir=/var --sysconfdir=/etc && \
253     make && \
254     make install
255
256 This will install the software under ``/usr/local``. You then need to
257 copy ``doc/examples/ganeti.initd`` to ``/etc/init.d/ganeti`` and
258 integrate it into your boot sequence (``chkconfig``, ``update-rc.d``,
259 etc.). Also, Ganeti uses symbolic links in the sysconfdir to determine,
260 which of potentially many installed versions currently is used. If these
261 symbolic links should be added by the install as well, add the
262 option ``--enable-symlinks`` to the ``configure`` call.
263
264
265 Cluster initialisation
266 ----------------------
267
268 Before initialising the cluster, on each node you need to create the
269 following directories:
270
271 - ``/etc/ganeti``
272 - ``/var/lib/ganeti``
273 - ``/var/log/ganeti``
274 - ``/srv/ganeti``
275 - ``/srv/ganeti/os``
276 - ``/srv/ganeti/export``
277
278 After this, use ``gnt-cluster init``.
279
280 .. vim: set textwidth=72 syntax=rst :
281 .. Local Variables:
282 .. mode: rst
283 .. fill-column: 72
284 .. End: