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