# ClusterSSH: one console, many terminals, one stream of keystrokes

> ClusterSSH is a long-lived Perl tool that opens a terminal window to every host in a cluster and replicates whatever you type to all of them at once. Its value is in the details: cluster tags, an evaluate mode that shows connection errors before you commit, and a warning about what happens when you edit the same file on fifty machines at once.

**duncs/clusterssh** — Cluster SSH - Cluster Admin Via SSH

- Repository: https://github.com/duncs/clusterssh
- Website: https://github.com/duncs/clusterssh/wiki
- Stars: 989 · Forks: 75
- Language: Perl
- License: not declared
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/duncs-clusterssh

## The broadcast console and the tiled windows

The core idea is simple. The command opens an administration console and an xterm to all specified hosts. Any text typed into the administration console is replicated to all windows, and each window can also be typed into directly.

That last part is the design detail that makes the tool usable rather than merely impressive. The console is a broadcast channel, but the individual windows stay live, so you can watch the same command land on forty machines at once and see which one produced an error. The tool exists for cluster administration where the same configuration or commands must be run on each node, and the stated reason is that running them all at once keeps the nodes in sync.

Connections are opened using SSH, which must be correctly installed and configured, and the tool ships related utilities that share the same fan-out model with a different transport: ccon uses console as the communication method, crsh uses rsh, csftp uses sftp and ctel uses telnet.

The presentation is handled by a sub-menu system with a dotted line tear-off that turns a sub-menu into its own window, and there are configuration knobs for the layout. If your window manager menu bars are hidden behind the terminal windows, the screen_reserve options in the configuration file fix it, and if the terminals overlap too much, the terminal_reserve options handle that:

```bash
screen_reserve_XXXXX
terminal_reserve_XXXXX
```

## The options are what make it scriptable

The option set is large, and several of the entries exist for automation rather than for interactive comfort.

The action option runs a command in each session, so the tool can drop straight into an editor on every host:

```bash
cssh -a 'vi /etc/hosts'
```

The autoclose option sets how many seconds to wait before closing finished terminal windows, and the autoquit option makes the tool exit once the last client window closes. The cluster-file and tag-file options add extra files defining hosts and tags, and the config-file option adds an extra configuration file, so a site can keep its host list under version control somewhere else.

The options option passes arguments straight through to ssh, and it has a documented default of -x -o ConnectTimeout=10. The documentation advises putting ssh options into the ssh configuration file and $HOME/.ssh/config rather than the command line, which is the right advice for anything long. The term-args option does the same for the terminals, and the port option overrides the port used for connections.

Two options are about the host set itself. The unique-servers option connects to each host only once when a hostname appears several times, and the use-all-a-records option decides what happens when a hostname resolves to several addresses: connect to all of them or to just the first.

The list option prints available cluster tags and, given a tag, the hosts under it, with the output format changing when the quiet option is used. The dump-config option prints the current configuration in the same format as the configuration file, which is the fastest way to find out why a setting is not taking effect.

## Evaluate mode is the safety net before a wide fan-out

One option deserves more attention than the rest, and it is the evaluate option. It displays and evaluates the terminal and connection arguments to show any potential errors, and the hostname is required so that the evaluation can be performed.

Read that as a dry run. The tool will work out how it intends to open a terminal and how it intends to reach the host, using your terminal settings and your ssh configuration, and it will show you the problem before it opens forty windows that all fail in the same way. For example, replace `example.com` with one of your own hosts:

```bash
cssh -e example.com
```

The same section explains the two usual causes. One is the terminal option that enables AllowSendEvents, which some terminals need and others provide by another route, and the other is the configuration of ssh. So the troubleshooting story is: run it against one host, read the error, fix the terminal or the ssh configuration, and only then point it at the cluster.

The debug option complements this, taking either a level or a repeated flag with a maximum level of 9, and the man option shows the full help text while the basic help option shows the shorter version.

## The trap that catches everyone: editing the same file everywhere

The documentation contains a warning that deserves to be read twice. Extra caution should be taken when editing files, because lines may not necessarily be in the same order, so assuming line 5 is the same across all servers and modifying that is dangerous. The advice is to search for the specific line to be changed and to double check that all terminals show what you expect before the changes are committed.

This is the real weakness of the broadcast model, and it is a semantic one rather than a performance one. The tool guarantees that the same keystrokes reach every terminal. It cannot guarantee that the files in front of you are identical, that the line you have in mind is at the same offset on every host, or that a previous run left every machine in the same state. A sed expression that appends a host entry is safe in that setting. A text editor opened on fifty machines at once is not, because the editors may have opened at different positions and your keystrokes go somewhere different on each one.

The safer pattern is to use the action option with a scripted, idempotent change, and to use the console for inspection rather than for interactive editing. The tool is excellent at the first job and dangerous at the second, and the documentation is candid enough to say so.

## Unplugging a host without closing it

A small feature does more work than it looks like it does. Unchecking a hostname on the Hosts sub-menu unplugs the host from the cluster control window, so any text typed into the console is not sent to that host, and re-selecting it plugs it back in.

This turns the console from an all-or-nothing broadcast into a selective one. You can type at a group, notice that one machine is already at a different prompt state, and exclude it without tearing down the session or losing the window you have open. On a cluster where a node is being rebuilt or is already broken, that is the difference between a tool you keep using and one you stop trusting.

The sub-menu system also carries the tear-off behaviour: the dotted line on any sub-menu turns it into its own window, so you can pull the Hosts list out and park it beside the console. Both features point at the same intent, which is that the operator stays in control of what is connected while the tool handles the fan-out.

The history option shows history within the console window, which matters when you are scrolling back through a long sequence of broadcast commands and want to see exactly what was typed rather than retyping it.

## MaxStartups is the real limit on a large fan-out

If you connect to a large number of systems to reach a single system, for example to copy a file from many remote computers to one host, and those connections need password authentication, the sshd daemon on the far side may start refusing connections. The documented cause is that the number of connections exceeded the MaxStartups limit in sshd_config, which defaults to 10 if it is not set.

The documentation is careful to say that this is expected behaviour, and that sshd uses this mechanism to prevent denial of service attacks from unauthenticated sources. That framing matters: the tool is not misbehaving, and the fix is not to disable the limit. The guidance is to tune sshd_config and reload the SSH daemon, or to use the authorized_keys mechanism in the home directory instead of password authentication.

The key based route is the better answer for a cluster tool, and it is the same answer for a different reason. Password authentication means every one of the N simultaneous connections is an unauthenticated connection until the password is typed, and that is exactly the state MaxStartups is designed to limit. With keys, the connections authenticate immediately, and the burst looks like an ordinary burst of established sessions.

This is the single operational fact to take away from the documentation: ClusterSSH scales with the number of hosts you open, and the limit that will bite first is on the server side, in a configuration file you do not control from the tool.

## A mature Perl project with no releases and no stated licence

The project is old in the way that a tool with an installed base is old, and the repository layout shows a conventional Perl distribution. There is a Build.PL, a dist.ini for Dist::Zilla, a bin_PL directory for the executable scripts, a lib directory for the modules, a t directory for the test suite, and the usual housekeeping files: Changes, TODO, AUTHORS, THANKS and a README.

The documentation identifies itself as being for version 4.18, which gives you a sense of the release cadence without a tag to point at, since the repository has no GitHub releases. The last push was on 2026-04-28 and the project is not archived.

The licence is the item to check yourself. The project does not state one, and for a tool that is installed on operations machines, usually through a system package manager, that gap matters more than usual. Read the LICENSE situation in the repository before you redistribute it or bake it into an image.

The home page is the project's wiki, which is the right place to look for the tag file format, the configuration file layout and the list of known bugs that the documentation refers to. For an operator picking this up, the combination of the man page, the wiki and the evaluate option is enough to get a first session working against a handful of hosts within a few minutes.

## Conclusion

ClusterSSH earns its place in any operations toolkit where the same command has to run on many machines and where SSH key authentication is already set up, because the broadcast console removes a loop of ssh sessions and the tag files make the target set reproducible. It is the wrong tool for editing the same file across a cluster, where the documentation itself warns that line order is not guaranteed, and it will hit the sshd MaxStartups limit on a large fan-out with password authentication. Before you use it on a wide cluster, tune MaxStartups in sshd_config, switch to the authorized_keys mechanism, and run a single host through the evaluate option to see how your terminal and ssh configuration are being interpreted.

## FAQ

### What does ClusterSSH do exactly?

It opens an administration console and an xterm window to every specified host, replicates anything typed in the console to all of them, and also lets you type into each window directly. Connections are made with SSH, and the tool is aimed at cluster administration where the same command has to run on every node.

### How do I test ClusterSSH connections before running it on a whole cluster?

Use the evaluate option with a single host name, for example cssh -e {single host name}. It displays and evaluates the terminal and connection arguments and shows any potential errors before the windows are opened.

### Why do my SSH connections get refused on a large ClusterSSH fan-out?

The sshd daemon on the far side limits unauthenticated connections through the MaxStartups setting in sshd_config, which defaults to 10. The documentation calls this expected behaviour and advises tuning sshd_config and reloading the daemon, or authenticating with the authorized_keys mechanism instead of a password.

### Is it safe to edit the same file on every host with ClusterSSH?

The documentation warns against it, because lines may not be in the same order on every server, so editing by line number is dangerous. The recommended approach is to search for the specific line and to check every terminal shows what you expect before the changes are committed.

## Sources

- [duncs/clusterssh on GitHub](https://github.com/duncs/clusterssh)
- [Issues](https://github.com/duncs/clusterssh/issues)
- [Project website](https://github.com/duncs/clusterssh/wiki)
- [README](https://github.com/duncs/clusterssh/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/duncs-clusterssh