1CSSH(1)               User Contributed Perl Documentation              CSSH(1)
2
3
4

NAME

6       cssh - Cluster administration tool
7

VERSION

9       This documentation is for version: 4.13.2
10

SYNOPSIS

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

DESCRIPTION

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
25       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
30       Connections are opened using ssh which must be correctly installed and
31       configured.
32
33       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
39   Further Notes
40       Please also see "KNOWN BUGS".
41
42       ·   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
45       ·   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
49       ·   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
53       ·   If the terminals overlap too much see the "terminal_reserve_XXXXX"
54           options in the $HOME/.clusterssh/config file (see "FILES").
55
56       ·   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
69       ·   If client windows fail to open, try running:
70
71           "cssh -e {single host name}"
72
73           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

OPTIONS

80       Some of these options may also be defined within the configuration
81       file.  Default options are shown as appropriate.
82
83       --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
87       --autoclose <seconds>, -K <seconds>
88           Number of seconds to wait before closing finished terminal windows.
89
90       --autoquit, -q
91           Toggle automatically quiting after the last client window has
92           closed (overriding the config file).
93
94       --cluster-file '<filename>', -c '<filename>'
95           Use supplied file as additional cluster file (see also "FILES").
96
97       --cols <cols>, -x <cols>
98           Number of columns
99
100       --config-file '<filename>', -C '<filename>'
101           Use supplied file as additional configuration file (see also
102           "FILES").
103
104       --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
108       --dump-config, -d
109           Dump the current configuration in the same format used by the
110           $HOME/.clusterssh/config file.
111
112       --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
117       --fillscreen
118           Resize terminal windows to fill the whole available screen
119
120       --font '<font>', -f '<font>'
121           Specify the font to use in the terminal windows. Use standard X
122           font notation such as "5x8".
123
124       --help, -h
125           Show basic help text and exit
126
127       --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
132       --man, -H
133           Show full help text (the man page) and exit
134
135       --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
141           Default: -x -o ConnectTimeout=10
142
143       --port <port>, -p <port>
144           Specify an alternate port for connections.
145
146       --quiet, -Q
147           Do not output extra text when using some options
148
149       --rows <rows>, -y <rows>
150           Number of rows
151
152       --show-history, -s
153           Show history within console window.
154
155       --tag-file '<filename>', -r '<filename>'
156           Use supplied file as additional tag file (see also "FILES")
157
158       --term-args '<STRING>', -t '<STRING>'
159           Specify arguments to be passed to terminals being used.
160
161       --tile, -g
162           Toggle window tiling (overriding the config file).
163
164       --title '<title>', -T '<title>'
165           Specify the initial part of the title used in the console and
166           client windows.
167
168       --unique-servers, -u
169           Toggle connecting to each host only once when a hostname has been
170           specified multiple times.
171
172       --usage, -?
173           Show synopsis and exit
174
175       --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
180       --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
185       --version, -v
186           Show version information and exit
187

ARGUMENTS

189       The following arguments are supported:
190
191       [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
196       <tag> ...
197           Open a series of xterms defined by <tag> in one of the
198           supplementary configuration files (see "FILES").
199
200           Note: specifying a username on a cluster tag will override any
201           usernames defined in the cluster.
202

KEY SHORTCUTS

204       The following key shortcuts are available within the console window,
205       and all of them may be changed via the configuration files.
206
207       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
211       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
215           "scp /etc/hosts server:files/<Alt-n>.hosts"
216
217           would replace the <Alt-n> with the client's name in each window.
218
219       Alt-l
220           Paste in the hostname of the server cssh is being run on
221
222       Alt-q
223           Quit the program and close all connections and windows.
224
225       Alt-r
226           Retile all the client windows.
227
228       Alt-u
229           Paste in the username for the connection
230

EXAMPLES

232       Open up a session to 3 servers
233           $ cssh server1 server2 server3
234
235       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
240       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
246       Open up a cluster defined in a non-default configuration file
247           $ cssh -c $HOME/cssh.extra_clusters db_cluster
248
249       Override the configured/default port to use 2022 instead
250           $ cssh -p 2022 server1 server2
251

FILES

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
259           <tag> [user@]<server>[:port] [user@]<server>[:port] [...]
260
261           e.g.
262
263               # List of servers in live
264               live admin1@server1 admin2@server2:2022 server3 server4
265
266           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
270           Servers can be defined using expansion macros:
271
272           "webservers websvr{a,b,c}"
273
274           would be expanded to
275
276           "webservers websvra websvrb websvrc"
277
278           and
279
280           "webservers websvr{6..9}"
281
282           would be expanded to
283
284           "webservers websvr6 websvr7 websvr8 websvr9"
285
286           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
291           NOTE: the last tag read overwrites any pre-existing tag of that
292           name.
293
294           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
298       /etc/tags, $HOME/.clusterssh/tags
299           Very similar to clusters files but the definition is reversed.  The
300           format is:
301
302           <host> <tag> [...]
303
304           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
307           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
311           NOTE: All tags are added together
312
313       /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
318           NOTE: values for entries do not need to be quoted unless it is
319           required for passing arguments, e.g.
320
321           "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""
322
323           should be written as
324
325           "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"
326
327           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
332           auto_quit = 1
333               Automatically quit after the last client window closes.  Set to
334               0 to disable.  See also --autoquit
335
336           auto_wm_decoration_offsets = no
337               Enable or disable alternative algorithm for calculating
338               terminal positioning.
339
340           comms = ssh
341               Sets the default communication method (initially taken from the
342               name of the program, but can be overridden here).
343
344           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
350           external_command_mode = 0600
351               File mode bits for the external_command_pipe.
352
353           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
358               Commands:
359
360               "open <tag|hostname>" - open new sessions to provided tag or
361               hostname
362
363               "retile" - force window retiling
364
365               e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>
366
367           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
374               A non-0 exit code will be counted as an error, a warning will
375               be printed and output ignored.
376
377               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
381           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
387               "extra_cluster_file = ~/clusters, $HOME/clus"
388
389           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
395               "extra_tag_file = ~/tags, $HOME/tags"
396
397           key_addhost = Control-Shift-plus
398               Default key sequence to open AddHost menu.  See "KEY SHORTCUTS"
399               for more information.
400
401           hide_menu = 0
402               If set to 1, hide the menu bar (File, Hosts, Send, Help) in the
403               console.
404
405           key_clientname = Alt-n
406               Default key sequence to send cssh client names to client.  See
407               "KEY SHORTCUTS" for more information.
408
409           key_localname = Alt-l
410               Default key sequence to send hostname of local server to
411               client.  See "KEY SHORTCUTS" for more information.
412
413           key_paste = Control-v
414               Default key sequence to paste text into the console window.
415               See "KEY SHORTCUTS" for more information.
416
417           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
421           key_retilehosts = Alt-r
422               Default key sequence to retile host windows.  See "KEY
423               SHORTCUTS" for more information.
424
425           key_username = Alt-u
426               Default key sequence to send username to client.  See "KEY
427               SHORTCUTS" for more information.
428
429           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
437           macros_enabled = yes
438               Enable or disable macro replacement.  Note: this affects all
439               the "macro_*" variables above.
440
441           max_addhost_menu_cluster_items = 6
442               Maximum number of entries in the 'Add Host' menu cluster list
443               before scrollbars are used
444
445           max_host_menu_items = 30
446               Maximum number of hosts to put into the host menu before
447               starting a new column
448
449           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
454           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
458           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
464           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
470               NOTE: The given defaults are based on OpenSSH, not commercial
471               ssh software.
472
473               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
477           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
487           terminal = /path/to/xterm
488               Path to the X-Windows terminal used for the client.
489
490           terminal_args = <blank>
491               Arguments to use when opening terminal windows.  Otherwise
492               takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.
493
494           terminal_chdir = 0
495               When non-0, set the working directory for each terminal as per
496               'terminal_chdir_path'
497
498           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
504           terminal_font = 6x13
505               Font to use in the terminal windows.  Use standard X font
506               notation.
507
508           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
517           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
526           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
533           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
538           terminal_title_opt = -T
539               Option used with "terminal" to set the title of the window
540
541           terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
542               Option required by the terminal to allow XSendEvents to be
543               received
544
545           title = cssh
546               Title of windows to use for both the console and terminals.
547
548           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
555           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
560           use_hotkeys = 1
561               Setting to 0 will disable all hotkeys.
562
563           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
569           user = $LOGNAME
570               Sets the default user for running commands on clients.
571
572           window_tiling = 1
573               Perform window tiling (set to 0 to disable)
574
575           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
580           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
585       $HOME/.clusterssh/send_menu
586           This (optional) file contains items to populate the send menu.  The
587           default entry could be written as:
588
589             <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
611           Submenus can also be specified as follows:
612
613             <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
623           Caveats:
624
625           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
629           The following replacement macros are available (note: these can be
630           changed in the configuration file):
631
632           %s  Hostname part of the specific connection string to each client,
633               minus any username or port
634
635           %u  Username part of the connection string to each client
636
637           %h  Hostname of server where cssh is being run from
638
639           %n  "RETURN" code
640
641           NOTE: requires XML::Simple to be installed
642

KNOWN BUGS

644       If you have any ideas about how to fix the below bugs, please get in
645       touch and/or provide a patch.
646
647       ·   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

TROUBLESHOOTING

654       If you have issues running cssh, first try:
655
656       "cssh -e [user@]<hostname>[:port]"
657
658       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
662       1.  Test the terminal window works with the options provided
663
664       2.  Test ssh works to a host with the configured arguments
665
666       Configuration options to watch for in ssh are:
667
668       ·   SSH doesn't understand "-o ConnectTimeout=10" - remove the option
669           from the $HOME/.clusterssh/config file
670
671       ·   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

SUPPORT AND REPORTING BUGS

676       A web site for comments, requests, bug reports and bug fixes/patches is
677       available at: <https://github.com/duncs/clusterssh>
678
679       If you require support, please run the following commands and create an
680       issue via: <https://github.com/duncs/clusterssh/issues>
681
682       "perl -V"
683
684       "perl -MTk -e 'print $Tk::VERSION,$/'"
685
686       "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
687
688       "cat /etc/csshrc $HOME/.clusterssh/config"
689
690       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

SEE ALSO

697       <https://github.com/duncs/clusterssh/wiki/>, "ssh", Tk::overview,
698       X11::Protocol, "perl"
699

AUTHOR

701       Duncan Ferguson, "<duncan_j_ferguson at yahoo.co.uk>"
702
704       Copyright 1999-2018 Duncan Ferguson.
705
706       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
710       See http://dev.perl.org/licenses/ for more information.
711
712
713
714perl v5.28.1                      2019-01-31                           CSSH(1)
Impressum