========================== 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