============
 clush.conf
============

------------------------------
Configuration file for `clush`
------------------------------

:Author: Stephane Thiell, <sthiell@stanford.edu>
:Date:   2023-02-09
:Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
:Version: 1.9.1
:Manual section: 5
:Manual group: ClusterShell User Manual


DESCRIPTION
===========

``clush``\(1) obtains configuration options from the following sources in the
following order:

 1. command-line options
 2. user configuration file (*$XDG_CONFIG_HOME/clustershell/clush.conf*)
 3. local pip user installation (*$HOME/.local/etc/clustershell/clush.conf*)
 4. global configuration file (*$CLUSTERSHELL_CFGDIR/clush.conf*, defaults to
    */etc/clustershell/clush.conf*)

For each parameter, the first obtained value will be used.

The configuration file has a format in the style of RFC 822 composed
of one main section:

Main
  Program options definition


[Main]
------
Configuration parameters of the ``Main`` section are described below.

fanout
  Size of the sliding window (fanout) of active commands for ``clush``. This
  `fanout` is used to avoid too many concurrent connections and to conserve
  resources on the initiating hosts. In tree mode, the same `fanout` value is
  used on the head node and on each gateway (the `fanout` value is propagated).
  That is, if the `fanout` is **16** on the head node, each gateway will
  initiate up to **16** connections to their target nodes at the same time.
confdir
  Optional list of directory paths where clush should look for `.conf` files
  which define run modes that can then be activated with ``--mode``. All other
  clush config file settings defined here might be overridden in a run mode.
  Each mode section should have a name prefixed by "mode:" to clearly identify
  a section defining a mode. Duplicate modes are not allowed in those files.
  Configuration files that are not readable by the current user are ignored.
  The variable `$CFGDIR` is replaced by the path of the highest priority
  configuration directory found (where clush.conf resides). The default confdir
  value enables both system-wide and any installed user configuration (thanks
  to `$CFGDIR`). Duplicate directory paths are ignored.
connect_timeout
  Timeout in seconds to allow a connection to establish. This parameter is
  passed to ssh. If set to *0*, no timeout occurs.
command_prefix
  Command prefix. Generally used for specific run modes, for example to
  implement ``sudo``\(8\) support.
command_timeout
  Timeout in seconds to allow a command to complete since the connection has
  been established. This parameter is passed to ssh.  In addition, the
  ClusterShell library ensures that any commands complete in less than
  ( connect_timeout + command_timeout ). If set to *0*, no timeout occurs.
color
  ``clush`` can use NO_COLOR, CLICOLOR and CLICOLOR_FORCE
  environment variables. NO_COLOR takes precedence over CLICOLOR_FORCE which
  takes precedence over CLICOLOR. When the option is set in configuration file
  environment variables are taken into account only with `auto` argument.
  ``color`` tells  whether to use ANSI colors to surround node or nodeset
  prefix/header with escape sequences to display them in color on the terminal.
  Valid arguments are ``never``, ``always`` or ``auto`` (which use color if
  standard output/error refer to a terminal). Colors are set to [34m (blue
  foreground text) for stdout and [31m (red foreground text) for stderr, and
  cannot be modified.
fd_max
  Maximum number of open file descriptors permitted per clush process (soft
  resource limit for open files). This limit can never exceed the system
  (hard) limit. The `fd_max` (soft) and system (hard) limits should be high
  enough to run ``clush``, although their values depend on your `fanout` value.
history_size
  Set the maximum number of history entries saved in the GNU readline history
  list. Negative values imply unlimited history file size.
node_count
  Should ``clush`` display additional (node count) information in buffer
  header? (`yes`/`no`)
maxrc
  Should ``clush`` return the largest of command return codes? (yes/no)
password_prompt
  Enable password prompt and password forwarding to stdin? (yes/no) Generally
  used for specific run modes, for example to implement interactive
  ``sudo``\(8\) support.
verbosity
  Set the verbosity level: `0` (quiet), `1` (default), `2` (verbose) or more
  (debug).
ssh_user
  Set the ssh user to use for remote connection (default is to not specify).
ssh_path
  Set the ssh binary path to use for remote connection (default is `ssh`).
ssh_options
  Set additional options to pass to the underlying ssh command.
scp_path
  Set the scp binary path to use for remote copy (default is `scp`).
scp_options
  Set additional options to pass to the underlying scp command. If not
  specified, ssh_options are used instead.
rsh_path
  Set the rsh binary path to use for remote connection (default is
  `rsh`). You could easily use mrsh or krsh by simply changing this value.
rcp_path
  Same a rsh_path for rcp command. (Default is `rcp`)
rsh_options
  Set additional options to pass to the underlying rsh/rcp command.

Run modes
---------
Since version 1.9, clush has support for run modes, which are special
``clush.conf``\(5) settings with a given name. Two run modes are provided in
example configuration files that can be copied and modified. They implement
password-based authentication with ``sshpass``\(1\) and support of interactive
``sudo``\(8\) with password.

To use a run mode with ``clush --mode``, install a configuration file in one of
``clush.conf``\(5)'s `confdir` (usually ``clush.conf.d``). Only configuration
files ending in `.conf` are scanned. If the user running ``clush``\(1\) doesn't
have read access to a configuration file, is it ignored. When ``--mode`` is
specified, you can display all available run modes for the current user by
enabling debug mode (``-d``).

EXAMPLES
===========

Simple configuration file.

*clush.conf*
------------

| [Main]
| fanout: 128
| connect_timeout: 15
| command_timeout: 0
| history_size: 100
| color: auto
| fd_max: 10240
| maxrc: no
| node_count: yes
| confdir: /etc/clustershell/clush.conf.d
|


FILES
=====

*$CLUSTERSHELL_CFGDIR/clush.conf*
  Global clush configuration file. If $CLUSTERSHELL_CFGDIR is not defined,
  */etc/clustershell/clush.conf* is used instead.

*$XDG_CONFIG_HOME/clustershell/clush.conf*
  User configuration file for clush. If $XDG_CONFIG_HOME is not defined,
  *$HOME/.config/clustershell/clush.conf* is used instead.

*$HOME/.local/etc/clustershell/clush.conf*
  Local user configuration file for clush (default installation for pip --user)

*~/.clush.conf*
  Deprecated per-user clush configuration file.


HISTORY
=======

As of ClusterShell version 1.3, the ``External`` section has been removed
from *clush.conf*.  External commands whose outputs were used by ``clush``
(-a, -g, -X) are now handled by the library itself and defined in
``groups.conf``\(5).


SEE ALSO
========

``clush``\(1), ``groups.conf``\(5), ``sshpass``\(1\), ``sudo``\(8\).

http://clustershell.readthedocs.org/
