CLUSH.CONF(5)

🎀 CLUSH.CONF 💖 — the config file that runs the whole clush vibe

ok bestie, this is section 5 of the ClusterShell User Manual, and it's literally the manual page for clush.conf — the little config file that decides how clush behaves. pull up a chair 🫶

---

✨ NAME ✨

clush.conf — configuration file for clush, no cap 💅

---

🌸 DESCRIPTION 🌸

the clush(1) config files are in Python's ConfigParser format. that's the vibe. it's giving .ini energy fr fr.

📍 Locations 📍

so clush(1) goes hunting for config options in a bunch of places, and it checks them in decreasing order of precedence — meaning the first one it finds wins, and the rest are just background characters:

1. command-line options 👑
2. $CLUSTERSHELL_CFGDIR/clush.conf — only used when $CLUSTERSHELL_CFGDIR is defined, iykyk
3. user configuration file ($XDG_CONFIG_HOME/clustershell/clush.conf, defaults to $HOME/.config/clustershell/clush.conf)
4. Python virtual environment ({sys.prefix}/etc/clustershell/clush.conf)
5. local pip user installation ($HOME/.local/etc/clustershell/clush.conf)
6. system-wide configuration file (/etc/clustershell/clush.conf)

for each parameter, the first obtained value will be used. periodt. 💅

the config file has a format in the style of RFC 822, composed of one main section:

• Main — program options definition

---

💖 [Main] 💖

the configuration parameters of the Main section are described below, and yes we're going through every single one, don't scroll 🫶

• fanout — the size of the sliding window (fanout) of active commands for clush. this fanout exists 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). so like, 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. slay ⭐
• 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 uses 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. it's giving rainbow but make it two colors 🌈
• 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. keep an eye on it bestie 👀
• history_size — set the maximum number of history entries saved in the GNU readline history list. negative values imply unlimited history file size. unlimited. main character energy 📜
• 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. glow up 💅
• rcp_path — same as 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. iconic behavior tbh 🔥

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, it is ignored. when --mode is specified, you can display all available run modes for the current user by enabling debug mode (-d). so helpful fr fr 🦋

---

💫 EXAMPLES 💫

simple configuration file. here's the whole thing, verbatim, don't touch it:

🎀 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.
• {sys.prefix}/etc/clustershell/clush.conf — configuration file when ClusterShell is installed in a Python virtual environment. ✨
• $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 (no longer read since version 1.9). rest in peace bestie 💀

---

📜 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). character development 🧚

---

👀 SEE ALSO 👀

• clush(1), groups.conf(5), sshpass(1), sudo(8)
• https://clustershell.readthedocs.io/
• Python ConfigParser
• https://docs.python.org/3/library/configparser.html

---

👑 AUTHOR 👑

Stephane Thiell

---

💜 COPYRIGHT 💜

GNU Lesser General Public License version 2.1 or later (LGPLv2.1+)

---

and that's the whole page bestie 🫶 this was CLUSH.CONF(5) from the ClusterShell User Manual, version 1.10.1, dated 2026-07-16. go forth and configure responsibly, mwah 💅✨