README

==========================
 clufter (CLUster FilTER)
==========================

.. code-block:: bash

  $ ./run-dev -h | sed '2,8p;d'

  Tool/library for transforming/analyzing cluster configuration formats

  While primarily aimed at (CMAN,rgmanager)->(Corosync/CMAN,Pacemaker) cluster
  stacks configuration conversion (as per RHEL trend), the command-filter-format
  framework (capable of XSLT) offers also other uses through its plugin library.

And nope, the name is not a pun, typo or lisp-pronounced `cluster` per se :-P
As mentioned elsewhere, the project is pretty composite, just as its name is.

Historical curiosity: ``clufter`` logotype should actually make ``f``
look similar to ``ſ`` letter (`long s`__, in use some 200 years ago)
as an explicit association with an s-contained word (conversely, project
name searchable in *A new alphabetical vocabulary, Gailic and English*
`OCR scan`__).

.. __: https://en.wikipedia.org/wiki/Long_s
.. __: http://deriv.nls.uk/dcn6/7664/76646081.6.pdf


-------
 Usage
-------

The package can either be used as a separate CLI tool (as per *What*) or as
a Python library, which is the case, e.g., with `pcs`_.

.. _pcs: https://github.com/ClusterLabs/pcs


Demo
~~~~

When properly installed, ``clufter`` command should be only these few
letters away at your shell prompt.  For simplicity, I will stick with
what one can use directly after cloning the repository and running
``./run-check`` (to get the helper binary compiled):

.. code-block:: bash

  $ ./run-dev ccs2pcscmd -gsq tests/filled.conf
  #!/bin/sh
  # sequence generated on 2017-03-10 17:01:31 with: clufter 0.60.0a
  # invoked as: ['./run-dev', 'ccs2pcscmd', '-gsq', 'tests/filled.conf']
  # targeting system: ('linux', 'fedora', '27', 'Rawhide')
  # using interpreter: CPython 2.7.13
  pcs cluster auth ju hele <>/dev/tty
  pcs cluster setup --name test ju hele --consensus 200 --join 100 \
    --token 5000
  pcs cluster start --all --wait=60
  pcs cluster cib tmp-cib.xml
  pcs -f tmp-cib.xml property set stonith-enabled=false
  pcs cluster cib-push tmp-cib.xml --config

or using Python 3:

.. code-block:: bash

  $ python3 ./run-dev ccs2pcscmd -gsq tests/filled.conf
  #!/bin/sh
  # sequence generated on 2017-03-10 17:02:34 with: clufter 0.60.0a
  # invoked as: ['run-dev', 'ccs2pcscmd', '-gsq', 'tests/filled.conf']
  # targeting system: ('linux', 'fedora', '27', 'Rawhide')
  # using interpreter: CPython 3.6.0
  pcs cluster auth ju hele <>/dev/tty
  pcs cluster setup --name test ju hele --consensus 200 --join 100 \
    --token 5000
  pcs cluster start --all --wait=60
  pcs cluster cib tmp-cib.xml
  pcs -f tmp-cib.xml property set stonith-enabled=false
  pcs cluster cib-push tmp-cib.xml --config

Here we got a sequence of ``pcs`` commands that should get us
started with rebuilding a cluster originally based on CMAN/rgmanager
stack (with configuration captured in given file), now targetting
Corosync/Pacemaker one (for which ``pcs`` is one of the high-level
configuration tools).

Depending on how sensitive the target environment is (conversely,
how much confident of ``clufter`` and its output you are), you can
either reason about each command, possibly making correction in due
course (well, ``clufter`` never had ambitions to be fully and reliably
automagic), or just pipe that into the shell interpreter, for instance:

.. code-block:: bash

  $ ./run-dev ccs2pcscmd -gsq tests/filled.conf | bash -x

which will also turn on echoing of what is being executed, just in case.

Take this just as a showcase of the primary goal for this tool, there
are many other realated conversion/analysis related tasks featured
and discoverable as:

.. code-block:: bash

  $ ./run-dev -l


Dependencies
~~~~~~~~~~~~

Python-wise:

- `lxml`_ (``python-lxml``/``python3-lxml``)

general:

- Python

  - 2.7 preferred

  - 2.6 with `ordereddict`_ or some kind of ``collections.OrderedDict``
    backport (#929258) required

  - 3.2+ support currently deemed experimental (the test suite is passing),
    bug reports appreciated (see `Reporting issues`_)

- embedded ``ccs_flatten`` (originally `pacemaker.git/extra/rgmanager
  <https://github.com/ClusterLabs/pacemaker/commit/6ef3f77>`_) compiled
  helper

  - suitable C compiler (``gcc``)
  - ``libxml2``


tests:

- outside of Python 2.7+, `unittest2`_ (``python-unittest2``)
  or, alternatively, `nose`_ (``python-nose``) is needed

.. _lxml: http://lxml.de
.. _ordereddict: https://pypi.python.org/pypi/ordereddict
.. _unittest2: https://pypi.python.org/pypi/unittest2
.. _nose: https://pypi.python.org/pypi/nose


Stable version
~~~~~~~~~~~~~~

Official released tarballs (as opposed to what you can `download from
GitHub <https://github.com/jnpkrn/clufter/releases>`_) can be found,
together with GPG signatures,
at https://pagure.io/releases/clufter/ or, alternatively,
at https://people.redhat.com/jpokorny/pkgs/clufter/.

Also, the ``HEAD`` of ``master`` branch in the repository should always
point to the latest stable, tagged (and GPG-signed, for that matter)
release.  Current status of the test run using Travis CI against
this branch:

.. image:: https://travis-ci.org/jnpkrn/clufter.svg?branch=master
  :target: https://travis-ci.org/jnpkrn/clufter

.. image:: https://coveralls.io/repos/jnpkrn/clufter/badge.svg?branch=master&service=github
  :target: https://coveralls.io/github/jnpkrn/clufter?branch=master


Development version
~~~~~~~~~~~~~~~~~~~

TBD

.. image:: https://travis-ci.org/jnpkrn/clufter.svg?branch=next
  :target: https://travis-ci.org/jnpkrn/clufter

.. image:: https://coveralls.io/repos/jnpkrn/clufter/badge.svg?branch=next&service=github
  :target: https://coveralls.io/github/jnpkrn/clufter?branch=next


---------------
 Other remarks
---------------

Bash completion
~~~~~~~~~~~~~~~

For convenience, bash completion is at user's hands by just running within
the session:

.. code-block:: bash

  $ eval "$(clufter --completion-bash)"


Indeed, to make such a feature permanent, the produced script can be appended
to or referred from some relevant file like ``~/.bashrc``, or when
``bash-completion`` package installed, stored to ``~/.config/bash_completion``
(per-user) or ``/usr/share/bash-completion/bash_completion`` (system-wide).
It's also possible this is already performed on the packaging level.


---------
 Contact
---------

Reporting issues
~~~~~~~~~~~~~~~~

Bug reports, suggestions and feature requests are best directed at
https://pagure.io/clufter/issues, alternatively check the bottom of
``clufter --help`` screen when using a distribution version.

The more feedback samples emerge, the better this project can get.


Wider community
~~~~~~~~~~~~~~~

Common cluster/HA channels falling under `ClusterLabs`_ umbrella:

- `users dedicated mailing list`_
- ``#clusterlabs`` channel at Freenode IRC server

.. _ClusterLabs: http://clusterlabs.org/
.. _users dedicated mailing list: http://oss.clusterlabs.org/mailman/listinfo/users