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

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

:Author: Stephane Thiell, <sthiell@stanford.edu>
:Date:   2017-10-23
:Copyright: GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)
:Version: 1.8
: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. system-wide configuration file (*/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
  initate up to **16** connections to their target nodes at the same time.
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_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
  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`)
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.

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

Simple configuration file.

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

| [Main]
| fanout: 128
| connect_timeout: 15
| command_timeout: 0
| history_size: 100
| color: auto
| fd_max: 10240
| node_count: yes
|


FILES
=====

*/etc/clustershell/clush.conf*
  System-wide clush configuration file.

*$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).

http://clustershell.readthedocs.org/
