1CSSH(1) User Contributed Perl Documentation CSSH(1)
2
6 cssh - Cluster administration tool
7
9 This documentation is for version: 4.13.2
10
12 cssh [-a '<command>'] [-K <seconds>] [-q] [-c '<filename>'] [-x <cols>]
13 [-C '<filename>'] [--debug [[...] || <INTEGER>]] [-d] [-e
14 '<[user@]<host>[:port]>'] [--fillscreen] [-f '<font>'] [-h] [-L
15 '[tag]'] [-H] [-o '<STRING>'] [-p <port>] [-Q] [-y <rows>] [-s] [-r
16 '<filename>'] [-t '<STRING>'] [-g] [-T '<title>'] [-u] [-?] [-A] [-l
17 '<username>'] [-v]
18
20 The command opens an administration console and an xterm to all
21 specified hosts. Any text typed into the administration console is
22 replicated to all windows. All windows may also be typed into
23 directly.
24 This tool is intended for (but not limited to) cluster administration
26 where the same configuration or commands must be run on each node
27 within the cluster. Performing these commands all at once via this
28 tool ensures all nodes are kept in sync.
29 Connections are opened using ssh which must be correctly installed and
31 configured.
32 Extra caution should be taken when editing files as lines may not
34 necessarily be in the same order; assuming line 5 is the same across
35 all servers and modifying that is dangerous. It's better to search for
36 the specific line to be changed and double-check all terminals are as
37 expected before changes are committed.
38 Further Notes
40 Please also see "KNOWN BUGS".
41 · The dotted line on any sub-menu is a tear-off, i.e. click on it and
43 the sub-menu is turned into its own window.
44 · Unchecking a hostname on the Hosts sub-menu will unplug the host
46 from the cluster control window, so any text typed into the console
47 is not sent to that host. Re-selecting it will plug it back in.
48 · If your window manager menu bars are obscured by terminal windows
50 see the "screen_reserve_XXXXX" options in the
51 $HOME/.clusterssh/config file (see "FILES").
52 · If the terminals overlap too much see the "terminal_reserve_XXXXX"
54 options in the $HOME/.clusterssh/config file (see "FILES").
55 · When using ClusterSSH on a large number of systems to connect to a
57 single system using an SSH utility (e.g. you issue a command to to
58 copy a file using scp from the remote computers to a single host)
59 and when these connections require authentication (i.e. you are
60 going to authenticate with a password), the sshd daemon at that
61 location may refuse connections after the number "MaxStartups"
62 limit in sshd_config is exceeded. (If this value is not set, it
63 defaults to 10). This is expected behavior; sshd uses this
64 mechanism to prevent DoS attacks from unauthenticated sources.
65 Please tune sshd_config and reload the SSH daemon, or consider
66 using the ~/.ssh/authorized_keys mechanism for authentication if
67 you encounter this problem.
68 · If client windows fail to open, try running:
70 "cssh -e {single host name}"
72 This will test the mechanisms used to open windows to hosts. This
74 could be due to either the "-xrm" terminal option which enables
75 "AllowSendEvents" (some terminals do not require this option, other
76 terminals have another method for enabling it - see your terminal
77 documentation) or the configuration of "ssh".
78
80 Some of these options may also be defined within the configuration
81 file. Default options are shown as appropriate.
82 --action '<command>', -a '<command>'
84 Run the command in each session, e.g. "-a 'vi /etc/hosts'" to drop
85 straight into a vi session.
86 --autoclose <seconds>, -K <seconds>
88 Number of seconds to wait before closing finished terminal windows.
89 --autoquit, -q
91 Toggle automatically quiting after the last client window has
92 closed (overriding the config file).
93 --cluster-file '<filename>', -c '<filename>'
95 Use supplied file as additional cluster file (see also "FILES").
96 --cols <cols>, -x <cols>
98 Number of columns
99 --config-file '<filename>', -C '<filename>'
101 Use supplied file as additional configuration file (see also
102 "FILES").
103 --debug [[...] || <INTEGER>]
105 Enable debugging. Either a level can be provided or the option can
106 be repeated multiple times. Maximum level is 9.
107 --dump-config, -d
109 Dump the current configuration in the same format used by the
110 $HOME/.clusterssh/config file.
111 --evaluate '<[user@]<host>[:port]>', -e '<[user@]<host>[:port]>'
113 Display and evaluate the terminal and connection arguments to
114 display any potential errors. The <hostname> is required to aid
115 the evaluation.
116 --fillscreen
118 Resize terminal windows to fill the whole available screen
119 --font '<font>', -f '<font>'
121 Specify the font to use in the terminal windows. Use standard X
122 font notation such as "5x8".
123 --help, -h
125 Show basic help text and exit
126 --list '[tag]', -L '[tag]'
128 List available cluster tags. Tag is optional. If a tag is provided
129 then hosts for that tag are listed. NOTE: format of output changes
130 when using "--quiet" or "-Q" option.
131 --man, -H
133 Show full help text (the man page) and exit
134 --options '<STRING>', -o '<STRING>'
136 Specify arguments to be passed to ssh when making the connection.
137 NOTE: options for ssh should normally be put into the ssh
138 configuration file; see "ssh_config" and $HOME/.ssh/config for more
139 details.
140 Default: -x -o ConnectTimeout=10
142 --port <port>, -p <port>
144 Specify an alternate port for connections.
145 --quiet, -Q
147 Do not output extra text when using some options
148 --rows <rows>, -y <rows>
150 Number of rows
151 --show-history, -s
153 Show history within console window.
154 --tag-file '<filename>', -r '<filename>'
156 Use supplied file as additional tag file (see also "FILES")
157 --term-args '<STRING>', -t '<STRING>'
159 Specify arguments to be passed to terminals being used.
160 --tile, -g
162 Toggle window tiling (overriding the config file).
163 --title '<title>', -T '<title>'
165 Specify the initial part of the title used in the console and
166 client windows.
167 --unique-servers, -u
169 Toggle connecting to each host only once when a hostname has been
170 specified multiple times.
171 --usage, -?
173 Show synopsis and exit
174 --use-all-a-records, -A
176 If a hostname resolves to multiple IP addresses, toggle whether or
177 not to connect to all of them, or just the first one (see also
178 config file entry).
179 --username '<username>', -l '<username>'
181 Specify the default username to use for connections (if different
182 from the currently logged in user). NOTE: will be overridden by
183 <user>@<host>.
184 --version, -v
186 Show version information and exit
187
189 The following arguments are supported:
190 [user@]<hostname>[:port] ...
192 Open an xterm to the given hostname and connect to the
193 administration console. The optional port number can be used if
194 the server is not listening on the standard port.
195 <tag> ...
197 Open a series of xterms defined by <tag> in one of the
198 supplementary configuration files (see "FILES").
199 Note: specifying a username on a cluster tag will override any
201 usernames defined in the cluster.
202
204 The following key shortcuts are available within the console window,
205 and all of them may be changed via the configuration files.
206 Control-Shift-plus
208 Open the 'Add Host(s) or Cluster(s)' dialogue box. Multiple host
209 or cluster names can be entered, separated by spaces.
210 Alt-n
212 Paste in the hostname part of the specific connection string to
213 each client, minus any username or port, e.g.
214 "scp /etc/hosts server:files/<Alt-n>.hosts"
216 would replace the <Alt-n> with the client's name in each window.
218 Alt-l
220 Paste in the hostname of the server cssh is being run on
221 Alt-q
223 Quit the program and close all connections and windows.
224 Alt-r
226 Retile all the client windows.
227 Alt-u
229 Paste in the username for the connection
230
232 Open up a session to 3 servers
233 $ cssh server1 server2 server3
234 Open up a session to a cluster of servers identified by the tag 'farm1'
236 and give the controlling window a specific title, where the tag is
237 defined in one of the default configuration files
238 $ cssh -T 'Web Farm Cluster 1' farm1
239 Connect to different servers using different login names. NOTE: this
241 can also be achieved by setting up appropriate options in the
242 configuration files. Do not close the console when the last terminal
243 exits.
244 $ cssh user1@server1 admin@server2
245 Open up a cluster defined in a non-default configuration file
247 $ cssh -c $HOME/cssh.extra_clusters db_cluster
248 Override the configured/default port to use 2022 instead
250 $ cssh -p 2022 server1 server2
251
253 /etc/clusters, $HOME/.clusterssh/clusters
254 These files contain a list of tags to server names mappings. When
255 any name is used on the command line it is checked to see if it is
256 a tag. If it is a tag, then the tag is replaced with the list of
257 servers. The format is as follows:
258 <tag> [user@]<server>[:port] [user@]<server>[:port] [...]
260 e.g.
262 # List of servers in live
264 live admin1@server1 admin2@server2:2022 server3 server4
265 All comments (marked by a #) and blank lines are ignored. Tags may
267 be nested, but be aware of using recursive tags as they are not
268 checked for.
269 Servers can be defined using expansion macros:
271 "webservers websvr{a,b,c}"
273 would be expanded to
275 "webservers websvra websvrb websvrc"
277 and
279 "webservers websvr{6..9}"
281 would be expanded to
283 "webservers websvr6 websvr7 websvr8 websvr9"
285 Extra cluster files may also be specified either as an option on
287 the command line (see "cluster-file") or in the user's
288 $HOME/.clusterssh/config file (see "extra_cluster_file"
289 configuration option).
290 NOTE: the last tag read overwrites any pre-existing tag of that
292 name.
293 NOTE: there is a special cluster tag called "default" - any tags or
295 hosts included within this tag will be automatically opened if
296 nothing is specified on the command line.
297 /etc/tags, $HOME/.clusterssh/tags
299 Very similar to clusters files but the definition is reversed. The
300 format is:
301 <host> <tag> [...]
303 This allows one host to be specified as a member of a number of
305 tags. This format can be clearer than using clusters files.
306 Extra tag files may be specified either as an option (see
308 "tag-file") or within the user's $HOME/.clusterssh/config file (see
309 "extra_tag_file" configuration option).
310 NOTE: All tags are added together
312 /etc/csshrc & $HOME/.clusterssh/config
314 This file contains configuration overrides - the defaults are as
315 marked. Default options are overwritten first by the global file,
316 and then by the user file.
317 NOTE: values for entries do not need to be quoted unless it is
319 required for passing arguments, e.g.
320 "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""
322 should be written as
324 "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"
326 auto_close = 5
328 Close terminal window after this many seconds. If set to 0
329 will instead wait on input from the user in each window before
330 closing. See also --autoclose and --no-autoclose
331 auto_quit = 1
333 Automatically quit after the last client window closes. Set to
334 0 to disable. See also --autoquit
335 auto_wm_decoration_offsets = no
337 Enable or disable alternative algorithm for calculating
338 terminal positioning.
339 comms = ssh
341 Sets the default communication method (initially taken from the
342 name of the program, but can be overridden here).
343 console_position = <null>
345 Set the initial position of the console - if empty then let the
346 window manager decide. Format is '+<x>+<y>', i.e. '+0+0' is
347 top left hand corner of the screen, '+0-70' is bottom left hand
348 side of screen (more or less).
349 external_command_mode = 0600
351 File mode bits for the external_command_pipe.
352 external_command_pipe = <null>
354 Define the full path to an external command pipe that can be
355 written to for controlling some aspects of ClusterSSH, such as
356 opening sessions to more clusters.
357 Commands:
359 "open <tag|hostname>" - open new sessions to provided tag or
361 hostname
362 "retile" - force window retiling
364 e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>
366 external_cluster_command = <null>
368 Define the full path to an external command that can be used to
369 resolve tags to host names. This command can be written in any
370 language. The script must accept a list of tags to resolve and
371 output a list of hosts (space separated on a single line). Any
372 tags that cannot be resolved should be returned unchanged.
373 A non-0 exit code will be counted as an error, a warning will
375 be printed and output ignored.
376 If the external command is given a "-L" option it should output
378 a list of tags (space separated on a single line) it can
379 resolve
380 extra_cluster_file = <null>
382 Define an extra cluster file in the format of /etc/clusters.
383 Multiple files can be specified, separated by commas. Both ~
384 and $HOME are acceptable as a reference to the user's home
385 directory, e.g.
386 "extra_cluster_file = ~/clusters, $HOME/clus"
388 extra_tag_file = <null>
390 Define an extra tag file in the format of /etc/tags. Multiple
391 files can be specified, separated by commas. Both ~ and $HOME
392 are acceptable as a reference to the user's home directory,
393 e.g.
394 "extra_tag_file = ~/tags, $HOME/tags"
396 key_addhost = Control-Shift-plus
398 Default key sequence to open AddHost menu. See "KEY SHORTCUTS"
399 for more information.
400 hide_menu = 0
402 If set to 1, hide the menu bar (File, Hosts, Send, Help) in the
403 console.
404 key_clientname = Alt-n
406 Default key sequence to send cssh client names to client. See
407 "KEY SHORTCUTS" for more information.
408 key_localname = Alt-l
410 Default key sequence to send hostname of local server to
411 client. See "KEY SHORTCUTS" for more information.
412 key_paste = Control-v
414 Default key sequence to paste text into the console window.
415 See "KEY SHORTCUTS" for more information.
416 key_quit = Control-q
418 Default key sequence to quit the program (will terminate all
419 open windows). See "KEY SHORTCUTS" for more information.
420 key_retilehosts = Alt-r
422 Default key sequence to retile host windows. See "KEY
423 SHORTCUTS" for more information.
424 key_username = Alt-u
426 Default key sequence to send username to client. See "KEY
427 SHORTCUTS" for more information.
428 macro_servername = %s
430 macro_hostname = %h
431 macro_username = %u
432 macro_newline = %n
433 macro_version = %v
434 Change the replacement macro used when either using a 'Send'
435 menu item, or when pasting text into the main console.
436 macros_enabled = yes
438 Enable or disable macro replacement. Note: this affects all
439 the "macro_*" variables above.
440 max_addhost_menu_cluster_items = 6
442 Maximum number of entries in the 'Add Host' menu cluster list
443 before scrollbars are used
444 max_host_menu_items = 30
446 Maximum number of hosts to put into the host menu before
447 starting a new column
448 menu_host_autotearoff = 0
450 menu_send_autotearoff = 0
451 When set to non-0 will automatically tear-off the host or send
452 menu at program start
453 mouse_paste = Button-2 (middle mouse button)
455 Default key sequence to paste text into the console window
456 using the mouse. See "KEY SHORTCUTS" for more information.
457 rsh = /path/to/rsh
459 ssh = /path/to/ssh
460 telnet = /path/to/telnet
461 Set the path to the specific binary to use for the
462 communication method, else uses the first match found in $PATH
463 rsh_args = <blank>
465 ssh_args = "-x -o ConnectTimeout=10"
466 telnet_args = <blank>
467 Sets any arguments to be used with the communication method
468 (defaults to ssh arguments).
469 NOTE: The given defaults are based on OpenSSH, not commercial
471 ssh software.
472 NOTE: Any "generic" change to the method (e.g., specifying the
474 ssh port to use) should be done in the medium's own config file
475 (see "ssh_config" and $HOME/.ssh/config).
476 screen_reserve_top = 0
478 screen_reserve_bottom = 60
479 screen_reserve_left = 0
480 screen_reserve_right = 0
481 Number of pixels from the screen's side to reserve when
482 calculating screen geometry for tiling. Setting this to
483 something like 50 will help keep cssh from positioning windows
484 over your window manager's menu bar if it draws one at that
485 side of the screen.
486 terminal = /path/to/xterm
488 Path to the X-Windows terminal used for the client.
489 terminal_args = <blank>
491 Arguments to use when opening terminal windows. Otherwise
492 takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.
493 terminal_chdir = 0
495 When non-0, set the working directory for each terminal as per
496 'terminal_chdir_path'
497 terminal_chdir_path = $HOME/.clusterssh/work/%s
499 Path to use as working directory for each terminal when
500 'terminal_chdir' is enabled. The path provided is passed
501 through the macro parser (see the section above on
502 'macros_enabled'.
503 terminal_font = 6x13
505 Font to use in the terminal windows. Use standard X font
506 notation.
507 terminal_reserve_top = 5
509 terminal_reserve_bottom = 0
510 terminal_reserve_left = 5
511 terminal_reserve_right = 0
512 Number of pixels from the terminal's side to reserve when
513 calculating screen geometry for tiling. Setting these will
514 help keep cssh from positioning windows over your scroll and
515 title bars or otherwise overlapping the windows too much.
516 terminal_colorize = 1
518 If set to 1 (the default), then "-bg" and "-fg" arguments will
519 be added to the terminal invocation command-line. The terminal
520 will be colored in a pseudo-random way based on the host name;
521 while the color of a terminal is not easily predicted, it will
522 always be the same color for a given host name. After a while,
523 you will recognize hosts by their characteristic terminal
524 color.
525 terminal_bg_style = dark
527 If set to "dark", the terminal background will be set to black
528 and the foreground to the pseudo-random color. If set to
529 "light", then the foreground will be black and the background
530 the pseudo-random color. If terminal_colorize is "zero", then
531 this option has no effect.
532 terminal_size = 80x24
534 Initial size of terminals to use. NOTE: the number of lines
535 (24) will be decreased when resizing terminals for tiling, not
536 the number of characters (80).
537 terminal_title_opt = -T
539 Option used with "terminal" to set the title of the window
540 terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
542 Option required by the terminal to allow XSendEvents to be
543 received
544 title = cssh
546 Title of windows to use for both the console and terminals.
547 unmap_on_redraw = no
549 Tell Tk to use the UnmapWindow request before redrawing
550 terminal windows. This defaults to "no" as it causes some
551 problems with the FVWM window manager. If you are experiencing
552 problems with redraws, you can set it to "yes" to allow the
553 window to be unmapped before it is repositioned.
554 use_all_a_records = 0
556 If a hostname resolves to multiple IP addresses, set to 1 to
557 connect to all of them, not just the first one found. See also
558 "--use-all-a-records"}
559 use_hotkeys = 1
561 Setting to 0 will disable all hotkeys.
562 use_natural_sort = 0
564 Windows will normally sort in alphabetical order, i.e.: host1,
565 host11, host2. Setting to this 1 will change the sort order,
566 i.e.: host1, host2, host11. NOTE: You must have the perl module
567 Sort::Naturally installed.
568 user = $LOGNAME
570 Sets the default user for running commands on clients.
571 window_tiling = 1
573 Perform window tiling (set to 0 to disable)
574 window_tiling_direction = right
576 Direction to tile windows, where "right" means starting top
577 left and moving right and then down, and anything else means
578 starting bottom right and moving left and then up
579 NOTE: The key shortcut modifiers must be in the form "Control",
581 "Alt" or "Shift", e.g. with the first letter capitalised and the
582 rest lower case. Keys may also be disabled individually by setting
583 to the word "null".
584 $HOME/.clusterssh/send_menu
586 This (optional) file contains items to populate the send menu. The
587 default entry could be written as:
588 <send_menu>
590 <menu title="Use Macros">
591 <toggle/>
592 <accelerator>ALT-p</accelerator>
593 </menu>
594 <menu title="Remote Hostname">
595 <command>%s</command>
596 <accelerator>ALT-n</accelerator>
597 </menu>
598 <menu title="Local Hostname">
599 <command>%s</command>
600 <accelerator>ALT-l</accelerator>
601 </menu>
602 <menu title="Username">
603 <command>%u</command>
604 <accelerator>ALT-u</accelerator>
605 </menu>
606 <menu title="Test Text">
607 <command>echo "ClusterSSH Version: %v%n</command>
608 </menu>
609 </send_menu>
610 Submenus can also be specified as follows:
612 <send_menu>
614 <menu title="Default Entries">
615 <detach>yes</detach>
616 <menu title="Hostname">
617 <command>%s</command>
618 <accelerator>ALT-n</accelerator>
619 </menu>
620 </menu>
621 </send_menu>
622 Caveats:
624 There is currently no strict format checking of this file.
626 The format of the file may change in the future
627 If the file exists, the default entry (Hostname) is not added
628 The following replacement macros are available (note: these can be
630 changed in the configuration file):
631 %s Hostname part of the specific connection string to each client,
633 minus any username or port
634 %u Username part of the connection string to each client
636 %h Hostname of server where cssh is being run from
638 %n "RETURN" code
640 NOTE: requires XML::Simple to be installed
642
644 If you have any ideas about how to fix the below bugs, please get in
645 touch and/or provide a patch.
646 · Swapping virtual desktops can cause a redraw of all the terminal
648 windows. This is due to a lack of distinction within Tk between
649 switching desktops and minimising/maximising windows. Until Tk can
650 tell the difference between the two events, there is no fix (apart
651 from rewriting everything directly in X).
652
654 If you have issues running cssh, first try:
655 "cssh -e [user@]<hostname>[:port]"
657 This performs two tests to confirm cssh is able to work properly with
659 the settings provided within the $HOME/.clusterssh/config file (or
660 internal defaults).
661 1. Test the terminal window works with the options provided
663 2. Test ssh works to a host with the configured arguments
665 Configuration options to watch for in ssh are:
667 · SSH doesn't understand "-o ConnectTimeout=10" - remove the option
669 from the $HOME/.clusterssh/config file
670 · OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
672 or use "ForwardX11Trusted yes" in $HOME/.ssh/ssh_config (if you
673 change the default ssh options from "-x" to "-X")
674
676 A web site for comments, requests, bug reports and bug fixes/patches is
677 available at: <https://github.com/duncs/clusterssh>
678 If you require support, please run the following commands and create an
680 issue via: <https://github.com/duncs/clusterssh/issues>
681 "perl -V"
683 "perl -MTk -e 'print $Tk::VERSION,$/'"
685 "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
687 "cat /etc/csshrc $HOME/.clusterssh/config"
689 Using the debug option (--debug) will turn on debugging output. Repeat
691 the option to increase the amount of debug. However, if possible
692 please only use this option with one host at a time, e.g. "cssh --debug
693 <host>" due to the amount of output produced (in both main and child
694 windows).
695
697 <https://github.com/duncs/clusterssh/wiki/>, "ssh", Tk::overview,
698 X11::Protocol, "perl"
699
701 Duncan Ferguson, "<duncan_j_ferguson at yahoo.co.uk>"
702
704 Copyright 1999-2018 Duncan Ferguson.
705 This program is free software; you can redistribute it and/or modify it
707 under the terms of either: the GNU General Public License as published
708 by the Free Software Foundation; or the Artistic License.
709 See http://dev.perl.org/licenses/ for more information.
711perl v5.28.1 2019-01-31 CSSH(1)