1CSSH(1) User Contributed Perl Documentation CSSH(1)
2
6 cssh, crsh, ctel - Cluster administration tool
7
9 cssh [options] [[user@]<server>[:port]|<tag>] [...]
10 crsh [options] [[user@]<server>[:port]|<tag>] [...]
11 ctel [options] [<server>[:port]|<tag>] [...]
12
14 The command opens an administration console and an xterm to all
15 specified hosts. Any text typed into the administration console is
16 replicated to all windows. All windows may also be typed into
17 directly.
18 This tool is intended for (but not limited to) cluster administration
20 where the same configuration or commands must be run on each node
21 within the cluster. Performing these commands all at once via this
22 tool ensures all nodes are kept in sync.
23 Connections are opened via ssh so a correctly installed and configured
25 ssh installation is required. If, however, the program is called by
26 "crsh" then the rsh protocol is used (and the communications channel is
27 insecure), or by "ctel" then telnet is used.
28 Extra caution should be taken when editing system files such as
30 /etc/inet/hosts as lines may not necessarily be in the same order.
31 Assuming line 5 is the same across all servers and modifying that is
32 dangerous. Better to search for the specific line to be changed and
33 double-check before changes are committed.
34 Further Notes
36 Please also see "KNOWN BUGS".
37 · The dotted line on any sub-menu is a tear-off, i.e. click on it and
39 the sub-menu is turned into its own window.
40 · Unchecking a hostname on the Hosts sub-menu will unplug the host
42 from the cluster control window, so any text typed into the console
43 is not sent to that host. Re-selecting it will plug it back in.
44 · If your window manager menu bars are obscured by terminal windows
46 see the "screen_reserve_XXXXX" options in the csshrc file (see
47 "FILES").
48 · If the terminals overlap too much see the "terminal_reserve_XXXXX"
50 options in the csshrc file (see "FILES").
51 · If the code is called as crsh instead of cssh (i.e. a symlink
53 called crsh points to the cssh file or the file is renamed) rsh is
54 used as the communications protocol instead of ssh.
55 · If the code is called as ctel instead of cssh (i.e. a symlink
57 called ctel points to the cssh file or the file is renamed) telnet
58 is used as the communications protocol instead of ssh.
59 · When using cssh on a large number of systems to connect back to a
61 single system (e.g. you issue a command to the cluster to scp a
62 file from a given location) and when these connections require
63 authentication (i.e. you are going to authenticate with a
64 password), the sshd daemon at that location may refuse connects
65 after the number specified by MaxStartups in sshd_config is
66 exceeded. (If this value is not set, it defaults to 10.) This is
67 expected behavior; sshd uses this mechanism to prevent DoS attacks
68 from unauthenticated sources. Please tune sshd_config and reload
69 the SSH daemon, or consider using the ~/.ssh/authorized_keys
70 mechanism for authentication if you encounter this problem.
71 · If client windows fail to open, try running:
73 "cssh -e {single host name}"
75 This will test the mechanisms used to open windows to hosts. This
77 could be due to either the "-xrm" terminal option which enables
78 "AllowSendEvents" (some terminal do not require this option, other
79 terminals have another method for enabling it - see your terminal
80 documention) or the "ConnectTimeout" ssh option (see the
81 configuration option "-o" or file "csshrc" below to resolve this).
82
84 Some of these options may also be defined within the configuration
85 file. Default options are shown as appropriate.
86 --action,-a '<command>'
88 Run the command in each session, i.e. "-a 'vi /etc/hosts'" to drop
89 straight into a vi session. NOTE: not all communications methods
90 support this (ssh and rsh should, telnet will not).
91 --cluster-file,-c <file>
93 Use supplied file as additional cluster file (see also "FILES")
94 --config-file,-C <file>
96 Use supplied file as additional configuration file (see also
97 "FILES")
98 -d DEPRECATED. See '--debug'.
100 -D DEPRECATED. See '--debug'.
102 --debug [number].
104 Enable debugging. Either a level can be provided or the option can
105 be repeated multiple times. Maximum level is 4.
106 --evaluate,-e [user@]<hostname>[:port]
108 Display and evaluate the terminal and connection arguments so
109 display any potential errors. The <hostname> is required to aid
110 the evaluation.
111 --tile,-g|--no-tile,-G
113 Enable|Disable window tiling (overriding the config file)
114 --help,-h|-?
116 Show basic help text, and exit
117 --man,-H
119 Show full help test (the man page), and exit
120 --username,-l $LOGNAME
122 Specify the default username to use for connections (if different
123 from the currently logged in user). NOTE: will be overridden by
124 <user>@<host>
125 --options,-o "-x -o ConnectTimeout=10" - for ssh connections
127 --options,-o "" - for rsh connections
128 Specify arguments to be passed to ssh or rsh when making the
129 connection.
130 NOTE: any "generic" change to the method (i.e. specifying the ssh
132 port to use) should be done in the medium's own config file (see
133 ssh_config and $HOME/.ssh/config).
134 --port,-p <port>
136 Specify an alternate port for connections.
137 --autoquit,-q|--no-autoquit,-Q
139 Enable|Disable automatically quiting after the last client window
140 has closed (overriding the config file)
141 --show-history,-s
143 IN BETA: Show history within console window. This code is still
144 being worked upon, but may help some users.
145 --term-args,-t ""
147 Specify arguments to be passed to terminals being used
148 --title,-T "CSSH"
150 Specify the initial part of the title used in the console and
151 client windows
152 --output-config,-u
154 Output the current configuration in the same format used by the
155 $HOME/.csshrc file.
156 --version,-v
158 Show version information and exit
159
161 The following arguments are support:
162 [user@]<hostname>[:port] ...
164 Open an xterm to the given hostname and connect to the
165 administration console. An optional port number can be used if
166 sshd is not listening on standard port (e.g not listening on port
167 22) and ssh_config cannot be used.
168 <tag> ...
170 Open a series of xterms defined by <tag> within either
171 /etc/clusters or $HOME/.csshrc (see "FILES").
172 Note: specifying a username on a cluster tag will override any
174 usernames defined in the cluster
175
177 The following key shortcuts are available within the console window,
178 and all of them may be changed via the configuration files.
179 Control-q
181 Quit the program and close all connections and windows
182 Control-+
184 Open the 'Add Host(s) or Cluster(s)' dialogue box. Mutiple host or
185 cluster names can be entered, separated by spaces.
186 Alt-n
188 Paste in the hostname part of the specific connection string to
189 each client, minus any username or port, i.e.
190 "scp /etc/hosts server:files/<Alt-n>.hosts"
192 would replace the <Alt-n> with the client's name in each window
194 Alt-r
196 Retile all the client windows
197
199 Open up a session to 3 servers
200 $ cssh server1 server2 server3
201 Open up a session to a cluster of servers identified by the tag 'farm1'
203 and give the controlling window a specific title, where the cluster is
204 defined in one of the default configuration files
205 $ cssh -T 'Web Farm Cluster 1' farm1
206 Connect to different servers using different login names. NOTE: this
208 can also be achieved by setting up appropriate options in the
209 .ssh/config file. Do not close cssh when last terminal exits.
210 $ cssh -Q user1@server1 admin@server2
211 Open up a cluster defined in a non-default configuration file
213 $ cssh -c $HOME/cssh.config db_cluster
214 Use telnet on port 2022 instead of ssh
216 $ ctel -p 2022 server1 server2
217 Use rsh instead of ssh
219 $ crsh server1 server2
220
222 /etc/clusters
223 This file contains a list of tags to server names mappings. When
224 any name is used on the command line it is checked to see if it is
225 a tag. If it is a tag, then the tag is replaced with the list of
226 servers. The formated is as follows:
227 <tag> [user@]<server> [user@]<server> [...]
229 i.e.
231 # List of servers in live
233 live admin1@server1 admin2@server2 server3 server4
234 All comments (marked by a #) and blank lines are ignored. Tags may
236 be nested, but be aware of recursive tags which are not checked
237 for.
238 Clusters may also be specified either directly (see "clusters"
240 configuration options) or indirectly (see "extra_cluster_file"
241 configuration option) in the users $HOME/.csshrc file.
242 NOTE: there is a special cluster tag called "default" - any tags or
244 hosts included within this tag will be automatically opened if no
245 other tags are specified on the command line.
246 /etc/csshrc & $HOME/.csshrc
248 This file contains configuration overrides - the defaults are as
249 marked. Default options are overwritten first by the global file,
250 and then by the user file.
251 NOTE: values for entries do not need to be quoted unless it is
253 required for passing arguments, i.e.
254 terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'"
256 should be written as
258 terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'
260 always_tile = yes
262 Setting to anything other than "yes" does not perform window
263 tiling (see also -G).
264 auto_quit = yes
266 Automatically quit after the last client window closes. Set to
267 anything other than "yes" to disable. Can be overridden by
268 "-Q" on the command line.
269 clusters = <blank>
271 Define a number of cluster tags in addition to (or to replace)
272 tags defined in the /etc/clusters file. The format is:
273 clusters = <tag1> <tag2> <tag3>
275 <tag1> = host1 host2 host3
276 <tag2> = user@host4 user@host5 host6
277 <tag3> = <tag1> <tag2>
278 As with the /etc/clusters file, be sure not to create
280 recursivly nested tags.
281 comms = ssh
283 Sets the default communication method (initially taken from the
284 name of program, but can be overridden here).
285 console_position = <null>
287 Set the initial position of the console - if empty then let the
288 window manager decide. Format is '+<x>+<y>', i.e. '+0+0' is
289 top left hand corner of the screen, '+0-70' is bottom left hand
290 side of screen (more or less).
291 extra_cluster_file = <null>
293 Define an extra cluster file in the format of /etc/clusters.
294 Multiple files can be specified, seperated by commas. Both ~
295 and $HOME are acceptable as a to reference the users home
296 directory, i.e.
297 extra_cluster_file = ~/clusters, $HOME/clus
299 ignore_host_errors
301 THIS OPTION IS DEPRECATED. It has been left in so current
302 systems continue to function as expected.
303 key_addhost = Control-Shift-plus
305 Default key sequence to open AddHost menu. See below notes on
306 shortcuts.
307 key_clientname = Alt-n
309 Default key sequence to send cssh client names to client. See
310 below notes on shortcuts.
311 key_paste = Control-v
313 Default key sequence to paste text into the console window.
314 See below notes on shortcuts.
315 key_quit = Control-q
317 Default key sequence to quit the program (will terminate all
318 open windows). See below notes on shortcuts.
319 key_retilehosts = Alt-r
321 Default key sequence to retile host windows. See below notes
322 on shortcuts.
323 max_addhost_menu_cluster_items = 6
325 Maximum number of entries in the 'Add Host' menu cluster list
326 before scrollbars are used
327 max_host_menu_items = 30
329 Maximum number of hosts to put into the host menu before
330 starting a new column
331 menu_host_autotearoff = 0
333 menu_send_autotearoff = 0
334 When set to non-0 will automatically tear-off the host or send
335 menu at program start
336 mouse_paste = Button-2 (middle mouse button)
338 Default key sequence to paste text into the console window
339 using the mouse. See below notes on shortcuts.
340 rsh_args = <blank>
342 ssh_args = "-x -o ConnectTimeout=10"
343 Sets any arguments to be used with the communication method
344 (defaults to ssh arguments).
345 NOTE: The given defaults are based on OpenSSH, not commercial
347 ssh software.
348 NOTE: Any "generic" change to the method (i.e. specifying the
350 ssh port to use) should be done in the medium's own config file
351 (see ssh_config and $HOME/.ssh/config).
352 screen_reserve_top = 0
354 screen_reserve_bottom = 60
355 screen_reserve_left = 0
356 screen_reserve_right = 0
357 Number of pixels from the screen side to reserve when
358 calculating screen geometry for tiling. Setting this to
359 something like 50 will help keep cssh from positioning windows
360 over your window manager's menu bar if it draws one at that
361 side of the screen.
362 rsh = /path/to/rsh
364 ssh = /path/to/ssh
365 Depending on the value of comms, set the path of the
366 communication binary.
367 terminal = /path/to/terminal
369 Path to the x-windows terminal used for the client.
370 terminal_args = <blank>
372 Arguments to use when opening terminal windows. Otherwise
373 takes defaults from $HOME/.Xdefaults or $<$HOME/.Xresources>
374 file.
375 terminal_font = 6x13
377 Font to use in the terminal windows. Use standard X font
378 notation.
379 terminal_reserve_top = 5
381 terminal_reserve_bottom = 0
382 terminal_reserve_left = 5
383 terminal_reserve_right = 0
384 Number of pixels from the terminal side to reserve when
385 calculating screen geometry for tiling. Setting these will
386 help keep cssh from positioning windows over your scroll and
387 title bars or otherwise overlapping the windows too much.
388 terminal_colorize = 1
390 If set to 1 (the default), then "-bg" and "-fg" arguments will
391 be added to the terminal invocation command-line. The terminal
392 will be colored in a pseudo-random way based on the host name;
393 while the color of a terminal is not easily predicted, it will
394 always be the same color for a given host name. After a while,
395 you will recognize hosts by their characteristic terminal
396 color.
397 terminal_bg_style = dark
399 If set to dark, the the terminal background will be set to
400 black and the foreground to the pseudo-random color. If set to
401 light, then the foreground will be black and the background the
402 pseudo-random color. If terminal_colorize is zero, then this
403 option has no effect.
404 terminal_size = 80x24
406 Initial size of terminals to use (note: the number of lines
407 (24) will be decreased when resizing terminals for tiling, not
408 the number of characters (80))
409 terminal_title_opt = -T
411 Option used with "terminal" to set the title of the window
412 terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
414 Option required by the terminal to allow XSendEvents to be
415 received
416 title = cssh
418 Title of windows to use for both the console and terminals.
419 unmap_on_redraw = no
421 Tell Tk to use the UnmapWindow request before redrawing
422 terminal windows. This defaults to "no" as it causes some
423 problems with the FVWM window manager. If you are experiencing
424 problems with redraws, you can set it to "yes" to allow the
425 window to be unmapped before it is repositioned.
426 use_hotkeys = yes
428 Setting to anything other than "yes" will disable all hotkeys.
429 user = $LOGNAME
431 Sets the default user for running commands on clients.
432 window_tiling = yes
434 Perform window tiling (set to "no" to disable)
435 window_tiling_direction = right
437 Direction to tile windows, where "right" means starting top
438 left and moving right and then down, and anything else means
439 starting bottom right and moving left and then up
440 NOTE: The key shortcut modifiers must be in the form "Control",
442 "Alt", or "Shift", i.e. with the first letter capitalised and the
443 rest lower case. Keys may also be disabled individually by setting
444 to the word "null".
445 $HOME/.csshrc_send_menu
447 This (optional) file contains items to populate the send menu. The
448 default entry could be written as:
449 <send_menu>
451 <menu title="Hostname">
452 <command>%s</command>
453 <accelerator>ALT-n</accelerator>
454 </menu>
455 </send_menu>
456 Submenus can also be specified as follows:
458 <send_menu>
460 <menu title="Default Entries">
461 <detach>yes</detach>
462 <menu title="Hostname">
463 <command>%s</command>
464 <accelerator>ALT-n</accelerator>
465 </menu>
466 </menu>
467 </send_menu>
468 Caveats:
470 There is currently no strict format checking of this file.
472 The format of the file may change in the future
473 If the file exists the default entry (Hostname) is not added
474 The following replacement macros are available:
476 %s Hostname part of the specific connection string to each client,
478 minus any username or port
479 %u Username part of the connection string to each client
481 %h Hostname of server where cssh is being run from
483 %n <RETURN> code
485 NOTE: requires XML::Simple to be installed
487
489 1. Catering for IPv6 addresses is minimal. This is due to a conflict
490 between IPv6 addresses and port numbers within the same server
491 definition since they both use the same seperator, i.e. is the
492 following just an IPv6 address, or an address + port number of
493 2323?
494 2001:db8::1428:2323
496 Exactly - I cannot tell either. the IPv6 address without a port is
498 assumed in those cases where it cannot be determined and a warning
499 is issued.
500 Possible work arounds include:
502 a. Use square brackets around the IPv6 address, i.e.
504 [2001:db8::1428]:2323 or
505 [2001:db8::1428:2323] as appropriate so there is no
506 ambiguity
507 b. Use the full IPv6 address if also using a port number - the 8th
509 colon is assumed to be the port seperator.
510 c. Define the IPv6 address in your /etc/hosts file, DNS or other
512 name service lookup mechanism and use the hostname instead of
513 the address.
514 2. Swapping virtual desktops can a redraw of all the terminal windows.
516 This is due to a lack of distinction within Tk between switching
517 desktops and minimising/maximising windows. Until Tk can tell the
518 difference between the two events, there is no fix (apart from
519 rewriting everything directly in X)
520 Anyone with any good ideas to fix the above bugs is more than welcome
522 to get in touch and/or provide a patch.
523
525 · If you have issues running cssh, first try:
526 "cssh -e [user@]<hostname>[:port]"
528 This performs two tests to confirm cssh is able to work properly with
530 the settings provided within the .csshrc file (or internal defaults).
531 1. test the terminal window works with the options provided
533 2. test ssh works to a host with the configured arguments
535 Configuration options to watch for in ssh are
537 - Doesnt understand "-o ConnectTimeout=10" - remove the option
539 in the F<.csshrc> file
540 - OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
542 or use "ForwardX11Trusted yes' in ssh_config (if you change the
543 default ssh options from -x to -X)
544 · If you require support, please run the following commands and post it
546 on the web site in the support/problems forum:
547 "perl -V"
549 "perl -MTk -e 'print $Tk::VERSION,$/'"
551 "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
553 "cat /etc/csshrc $HOME/.csshrc"
555 · Use the debug switches (-d, -D, or -dD) will turn on debugging
557 output. However, please only use this option with one host at a
558 time, i.e. "cssh -d <host>" due to the amount of output produced (in
559 both main and child windows).
560
562 <http://clusterssh.sourceforge.net/>, ssh, Tk::overview, X11::Protocol,
563 perl
564
566 Duncan Ferguson
567
569 clusterssh is distributed under the GNU public license. See the file
570 LICENSE for details.
571 A web site for comments, requests, bug reports and bug fixes/patches is
573 available at <http://clusterssh.sourceforge.net/>
574perl v5.12.1 2009-12-19 CSSH(1)