============================================================================
sunzi: a web-based GUI frontend for the Pacemaker cluster resource manager
============================================================================
Web application `sunzi` allows various administrative tasks within
`Pacemaker`_ powered clusters. It is built on the `TurboGears 2`_
framework.
.. _Pacemaker: http://www.clusterlabs.org/
.. _TurboGears 2: http://turbogears.org/
1. Introduction
===============
``TODO``
2. Installation and Setup
=========================
In case of using distro-packaged version of `sunzi`, you can skip
to point ``TODO``. If you want to contribute, you may be also
skip down to point 2.3.
2.1 Dependencies
----------------
``TODO`` (see below)
programs:
shell
Python
GCC
libraries:
(sasl)
Python libraries:
2.2 Using upstream code
-----------------------
Initial repository clone could be done as (once `master` branch exists)::
git clone git://git.fedorahosted.org/sunzi.git
cd third-party; ./init.sh all; cd ..
to also initialize third-party bundles, necessary for successful
package build.
Another enabling step is to get an initial `setup.cfg` file (unless you want
to provide all the parameters in command-line) as a copy of the default one::
cp dist-files/setup.cfg .
Probably more convenient is to use `./setup` shell wrapper at places you
would use `python setup.py`. This will ensure you have pristine version
of `setup.cfg` (from the path above) before actually performing requested
`setup.py` command(s), which can prevent "oh, I had edited setup.cfg and
forgot". To preserve a copy of `setup.cfg`, just use `python setup.py`
as usual.
2.3 Quick start (for contribution)
----------------------------------
Bootstrap script is the fastest way to experiment with `sunzi`. No external
Python library is needed as Python side is well-managed in the isolated
virtualenv environment. This snippet will setup the environment in the
current dir (but feel free to modify as per your needs)::
URL='http://git.fedorahosted.org/git/?p=sunzi.git;a=blob_plain;f=sunzi-bootstrap.py;hb=8909e2a'
ARGS=". " # actual arguments for virtualenv (target dir has to be present)
curl $URL | python -c'import sys;__file__="_";exec(sys.stdin.read())' $ARGS
# or download $URL locally and run as a common Python script...
.. TODO: URL may be even static file, e.g., on fedorapeople.org
The whole process may take a while as the steps from 2.2 are being perfomed
(third-party repositories cloned, etc.). In the internal logic of setup,
the virtualenv environment is used automatically, but you have to activate
it manually (`source bin/activate`, look at virtualenv documentation)
before rerunning the application, etc.
Note: `yolk`_ allows maintaining packages within the virtualenv environment.
.. _yolk: http://pypi.python.org/pypi/yolk
.. ``TODO``
.. Prerequisities for successful build/installation/deployment:
..
.. * python (2.6, 2.7 should be also fine)
.. * Cyrus SASL v2 (2.1.22+) libraries and header files
.. * to use bundled initscript, check the additional requirements
.. in the SPEC file (mostly common utilities that are found everywhere)
..
.. Any missing Python package might be installed with ``setuptools`` automatically
.. (if even ``setuptools`` is missing, ``ez_setup`` is there to handle it).
..
..
.. Following items describe the steps to get it running (instructions contain some
.. example values that should be modified to fit the environment, needs etc.;
.. also you might need to do some of the commands as a root):
..
.. 0. Make sure you are navigated to the directory containing this ``README``.
.. If you have just cloned luci from the git repository as shown above,
.. you may need to move here:
..
.. $ cd luci
..
.. 1. Edit ``pkg_prepare`` section in ``setup.cfg`` according to your needs
.. (using ``vim``, for instance). The names of configuration items there
.. should be self-explainatory::
..
.. $ vim setup.cfg
..
.. Note: Following steps use default values in ``setup.cfg`` so if you have
.. changed anything there, you might have to modify commands
.. accordingly.
..
.. Note: It is also possible to define (in an overriding manner) all these
.. options directly as command-line arguments preceded by
.. ``prepare_pkg'' which are as a whole appended to ``install`` command
.. in the step 2., see also ``python setup.py pkg_prepare --help``.
..
.. 2. Install ``luci`` using the ``setup.py`` script which also includes
.. prior compilation of C extensions and some files preparation::
..
.. $ python setup.py install
..
.. 3. Optionally, you can change the certificate configuration file, especially
.. you can fill concrete hostname or IP address under which the machine
.. running luci will be accessible by other computers in the network, which
.. will prevent some (not all, there is still a problem that the generated
.. certificate is self-signed) of the warnings about the certificate::
..
.. $ vim /var/lib/luci/etc/cacert.config
..
.. 4. Now, there are two ways how to continue... The easier way is to use
.. bundled initscript -- just run two immediately following commands and you
.. are ready, having luci started (at worst, some little tweaking required).
.. If you want "expert-mode" way, just skip them and continue starting with
.. point 3b. This way follows the sequence of commands effectively used in
.. the initscript, although initscript is more fine-tuned so refer to it
.. if something gets stuck.
..
.. 4a. Edit configuration file that comes with initscript according to your needs
.. (``vim`` used as an example here again):
..
.. $ vim /etc/sysconfig/luci
..
.. 5a. Start the ``paste`` http(s) server using bundled initscript::
..
.. $ service luci start
..
.. Note: Before the first run of this command, it is good to do following::
..
.. $ chkconfig --add luci
..
.. 6a. Luci should be running, check respective address (echoed by initscript).
.. To stop it, use::
..
.. $ service luci stop
..
.. 4b. To achieve the same as with 5a. but using direct commands, start with
.. generating base configuration file from implicit template::
..
.. $ paster make-config luci /var/lib/luci/etc/luci.ini
..
.. 5b. Similarly, create the database used by ``luci``::
..
.. $ paster setup-app /var/lib/luci/etc/luci.ini
..
.. Note: If you use preconfigured ``pkg_prepare`` section in ``setup.cfg``,
.. don't forget to create ``/var/lib/luci/data`` first (missing parts
.. of paths like this are not created automatically unless you use
.. initscript).
..
.. 6b. Generate self-signed certificate for luci using originally installed
.. configuration file (installation location depends on ``certconfig`` value
.. in ``setup.cfg`` which is ``/var/lib/luci/etc/cacert.config`` by default)::
..
.. $ export RANDFILE=$(mktemp -q cert_rnd.XXXXXX)
.. $ openssl req -new -x509 -nodes -sha1 \
.. > -newkey rsa:2048 \
.. > -config /var/lib/luci/etc/cacert.config \
.. > -days 1825 \
.. > -set_serial "$(/bin/date +%s)" \
.. > -keyout /var/lib/luci/certs/host.pem \
.. > -out /var/lib/luci/certs/host.pem
.. $ rm -f cert_rnd.*
..
.. Note: If you use preconfigured ``pkg_prepare`` section in ``setup.cfg``,
.. don't forget to create ``/var/lib/luci/certs`` first (missing parts
.. of paths like this are not created automatically unless you use
.. initscript).
..
.. Note: Do not forget to set the permissions for generated certificate
.. (``/var/lib/luci/certs/host.pem`` was used in the example) such that
.. it is only accessible by the user which then effectively runs luci.
..
.. 7b. Compared to point 4a. from a straightforward "initscript" way, you have no
.. other way (unless you will find out how to use config. file that comes
.. with initscript directly from initscript) then to edit base configuration
.. file immediately (``/var/lib/luci/etc/luci.ini`` by default). Especially
.. if you have used another path for the output certificate in the step 6b.,
.. this configuration item should be edited respectively::
..
.. $ vim /var/lib/luci/etc/luci.ini
..
.. 8b. Finally, start the SASL daemon and then ``paste`` http(s) server...::
..
.. $ saslauthd -a pam
.. $ paster serve /var/lib/luci/etc/luci.ini
..
.. Note: The former command might be replaced with equivalent if applicable
.. (``MECH=pam`` in respective configuration) ::
..
.. $ service start saslauthd
..
.. Note: To run luci on background, refer to the ``--daemon`` option
.. for ``paster`` command.
..
.. 9b. Luci should be running, check respective address (can be found in
.. configuration file used such as ``/var/lib/luci/etc/luci.ini`` from
.. the example). To stop it, press Ctrl-C.
..
.. Please note that these steps do not cover everything -- initscript and maybe
.. the SPEC file might give you a better idea.
..
..
.. 1.2 Using package in your preferred distribution
.. ------------------------------------------------
..
.. Currently, this project is recognized only in RHEL 6 and Fedora [#distros]_.
.. Using them, you can get latest ``luci`` package using::
..
.. $ yum install luci
..
.. .. [#distros] on these distros, ``luci`` has an official status
..
..
.. 1.3 Post-installation procedures
.. --------------------------------
..
.. Please refer to
.. http://sources.redhat.com/cluster/wiki/Luci#Post-installation_procedures
3. Authors
==========
:Authors/Contributors:
Ryan McCabe <rmccabe@redhat.com>
Jan Pokorný <jpokorny@redhat.com>
.. :Homepage: http://sources.redhat.com/cluster/wiki/Luci
.. vim: et:ts=4:sw=4:fileencoding=utf-8:syntax=rst