1CCON(1) User Contributed Perl Documentation CCON(1)
2
6 ccon - Cluster administration tool
7
9 This documentation is for version: 4.14
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 quitting 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 Alt-1
219 Alt-2
220 Alt-3
221 Alt-4
222 Run the matching user defined macro on the server and send the
223 output to the client
224
226 Open up a session to 3 servers
227 $ ccon server1 server2 server3
228 Open up a session to a cluster of servers identified by the tag 'farm1'
230 and give the controlling window a specific title, where the tag is
231 defined in one of the default configuration files
232 $ ccon -T 'Web Farm Cluster 1' farm1
233 Connect to different servers using different login names. NOTE: this
235 can also be achieved by setting up appropriate options in the
236 configuration files. Do not close the console when the last terminal
237 exits.
238 $ ccon user1@server1 admin@server2
239 Open up a cluster defined in a non-default configuration file
241 $ ccon -c $HOME/cssh.extra_clusters db_cluster
242 Override the configured/default port to use 2022 instead
244 $ ccon -p 2022 server1 server2
245
247 /etc/clusters, $HOME/.clusterssh/clusters
248 These files contain a list of tags to server names mappings. When
249 any name is used on the command line it is checked to see if it is
250 a tag. If it is a tag, then the tag is replaced with the list of
251 servers. The format is as follows:
252 <tag> [user@]<server>[:port] [user@]<server>[:port] [...]
254 e.g.
256 # List of servers in live
258 live admin1@server1 admin2@server2:2022 server3 server4
259 All comments (marked by a #) and blank lines are ignored. Tags may
261 be nested, but be aware of using recursive tags as they are not
262 checked for.
263 Servers can be defined using expansion macros:
265 "webservers websvr{a,b,c}"
267 would be expanded to
269 "webservers websvra websvrb websvrc"
271 and
273 "webservers websvr{6..9}"
275 would be expanded to
277 "webservers websvr6 websvr7 websvr8 websvr9"
279 Extra cluster files may also be specified either as an option on
281 the command line (see "cluster-file") or in the user's
282 $HOME/.clusterssh/config file (see "extra_cluster_file"
283 configuration option).
284 NOTE: the last tag read overwrites any pre-existing tag of that
286 name.
287 NOTE: there is a special cluster tag called "default" - any tags or
289 hosts included within this tag will be automatically opened if
290 nothing is specified on the command line.
291 /etc/tags, $HOME/.clusterssh/tags
293 Very similar to clusters files but the definition is reversed. The
294 format is:
295 <host> <tag> [...]
297 This allows one host to be specified as a member of a number of
299 tags. This format can be clearer than using clusters files.
300 Extra tag files may be specified either as an option (see
302 "tag-file") or within the user's $HOME/.clusterssh/config file (see
303 "extra_tag_file" configuration option).
304 NOTE: All tags are added together
306 /etc/csshrc & $HOME/.clusterssh/config
308 This file contains configuration overrides - the defaults are as
309 marked. Default options are overwritten first by the global file,
310 and then by the user file.
311 NOTE: values for entries do not need to be quoted unless it is
313 required for passing arguments, e.g.
314 "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""
316 should be written as
318 "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"
320 auto_close = 5
322 Close terminal window after this many seconds. If set to 0
323 will instead wait on input from the user in each window before
324 closing. See also --autoclose and --no-autoclose
325 auto_quit = 1
327 Automatically quit after the last client window closes. Set to
328 0 to disable. See also --autoquit
329 auto_wm_decoration_offsets = no
331 Enable or disable alternative algorithm for calculating
332 terminal positioning.
333 comms = console
335 Sets the default communication method (initially taken from the
336 name of the program, but can be overridden here).
337 console_position = <null>
339 Set the initial position of the console - if empty then let the
340 window manager decide. Format is '+<x>+<y>', i.e. '+0+0' is
341 top left hand corner of the screen, '+0-70' is bottom left hand
342 side of screen (more or less).
343 external_command_mode = 0600
345 File mode bits for the external_command_pipe.
346 external_command_pipe = <null>
348 Define the full path to an external command pipe that can be
349 written to for controlling some aspects of ClusterSSH, such as
350 opening sessions to more clusters.
351 Commands:
353 "open <tag|hostname>" - open new sessions to provided tag or
355 hostname
356 "retile" - force window retiling
358 e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>
360 external_cluster_command = <null>
362 Define the full path to an external command that can be used to
363 resolve tags to host names. This command can be written in any
364 language. The script must accept a list of tags to resolve and
365 output a list of hosts (space separated on a single line). Any
366 tags that cannot be resolved should be returned unchanged.
367 A non-0 exit code will be counted as an error, a warning will
369 be printed and output ignored.
370 If the external command is given a "-L" option it should output
372 a list of tags (space separated on a single line) it can
373 resolve
374 extra_cluster_file = <null>
376 Define an extra cluster file in the format of /etc/clusters.
377 Multiple files can be specified, separated by commas. Both ~
378 and $HOME are acceptable as a reference to the user's home
379 directory, e.g.
380 "extra_cluster_file = ~/clusters, $HOME/clus"
382 extra_tag_file = <null>
384 Define an extra tag file in the format of /etc/tags. Multiple
385 files can be specified, separated by commas. Both ~ and $HOME
386 are acceptable as a reference to the user's home directory,
387 e.g.
388 "extra_tag_file = ~/tags, $HOME/tags"
390 key_addhost = Control-Shift-plus
392 Default key sequence to open AddHost menu. See "KEY SHORTCUTS"
393 for more information.
394 hide_menu = 0
396 If set to 1, hide the menu bar (File, Hosts, Send, Help) in the
397 console.
398 key_clientname = Alt-n
400 Default key sequence to send cssh client names to client. See
401 "KEY SHORTCUTS" for more information.
402 key_localname = Alt-l
404 Default key sequence to send hostname of local server to
405 client. See "KEY SHORTCUTS" for more information.
406 key_paste = Control-v
408 Default key sequence to paste text into the console window.
409 See "KEY SHORTCUTS" for more information.
410 key_quit = Control-q
412 Default key sequence to quit the program (will terminate all
413 open windows). See "KEY SHORTCUTS" for more information.
414 key_retilehosts = Alt-r
416 Default key sequence to retile host windows. See "KEY
417 SHORTCUTS" for more information.
418 key_username = Alt-u
420 Default key sequence to send username to client. See "KEY
421 SHORTCUTS" for more information.
422 key_user_1 = Alt-1
424 key_user_2 = Alt-2
425 key_user_3 = Alt-3
426 key_user_4 = Alt-4
427 Default key sequence to send user defined macros to client. If
428 the matching macro_user_1 macro is undefined, the sequence is
429 passed straight to the terminal. See "KEY SHORTCUTS" for more
430 information.
431 macro_servername = %s
433 macro_hostname = %h
434 macro_username = %u
435 macro_newline = %n
436 macro_version = %v
437 macro_user_1 = %1
438 macro_user_2 = %2
439 macro_user_3 = %3
440 macro_user_4 = %4
441 Change the replacement macro used when either using a 'Send'
442 menu item, or when pasting text into the main console.
443 macro_user_1_command =
445 macro_user_2_command =
446 macro_user_3_command =
447 macro_user_4_command =
448 User defined macros - the macro is run through the shell on the
449 server and the output is sent to the client. For example,
450 "macro_user_1_command=echo echo macro_user_1"
452 would send the text C<echo macro_user_1> into the terminal session.
454 "macro_user_1_command=env | grep CSSH"
456 would send the CSSH environment variables to the client.
458 The following environment variables are set in the shell of the
460 macro process
461 "CSSH_SERVERNAME"
463 "CSSH_HOSTNAME"
464 "CSSH_USERNAME"
465 "CSSH_CONNECTION_STRING"
466 "CSSH_CONNECTION_PORT"
467 "CSSH_VERSION"
468 macros_enabled = yes
469 Enable or disable macro replacement. Note: this affects all
470 the "macro_*" variables above.
471 max_addhost_menu_cluster_items = 6
473 Maximum number of entries in the 'Add Host' menu cluster list
474 before scrollbars are used
475 max_host_menu_items = 30
477 Maximum number of hosts to put into the host menu before
478 starting a new column
479 menu_host_autotearoff = 0
481 menu_send_autotearoff = 0
482 When set to non-0 will automatically tear-off the host or send
483 menu at program start
484 mouse_paste = Button-2 (middle mouse button)
486 Default key sequence to paste text into the console window
487 using the mouse. See "KEY SHORTCUTS" for more information.
488 rsh = /path/to/rsh
490 ssh = /path/to/ssh
491 telnet = /path/to/telnet
492 Set the path to the specific binary to use for the
493 communication method, else uses the first match found in $PATH
494 rsh_args = <blank>
496 ssh_args = "-x -o ConnectTimeout=10"
497 telnet_args = <blank>
498 Sets any arguments to be used with the communication method
499 (defaults to ssh arguments).
500 NOTE: The given defaults are based on OpenSSH, not commercial
502 ssh software.
503 NOTE: Any "generic" change to the method (e.g., specifying the
505 ssh port to use) should be done in the medium's own config file
506 (see "ssh_config" and $HOME/.ssh/config).
507 screen_reserve_top = 0
509 screen_reserve_bottom = 60
510 screen_reserve_left = 0
511 screen_reserve_right = 0
512 Number of pixels from the screen's side to reserve when
513 calculating screen geometry for tiling. Setting this to
514 something like 50 will help keep cssh from positioning windows
515 over your window manager's menu bar if it draws one at that
516 side of the screen.
517 terminal = /path/to/xterm
519 Path to the X-Windows terminal used for the client.
520 terminal_args = <blank>
522 Arguments to use when opening terminal windows. Otherwise
523 takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.
524 terminal_chdir = 0
526 When non-0, set the working directory for each terminal as per
527 'terminal_chdir_path'
528 terminal_chdir_path = $HOME/.clusterssh/work/%s
530 Path to use as working directory for each terminal when
531 'terminal_chdir' is enabled. The path provided is passed
532 through the macro parser (see the section above on
533 'macros_enabled'.
534 terminal_font = 6x13
536 Font to use in the terminal windows. Use standard X font
537 notation.
538 terminal_reserve_top = 5
540 terminal_reserve_bottom = 0
541 terminal_reserve_left = 5
542 terminal_reserve_right = 0
543 Number of pixels from the terminal's side to reserve when
544 calculating screen geometry for tiling. Setting these will
545 help keep cssh from positioning windows over your scroll and
546 title bars or otherwise overlapping the windows too much.
547 terminal_colorize = 1
549 If set to 1 (the default), then "-bg" and "-fg" arguments will
550 be added to the terminal invocation command-line. The terminal
551 will be colored in a pseudo-random way based on the host name;
552 while the color of a terminal is not easily predicted, it will
553 always be the same color for a given host name. After a while,
554 you will recognize hosts by their characteristic terminal
555 color.
556 terminal_bg_style = dark
558 If set to "dark", the terminal background will be set to black
559 and the foreground to the pseudo-random color. If set to
560 "light", then the foreground will be black and the background
561 the pseudo-random color. If terminal_colorize is "zero", then
562 this option has no effect.
563 terminal_size = 80x24
565 Initial size of terminals to use. NOTE: the number of lines
566 (24) will be decreased when resizing terminals for tiling, not
567 the number of characters (80).
568 terminal_title_opt = -T
570 Option used with "terminal" to set the title of the window
571 terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
573 Option required by the terminal to allow XSendEvents to be
574 received
575 title = cssh
577 Title of windows to use for both the console and terminals.
578 unmap_on_redraw = no
580 Tell Tk to use the UnmapWindow request before redrawing
581 terminal windows. This defaults to "no" as it causes some
582 problems with the FVWM window manager. If you are experiencing
583 problems with redraws, you can set it to "yes" to allow the
584 window to be unmapped before it is repositioned.
585 use_all_a_records = 0
587 If a hostname resolves to multiple IP addresses, set to 1 to
588 connect to all of them, not just the first one found. See also
589 "--use-all-a-records"}
590 use_hotkeys = 1
592 Setting to 0 will disable all hotkeys.
593 use_natural_sort = 0
595 Windows will normally sort in alphabetical order, i.e.: host1,
596 host11, host2. Setting to this 1 will change the sort order,
597 i.e.: host1, host2, host11. NOTE: You must have the perl module
598 Sort::Naturally installed.
599 user = $LOGNAME
601 Sets the default user for running commands on clients.
602 window_tiling = 1
604 Perform window tiling (set to 0 to disable)
605 window_tiling_direction = right
607 Direction to tile windows, where "right" means starting top
608 left and moving right and then down, and anything else means
609 starting bottom right and moving left and then up
610 NOTE: The key shortcut modifiers must be in the form "Control",
612 "Alt" or "Shift", e.g. with the first letter capitalised and the
613 rest lower case. Keys may also be disabled individually by setting
614 to the word "null".
615 $HOME/.clusterssh/send_menu
617 This (optional) file contains items to populate the send menu. The
618 default entry could be written as:
619 <send_menu>
621 <menu title="Use Macros">
622 <toggle/>
623 <accelerator>ALT-p</accelerator>
624 </menu>
625 <menu title="Remote Hostname">
626 <command>%s</command>
627 <accelerator>ALT-n</accelerator>
628 </menu>
629 <menu title="Local Hostname">
630 <command>%s</command>
631 <accelerator>ALT-l</accelerator>
632 </menu>
633 <menu title="Username">
634 <command>%u</command>
635 <accelerator>ALT-u</accelerator>
636 </menu>
637 <menu title="Test Text">
638 <command>echo "ClusterSSH Version: %v%n</command>
639 </menu>
640 </send_menu>
641 Submenus can also be specified as follows:
643 <send_menu>
645 <menu title="Default Entries">
646 <detach>yes</detach>
647 <menu title="Hostname">
648 <command>%s</command>
649 <accelerator>ALT-n</accelerator>
650 </menu>
651 </menu>
652 </send_menu>
653 Caveats:
655 There is currently no strict format checking of this file.
657 The format of the file may change in the future
658 If the file exists, the default entry (Hostname) is not added
659 The following replacement macros are available (note: these can be
661 changed in the configuration file):
662 %s Hostname part of the specific connection string to each client,
664 minus any username or port
665 %u Username part of the connection string to each client
667 %h Hostname of server where cssh is being run from
669 %n "RETURN" code
671 NOTE: requires XML::Simple to be installed
673
675 If you have any ideas about how to fix the below bugs, please get in
676 touch and/or provide a patch.
677 · Swapping virtual desktops can cause a redraw of all the terminal
679 windows. This is due to a lack of distinction within Tk between
680 switching desktops and minimising/maximising windows. Until Tk can
681 tell the difference between the two events, there is no fix (apart
682 from rewriting everything directly in X).
683
685 If you have issues running ccon, first try:
686 "ccon -e [user@]<hostname>[:port]"
688 This performs two tests to confirm cssh is able to work properly with
690 the settings provided within the $HOME/.clusterssh/config file (or
691 internal defaults).
692 1. Test the terminal window works with the options provided
694 2. Test console works to a host with the configured arguments
696 Configuration options to watch for in ssh are:
698 · SSH doesn't understand "-o ConnectTimeout=10" - remove the option
700 from the $HOME/.clusterssh/config file
701 · OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
703 or use "ForwardX11Trusted yes" in $HOME/.ssh/ssh_config (if you
704 change the default ssh options from "-x" to "-X")
705
707 A web site for comments, requests, bug reports and bug fixes/patches is
708 available at: <https://github.com/duncs/clusterssh>
709 If you require support, please run the following commands and create an
711 issue via: <https://github.com/duncs/clusterssh/issues>
712 "perl -V"
714 "perl -MTk -e 'print $Tk::VERSION,$/'"
716 "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
718 "cat /etc/csshrc $HOME/.clusterssh/config"
720 Using the debug option (--debug) will turn on debugging output. Repeat
722 the option to increase the amount of debug. However, if possible
723 please only use this option with one host at a time, e.g. "cssh --debug
724 <host>" due to the amount of output produced (in both main and child
725 windows).
726
728 <https://github.com/duncs/clusterssh/wiki/>, "ssh", Tk::overview,
729 X11::Protocol, "perl"
730
732 Duncan Ferguson, "<duncan_j_ferguson at yahoo.co.uk>"
733
735 Copyright 1999-2018 Duncan Ferguson.
736 This program is free software; you can redistribute it and/or modify it
738 under the terms of either: the GNU General Public License as published
739 by the Free Software Foundation; or the Artistic License.
740 See http://dev.perl.org/licenses/ for more information.
742perl v5.30.0 2019-08-22 CCON(1)