Commit 727ee1ec authored by Iustin Pop's avatar Iustin Pop

Update INSTALL and devnotes documents

Added the new Haskell library requirements, for both normal and
developer usage.

Furthermore, all commands are now converted to the shell-example
lexer.
Signed-off-by: default avatarIustin Pop <iustin@google.com>
Reviewed-by: default avatarMichael Hanselmann <hansmi@google.com>
parent 63b4bb1e
......@@ -9,6 +9,8 @@ the :doc:`install`. A glossary of terms can be found in the
Software Requirements
---------------------
.. highlight:: shell-example
Before installing, please verify that you have the following programs:
- `Xen Hypervisor <http://www.xen.org/>`_, version 3.0 or above, if
......@@ -16,11 +18,11 @@ Before installing, please verify that you have the following programs:
- `KVM Hypervisor <http://www.linux-kvm.org>`_, version 72 or above, if
running on KVM. In order to use advanced features, such as live
migration, virtio, etc, an even newer version is recommended (qemu-kvm
versions 0.11.X or above have shown good behavior).
versions 0.11.X and above have shown good behavior).
- `DRBD <http://www.drbd.org/>`_, kernel module and userspace utils,
version 8.0.7 or above
- `RBD <http://ceph.newdream.net/>`_, kernel modules (rbd.ko/libceph.ko)
and userspace utils (ceph-common)
version 8.0.7 or above; note that Ganeti doesn't yet support version 8.4
- `RBD <http://ceph.newdream.net/>`_, kernel modules
(``rbd.ko``/``libceph.ko``) and userspace utils (``ceph-common``)
- `LVM2 <http://sourceware.org/lvm2/>`_
- `OpenSSH <http://www.openssh.com/portable.html>`_
- `bridge utilities <http://www.linuxfoundation.org/en/Net:Bridge>`_
......@@ -44,8 +46,8 @@ Before installing, please verify that you have the following programs:
- `affinity Python module <http://pypi.python.org/pypi/affinity/0.1.0>`_,
optional python package for supporting CPU pinning under KVM
- `ElementTree Python module <http://effbot.org/zone/element-index.htm>`_,
if running python 2.4 (optional, used by ovfconverter tool)
- `qemu-img <http://qemu.org/>`_, if you want to use ovfconverter
if running python 2.4 (optional, used by the ``ovfconverter`` tool)
- `qemu-img <http://qemu.org/>`_, if you want to use ``ovfconverter``
- `fping <http://fping.sourceforge.net/>`_
These programs are supplied as part of most Linux distributions, so
......@@ -60,10 +62,40 @@ packages, except for RBD, DRBD and Xen::
python-pyinotify python-pycurl socat \
python-elementtree qemu
If you want to also enable the `htools` components, which is recommended
on bigger deployments (they give you automatic instance placement,
cluster balancing, etc.), then you need to have a Haskell compiler
installed. More specifically:
If you want to build from source, please see doc/devnotes.rst for more
dependencies.
.. _socat-note:
.. note::
Ganeti's import/export functionality uses ``socat`` with OpenSSL for
transferring data between nodes. By default, OpenSSL 0.9.8 and above
employ transparent compression of all data using zlib if supported by
both sides of a connection. In cases where a lot of data is
transferred, this can lead to an increased CPU usage. Additionally,
Ganeti already compresses all data using ``gzip`` where it makes sense
(for inter-cluster instance moves).
To remedey this situation, patches implementing a new ``socat`` option
for disabling OpenSSL compression have been contributed and will
likely be included in the next feature release. Until then, users or
distributions need to apply the patches on their own.
Ganeti will use the option if it's detected by the ``configure``
script; auto-detection can be disabled by explicitely passing
``--enable-socat-compress`` (use the option to disable compression) or
``--disable-socat-compress`` (don't use the option).
The patches and more information can be found on
http://www.dest-unreach.org/socat/contrib/socat-opensslcompress.html.
Haskell requirements
~~~~~~~~~~~~~~~~~~~~
If you want to enable the `htools` component, which is recommended on
bigger deployments (this give you automatic instance placement, cluster
balancing, etc.), then you need to have a Haskell compiler installed on
your build machine (but this is not required on the machines which are
just going to run Ganeti). More specifically:
- `GHC <http://www.haskell.org/ghc/>`_ version 6.12 or higher
- or even better, `The Haskell Platform
......@@ -89,46 +121,49 @@ were renamed::
$ apt-get install ghc libghc-json-dev libghc-network-dev \
libghc-parallel-dev libghc-curl-dev
If using a distribution which does not provide them, the first install
the Haskell platform and then install the additional libraries via
``cabal``::
$ cabal install json network parallel curl
The compilation of the htools components is automatically enabled when
the compiler and the requisite libraries are found. You can use the
``--enable-htools`` configure flag to force the selection (at which
point ``./configure`` will fail if it doesn't find the prerequisites).
If you want to build from source, please see doc/devnotes.rst for more
dependencies.
In Ganeti version 2.6, one of the daemons (``ganeti-confd``) is shipped
in two versions: the Python default version (which has no extra
dependencies), and an experimental Haskell version. This latter version
can be enabled via the ``./configure`` flag ``--enable-confd=haskell``
and a few has extra dependencies:
.. _socat-note:
.. note::
Ganeti's import/export functionality uses ``socat`` with OpenSSL for
transferring data between nodes. By default, OpenSSL 0.9.8 and above
employ transparent compression of all data using zlib if supported by
both sides of a connection. In cases where a lot of data is
transferred, this can lead to an increased CPU usage. Additionally,
Ganeti already compresses all data using ``gzip`` where it makes sense
(for inter-cluster instance moves).
- `hslogger <http://software.complete.org/hslogger>`_, version 1.1 and
above (note that Debian Squeeze only has version 1.0.9)
- `Crypto <http://hackage.haskell.org/package/Crypto>`_, tested with
version 4.2.4
- `text <http://hackage.haskell.org/package/text>`_
- ``bytestring``, which usually comes with the compiler
To remedey this situation, patches implementing a new ``socat`` option
for disabling OpenSSL compression have been contributed and will
likely be included in the next feature release. Until then, users or
distributions need to apply the patches on their own.
These libraries are available in Debian Wheezy (but not in Squeeze), so
you can use either apt::
Ganeti will use the option if it's detected by the ``configure``
script; auto-detection can be disabled by explicitely passing
``--enable-socat-compress`` (use the option to disable compression) or
``--disable-socat-compress`` (don't use the option).
$ apt-get install libghc-hslogger-dev libghc-crypto-dev libghc-text-dev
The patches and more information can be found on
http://www.dest-unreach.org/socat/contrib/socat-opensslcompress.html.
or ``cabal``::
$ cabal install hslogger Crypto text
to install them.
Installation of the software
----------------------------
To install, simply run the following command::
./configure --localstatedir=/var --sysconfdir=/etc && \
make && \
make install
$ ./configure --localstatedir=/var --sysconfdir=/etc && \
make && \
make install
This will install the software under ``/usr/local``. You then need to
copy ``doc/examples/ganeti.initd`` to ``/etc/init.d/ganeti`` and
......
Developer notes
===============
.. highlight:: shell-example
Build dependencies
------------------
......@@ -19,7 +21,7 @@ Most dependencies from :doc:`install-quick`, plus (for Python):
- `pep8 <https://github.com/jcrocholl/pep8/>`_
Note that for pylint, at the current moment the following versions
need to be used::
must be used::
$ pylint --version
pylint 0.21.1,
......@@ -42,23 +44,27 @@ document, plus:
library, version 2.x
- ``hpc``, which comes with the compiler, so you should already have
it
- `shelltestrunner <http://joyful.com/shelltestrunner>`_, used for
running unit-tests
Under Debian Wheezy or later, these can be installed (on top of the
required ones from the quick install document) via::
Under Debian, these can be installed (on top of the required ones from
the quick install document) via::
$ apt-get install libghc-quickcheck2-dev hscolour hlint
apt-get install libghc-quickcheck2-dev hscolour hlint
Or alternatively via ``cabal``::
$ cabal install quickcheck hscolour hlint shelltestrunner
Configuring for development
---------------------------
.. highlight:: sh
Run the following command (only use ``PYTHON=...`` if you need to use a
different python version)::
./autogen.sh && \
./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
$ ./autogen.sh && \
./configure --prefix=/usr/local --sysconfdir=/etc --localstatedir=/var
Haskell development notes
-------------------------
......@@ -68,7 +74,7 @@ code.
You can run the Haskell linter :command:`hlint` via::
make hlint
$ make hlint
This is not enabled by default (as the htools component is
optional). The above command will generate both output on the terminal
......@@ -78,16 +84,16 @@ and, if any warnings are found, also an HTML report at
When writing or debugging TemplateHaskell code, it's useful to see
what the splices are converted to. This can be done via::
make HEXTRA="-ddump-splices"
$ make HEXTRA="-ddump-splices"
Due to the way TemplateHaskell works, it's not straightforward to
build profiling code. The recommended way is to run ``make hs-prof``,
or alternatively the manual sequence is::
make clean
make htools/htools HEXTRA="-osuf .o"
rm htools/htools
make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
$ make clean
$ make htools/htools HEXTRA="-osuf .o"
$ rm htools/htools
$ make htools/htools HEXTRA="-osuf .prof_o -prof -auto-all"
This will build the binary twice, per the TemplateHaskell
documentation, the second one with profiling enabled.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment