.. highlight:: console

Installation
============

ClusterShell is distributed in several packages. On RedHat-like OS, we
recommend to use the RPM package (.rpm) distribution.

As system software for cluster, ClusterShell is primarily made for
system-wide installation to be used by system administrators. However,
changes have been made so that it's now possible to install it without
root access (see :ref:`install-pip-user`).

.. _install-requirements:

Requirements
------------

ClusterShell should work with any Unix [#]_ operating systems which provides
Python 2.7 or 3.x and OpenSSH or any compatible Secure Shell clients.

.. warning:: While we are making our best effort to maintain Python 2
   compatibility in ClusterShell 1.9.x, we no longer run tests for Python 2.
   Therefore, functionality on Python 2 is not guaranteed and may break without
   notice. For the best experience and continued support, it is strongly
   recommended to use Python 3.

Furthermore, ClusterShell's engine has been optimized when the ``poll()``
syscall is available or even better, when the ``epoll_wait()`` syscall is
available (Linux only).

For instance, ClusterShell is known to work on the following operating systems:

* GNU/Linux

  * Red Hat Enterprise Linux 7 (Python 2.7)

  * Red Hat Enterprise Linux 8 (Python 3.6)

  * Red Hat Enterprise Linux 9 (Python 3.9)

  * Fedora 30 and above (Python 2.7 to 3.10+)

  * Debian 10 "buster" (Python 3.7)

  * Debian 11 "bullseye" (Python 3.9)

  * Ubuntu 20.04 (Python 3.8)

* Mac OS X 12+ (Python 2.7 and 3.8)

Distribution
------------

ClusterShell is an open-source project distributed under the GNU Lesser General
Public License version or later (`LGPL v2.1+`_), which means that many
possibilities are offered to the end user. Also, as a software library,
ClusterShell should remain easily available to everyone. Hopefully, packages are
currently available for Fedora Linux, RHEL (through EPEL repositories), Debian,
Arch Linux and more.

.. _install-python-support-overview:

Python support overview
^^^^^^^^^^^^^^^^^^^^^^^

As seen in :ref:`install-requirements`, ClusterShell supports Python 2.7 and
onwards, at least up to Python 3.10 at the time of writing.

The table below provides a few examples of versions of Python supported by
ClusterShell packages as found in some common Linux distributions:

+------------------+----------------------------+-----------------------------------+
| Operating        | System Python version used | Alternate Python support          |
| System           | by the clustershell tools  | packaged (version-suffixed tools) |
+==================+============================+===================================+
| RHEL 7           | Python 2.7                 | Python 3.6                        |
+------------------+----------------------------+-----------------------------------+
| RHEL 8           | **Python 3.6**             |                                   |
+------------------+----------------------------+-----------------------------------+
| RHEL 9           | **Python 3.9**             |                                   |
+------------------+----------------------------+-----------------------------------+
| Fedora 36        | **Python 3.10**            |                                   |
+------------------+----------------------------+-----------------------------------+
| openSUSE Leap 15 | Python 2.7                 | Python 3.6                        |
+------------------+----------------------------+-----------------------------------+
| SUSE SLES 12     | Python 2.7                 | Python 3.4                        |
+------------------+----------------------------+-----------------------------------+
| SUSE SLES 15     | Python 2.7                 | Python 3.6                        |
+------------------+----------------------------+-----------------------------------+
| Ubuntu 18.04 LTS | **Python 3.6**             |                                   |
+------------------+----------------------------+-----------------------------------+
| Ubuntu 20.04 LTS | **Python 3.8**             |                                   |
+------------------+----------------------------+-----------------------------------+

Red Hat Enterprise Linux
^^^^^^^^^^^^^^^^^^^^^^^^

ClusterShell packages are maintained on Extra Packages for Enterprise Linux
`EPEL`_ for Red Hat Enterprise Linux (RHEL) and its compatible spinoffs such
as `Alma Linux`_ and `Rocky Linux`_. At the time of writing, ClusterShell |version|
is available on EPEL 8 and 9.


Install ClusterShell from EPEL
""""""""""""""""""""""""""""""

First you have to enable the ``yum`` EPEL repository. We recommend to download
and install the `EPEL`_ repository RPM package. On CentOS, this can be easily
done using the following command::

    $ dnf --enablerepo=extras install epel-release

Then, the ClusterShell installation procedure is quite the same as for
*Fedora Updates*, for instance::

    $ dnf install clustershell

The Python 3 modules and tools are installed by default with ``clustershell``.
If interested in the Python 3 library only, you can install ClusterShell's
Python 3 subpackage using the following command::

    $ dnf install python3-clustershell

With EPEL 8 and 9, however, Python 3 is the system default, and Python 2 has
been deprecated. Thus only Python 3 is supported by the EPEL clustershell
packages, the tools are using Python 3 by default and are not suffixed anymore.

Fedora
^^^^^^

At the time of writing, ClusterShell |version| is available on Fedora 41
(releases being maintained by the Fedora Project).

Install ClusterShell from *Fedora Updates*
""""""""""""""""""""""""""""""""""""""""""

ClusterShell is part of Fedora, so it is really easy to install it with
``dnf``, although you have to keep the Fedora *updates* default repository.
The following command checks whether the packages are available on a Fedora
system::

    $ dnf list \*clustershell
    Available Packages
    clustershell.noarch                     1.8-1.fc26                fedora
    python2-clustershell.noarch             1.8-1.fc26                fedora
    python3-clustershell.noarch             1.8-1.fc26                fedora

Then, install ClusterShell's library module and tools using the following
command::

    $ dnf install clustershell

Prior to Fedora 31, Python 2 modules and tools were installed by default. If
interested in Python 3 support, simply install the additional ClusterShell's
Python 3 subpackage using the following command::

    $ dnf install python3-clustershell

Prior to Fedora 31, Python 3 versions of the tools are installed as
*tool-pythonversion*, like ``clush-3.6``, ``cluset-3.6`` or ``nodeset-3.6``.

On Fedora 31 and onwards, only Python 3 is supported.

Install ClusterShell from Fedora Updates Testing
""""""""""""""""""""""""""""""""""""""""""""""""

Recent releases of ClusterShell are first available through the
`Test Updates`_ repository of Fedora, then it is later pushed to the stable
*updates* repository. The following ``dnf`` command will also checks for
packages availability in the *updates-testing* repository::

    $ dnf list \*clustershell --enablerepo=updates-testing

To install, also add the ``--enablerepo=updates-testing`` option, for
instance::

    $ dnf install clustershell --enablerepo=updates-testing

openSUSE
^^^^^^^^

ClusterShell is available in openSUSE Tumbleweed (Factory) and Leap since 2017::

    $ zypper search clustershell
    Loading repository data...
    Reading installed packages...

    S | Name                 | Summary                                               | Type
    --+----------------------+-------------------------------------------------------+--------
      | clustershell         | Python framework for efficient cluster administration | package
      | python2-clustershell | ClusterShell module for Python 2                      | package
      | python3-clustershell | ClusterShell module for Python 3                      | package


To install ClusterShell on openSUSE, use::

    $ zypper install clustershell

Python 2 module and tools are installed by default. If interested in Python 3 support,
simply install the additional ClusterShell's Python 3 subpackage
using the following command::

    $ zypper install python3-clustershell

Python 3 versions of the tools are installed as *tool-pythonversion*, like
``clush-3.6``, ``cluset-3.6`` or ``nodeset-3.6``.

Debian
^^^^^^

ClusterShell is available in Debian **main** repository (since 2011).

To install it on Debian, simply use::

    $ apt-get install clustershell

You can get the latest version on::

* http://packages.debian.org/sid/clustershell


Ubuntu
^^^^^^

Like Debian, it is easy to get and install ClusterShell on Ubuntu (also with
``apt-get``). To do so, please first enable the **universe** repository.
ClusterShell is available since "Natty" release (11.04):

* http://packages.ubuntu.com/clustershell

.. _install-python:

Installing ClusterShell the Python way
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. warning:: Installing ClusterShell as root using pip [#]_ is discouraged and
   can result in conflicting behaviour with the system package manager.  Use
   packages provided by your OS instead to install ClusterShell system-wide.

.. _install-pip-user:

Installing ClusterShell as user using pip
"""""""""""""""""""""""""""""""""""""""""

To install ClusterShell as a standard Python package using pip as an user::

    $ pip install --user ClusterShell

Or alternatively, using the source tarball::

    $ pip install --user ClusterShell-1.x.tar.gz

Then, you might need to update your ``PATH`` to easily use the :ref:`tools`,
and possibly set the ``PYTHONPATH`` environment variable to be able to import
the library, and finally ``MANPATH`` for the man pages::

    $ export PATH=$PATH:~/.local/bin
    $
    $ # Might also be needed:
    $ export PYTHONPATH=$PYTHONPATH:~/.local/lib
    $ export MANPATH=$MANPATH:$HOME/.local/share/man

Configuration files are installed in ``~/.local/etc/clustershell`` and are
automatically loaded before system-wide ones (for more info about supported
user config files, please see the :ref:`clush-config` or :ref:`groups-config`
config sections).

.. _install-venv-pip:

Isolated environment using virtualenv and pip
"""""""""""""""""""""""""""""""""""""""""""""

It is possible to use virtual env (`venv`_) and pip to install ClusterShell
in an isolated environment::

    $ python3 -m venv venv
    $ source venv/bin/activate
    $ pip install ClusterShell

.. _install-source:

Source
------

Current source is available through Git, use the following command to retrieve
the latest development version from the repository::

    $ git clone git@github.com:cea-hpc/clustershell.git


.. [#] Unix in the same sense of the *Availability: Unix* notes in the Python
   documentation
.. [#] pip is a tool for installing and managing Python packages, such as
   those found in the Python Package Index

.. _LGPL v2.1+: https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html
.. _Test Updates: http://fedoraproject.org/wiki/QA/Updates_Testing
.. _EPEL: http://fedoraproject.org/wiki/EPEL
.. _Alma Linux: https://almalinux.org/
.. _Rocky Linux: https://rockylinux.org/
.. _venv: https://docs.python.org/3/tutorial/venv.html