clush — clustershell 1.10.1 documentation

Tools

clush

View page source

clush

clush is a program for executing commands in parallel on a cluster and for<br>gathering their results. It can execute commands interactively or can be used<br>within shell scripts and other applications. It is a partial front-end to the<br>Task class of the ClusterShell library (cf. Structure of Task).<br>clush currently makes use of the Ssh worker of ClusterShell by default,<br>which only requires ssh(1) (we tested with OpenSSH SSH client).

Some features of clush command line tool are:

two modes of parallel cluster commands execution:

flat mode: sliding window of local or remote (e.g.<br>ssh(1)) commands

tree mode: commands propagated to the targets<br>through a tree of pre-configured gateways; gateways are then using a<br>sliding window of local or ssh(1) commands to reach the targets (if the<br>target count per gateway is greater than the<br>fanout value)

smart display of command results (integrated output gathering, sorting by<br>node, nodeset or node groups)

standard input redirection to remote nodes

files copying in parallel

pdsh [1] options backward compatibility

clush can be started non-interactively to run a shell command, or can be<br>invoked as an interactive shell. Both modes are discussed here (see<br>Non-interactive (or one-shot) mode and Interactive mode).

Target and filter nodes

clush offers different ways to select or filter target nodes through command<br>line options or files containing a list of hosts.

Command line options

The -w option allows you to specify remote hosts by using ClusterShell<br>NodeSet syntax, including the node groups @group special syntax<br>(cf. Node group expression rules) and the Extended String Patterns syntax (see<br>Extended String Pattern) to benefit from NodeSet<br>basic arithmetic (like @Agroup&@Bgroup). Additionally, the -x option<br>allows you to exclude nodes from remote hosts list (the same NodeSet syntax<br>can be used here). Nodes exclusion has priority over nodes addition.

Using node groups

If you have ClusterShell node groups configured on your<br>cluster, any node group syntax may be used in place of nodes for -w as<br>well as -x.

For example:

$ clush -w @rhel6 cat /proc/loadavg<br>node26: 0.02 0.01 0.00 1/202 23042

For pdsh backward compatibility, clush supports two -g and -X<br>options to respectively select and exclude nodes group(s), but only specified<br>by omitting any "@" group prefix (see example below). In general, though, it<br>is advised to use the @-prefixed group syntax as the non-prefixed notation<br>is only recognized by clush but not by other tools like nodeset.

For example:

$ clush -g rhel6 cat /proc/loadavg<br>node26: 0.02 0.01 0.00 1/202 23033

Selecting all nodes

The special option -a (without argument) can be used to select all<br>nodes, in the sense of ClusterShell node groups (see<br>node groups configuration for more details on special<br>all external shell command upcall). If not properly configured, the<br>-a option may lead to a runtime error like:

clush: External error: Not enough working methods (all or map + list) to get all nodes

Picking node(s) at random

Use --pick with a maximum number of nodes you wish to pick randomly from<br>the targeted node set. clush will then run only on selected node(s). The<br>following example will run a script on a single random node picked from the<br>@compute group:

$ clush -w @compute --pick=1 ./nonreg-single-client-fs-io.sh

Host files

The option --hostfile (or --machinefile) may be used to specify a<br>path to a file containing a list of single hosts, node sets or node groups,<br>separated by spaces and lines. It may be specified multiple times (one per<br>file).

For example:

$ clush --hostfile ./host_file -b systemctl is-enabled httpd

This option has been added as backward compatibility with other parallel shell<br>tools. Indeed, ClusterShell provides a preferred way to provision node sets<br>from node group sources and flat files to all cluster tools using<br>NodeSet (including clush). Please see node groups<br>configuration.

Note

Use --debug or -d to see resulting node sets from host<br>files.

Flat execution mode

The default execution mode is to launch commands (local or remote) in parallel,<br>up to a certain limit fixed by the fanout value,<br>which is the number of child processes allowed to run at a time. This "sliding<br>window" of active commands is a common technique used on large clusters to<br>conserve resources on the initiating host, while allowing some commands to<br>time out. If used with ssh(1), this does actually limit the number of<br>concurrent ssh connections.

Fanout (sliding window)

The --fanout (or -f) option of clush allows the user to change the<br>default fanout value defined in clush.conf or in the<br>library defaults if not specified.

Indeed, it is sometimes useful to change the fanout value for a specific<br>command, for example to avoid flooding a remote service with concurrent<br>requests generated by that actual command.

The following example will launch up to ten puppet commands at...