1CCON(1) User Contributed Perl Documentation CCON(1)
2
6 ccon - Cluster administration tool
7
9 This documentation is for version: 4.16
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 Also see the individual man pages for each of these utilities
20 crsh - Use 'rsh' as the communication method
22 csftp - Use 'sftp' as the communication method
23 cssh - Use 'ssh' as the communication method
24 ctel - Use 'telnet' as the communication method
25
27 The command opens an administration console and an xterm to all
28 specified hosts. Any text typed into the administration console is
29 replicated to all windows. All windows may also be typed into
30 directly.
31 This tool is intended for (but not limited to) cluster administration
33 where the same configuration or commands must be run on each node
34 within the cluster. Performing these commands all at once via this
35 tool ensures all nodes are kept in sync.
36 Connections are opened using console which must be correctly installed
38 and configured.
39 Extra caution should be taken when editing files as lines may not
41 necessarily be in the same order; assuming line 5 is the same across
42 all servers and modifying that is dangerous. It's better to search for
43 the specific line to be changed and double-check all terminals are as
44 expected before changes are committed.
45 Further Notes
47 Please also see "KNOWN BUGS".
48 • The dotted line on any sub-menu is a tear-off, i.e. click on it and
50 the sub-menu is turned into its own window.
51 • Unchecking a hostname on the Hosts sub-menu will unplug the host
53 from the cluster control window, so any text typed into the console
54 is not sent to that host. Re-selecting it will plug it back in.
55 • If your window manager menu bars are obscured by terminal windows
57 see the "screen_reserve_XXXXX" options in the
58 $HOME/.clusterssh/config file (see "FILES").
59 • If the terminals overlap too much see the "terminal_reserve_XXXXX"
61 options in the $HOME/.clusterssh/config file (see "FILES").
62 • When using ClusterSSH on a large number of systems to connect to a
64 single system using an SSH utility (e.g. you issue a command to to
65 copy a file using scp from the remote computers to a single host)
66 and when these connections require authentication (i.e. you are
67 going to authenticate with a password), the sshd daemon at that
68 location may refuse connections after the number "MaxStartups"
69 limit in sshd_config is exceeded. (If this value is not set, it
70 defaults to 10). This is expected behavior; sshd uses this
71 mechanism to prevent DoS attacks from unauthenticated sources.
72 Please tune sshd_config and reload the SSH daemon, or consider
73 using the ~/.ssh/authorized_keys mechanism for authentication if
74 you encounter this problem.
75 • If client windows fail to open, try running:
77 "ccon -e {single host name}"
79 This will test the mechanisms used to open windows to hosts. This
81 could be due to either the "-xrm" terminal option which enables
82 "AllowSendEvents" (some terminals do not require this option, other
83 terminals have another method for enabling it - see your terminal
84 documentation) or the configuration of "console".
85
87 Some of these options may also be defined within the configuration
88 file. Default options are shown as appropriate.
89 --autoclose <seconds>, -K <seconds>
91 Number of seconds to wait before closing finished terminal windows.
92 --autoquit, -q
94 Toggle automatically quitting after the last client window has
95 closed (overriding the config file).
96 --cluster-file '<filename>', -c '<filename>'
98 Use supplied file as additional cluster file (see also "FILES").
99 --cols <cols>, -x <cols>
101 Number of columns
102 --config-file '<filename>', -C '<filename>'
104 Use supplied file as additional configuration file (see also
105 "FILES").
106 --debug [[...] || <INTEGER>]
108 Enable debugging. Either a level can be provided or the option can
109 be repeated multiple times. Maximum level is 9.
110 --dump-config, -d
112 Dump the current configuration in the same format used by the
113 $HOME/.clusterssh/config file.
114 --evaluate '<[user@]<host>[:port]>', -e '<[user@]<host>[:port]>'
116 Display and evaluate the terminal and connection arguments to
117 display any potential errors. The <hostname> is required to aid
118 the evaluation.
119 --fillscreen
121 Resize terminal windows to fill the whole available screen
122 --font '<font>', -f '<font>'
124 Specify the font to use in the terminal windows. Use standard X
125 font notation such as "5x8".
126 --help, -h
128 Show basic help text and exit
129 --list '[tag]', -L '[tag]'
131 List available cluster tags. Tag is optional. If a tag is provided
132 then hosts for that tag are listed. NOTE: format of output changes
133 when using "--quiet" or "-Q" option.
134 --man, -H
136 Show full help text (the man page) and exit
137 --master '<STRING>', -M '<STRING>'
139 The console client program polls master as the primary server,
140 rather than the default set at compile time (typically
141 ``console'').
142 --port <port>, -p <port>
144 Specify an alternate port for connections.
145 --quiet, -Q
147 Do not output extra text when using some options
148 --rows <rows>, -y <rows>
150 Number of rows
151 --show-history, -s
153 Show history within console window.
154 --tag-file '<filename>', -r '<filename>'
156 Use supplied file as additional tag file (see also "FILES")
157 --term-args '<STRING>', -t '<STRING>'
159 Specify arguments to be passed to terminals being used.
160 --tile, -g
162 Toggle window tiling (overriding the config file).
163 --title '<title>', -T '<title>'
165 Specify the initial part of the title used in the console and
166 client windows.
167 --unique-servers, -u
169 Toggle connecting to each host only once when a hostname has been
170 specified multiple times.
171 --usage, -?
173 Show synopsis and exit
174 --use-all-a-records, -A
176 If a hostname resolves to multiple IP addresses, toggle whether or
177 not to connect to all of them, or just the first one (see also
178 config file entry).
179 --version, -v
181 Show version information and exit
182
184 The following arguments are supported:
185 [user@]<hostname>[:port] ...
187 Open an xterm to the given hostname and connect to the
188 administration console. The optional port number can be used if
189 the server is not listening on the standard port.
190 <tag> ...
192 Open a series of xterms defined by <tag> in one of the
193 supplementary configuration files (see "FILES").
194 Note: specifying a username on a cluster tag will override any
196 usernames defined in the cluster.
197
199 The following key shortcuts are available within the console window,
200 and all of them may be changed via the configuration files.
201 Control-Shift-plus
203 Open the 'Add Host(s) or Cluster(s)' dialogue box. Multiple host
204 or cluster names can be entered, separated by spaces.
205 Alt-n
207 Paste in the hostname part of the specific connection string to
208 each client, minus any username or port, e.g.
209 "scp /etc/hosts server:files/<Alt-n>.hosts"
211 would replace the <Alt-n> with the client's name in each window.
213 Alt-l
215 Paste in the hostname of the server cssh is being run on
216 Alt-q
218 Quit the program and close all connections and windows.
219 Alt-r
221 Retile all the client windows.
222 Alt-u
224 Paste in the username for the connection
225 Alt-1
227 Alt-2
228 Alt-3
229 Alt-4
230 Run the matching user defined macro on the server and send the
231 output to the client
232
234 Open up a session to 3 servers
235 $ ccon server1 server2 server3
236 Open up a session to a cluster of servers identified by the tag 'farm1'
238 and give the controlling window a specific title, where the tag is
239 defined in one of the default configuration files
240 $ ccon -T 'Web Farm Cluster 1' farm1
241 Connect to different servers using different login names. NOTE: this
243 can also be achieved by setting up appropriate options in the
244 configuration files. Do not close the console when the last terminal
245 exits.
246 $ ccon user1@server1 admin@server2
247 Open up a cluster defined in a non-default configuration file
249 $ ccon -c $HOME/cssh.extra_clusters db_cluster
250 Override the configured/default port to use 2022 instead
252 $ ccon -p 2022 server1 server2
253
255 /etc/clusters, $HOME/.clusterssh/clusters
256 These files contain a list of tags to server names mappings. When
257 any name is used on the command line it is checked to see if it is
258 a tag. If it is a tag, then the tag is replaced with the list of
259 servers. The format is as follows:
260 <tag> [user@]<server>[:port] [user@]<server>[:port] [...]
262 e.g.
264 # List of servers in live
266 live admin1@server1 admin2@server2:2022 server3 server4
267 All comments (marked by a #) and blank lines are ignored. Tags may
269 be nested, but be aware of using recursive tags as they are not
270 checked for.
271 Servers can be defined using expansion macros:
273 "webservers websvr{a,b,c}"
275 would be expanded to
277 "webservers websvra websvrb websvrc"
279 and
281 "webservers websvr{6..9}"
283 would be expanded to
285 "webservers websvr6 websvr7 websvr8 websvr9"
287 Extra cluster files may also be specified either as an option on
289 the command line (see "cluster-file") or in the user's
290 $HOME/.clusterssh/config file (see "extra_cluster_file"
291 configuration option).
292 NOTE: the last tag read overwrites any pre-existing tag of that
294 name.
295 NOTE: there is a special cluster tag called "default" - any tags or
297 hosts included within this tag will be automatically opened if
298 nothing is specified on the command line.
299 /etc/tags, $HOME/.clusterssh/tags
301 Very similar to clusters files but the definition is reversed. The
302 format is:
303 <host> <tag> [...]
305 This allows one host to be specified as a member of a number of
307 tags. This format can be clearer than using clusters files.
308 Extra tag files may be specified either as an option (see
310 "tag-file") or within the user's $HOME/.clusterssh/config file (see
311 "extra_tag_file" configuration option).
312 NOTE: All tags are added together
314 /etc/csshrc & $HOME/.clusterssh/config
316 This file contains configuration overrides - the defaults are as
317 marked. Default options are overwritten first by the global file,
318 and then by the user file.
319 NOTE: values for entries do not need to be quoted unless it is
321 required for passing arguments, e.g.
322 "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""
324 should be written as
326 "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"
328 auto_close = 5
330 Close terminal window after this many seconds. If set to 0
331 will instead wait on input from the user in each window before
332 closing. See also --autoclose and --no-autoclose
333 auto_quit = 1
335 Automatically quit after the last client window closes. Set to
336 0 to disable. See also --autoquit
337 auto_wm_decoration_offsets = no
339 Enable or disable alternative algorithm for calculating
340 terminal positioning.
341 command_pre =
343 command_post =
344 Add extra commands around the communication method. For
345 example:
346 command_pre= . $HOME/virtualenvs/default/bin/active ;
348 command_post= | ct
349 would allow for using Python virtual envronments and then
351 piping all shell output through "chromaterm" for syntax
352 highlighting. Note: you must use appropriate command
353 separators/terminators to keep the meaning of the command
354 pipline (such as ";" and "|" between commands).
355 These are not put through macro parsing.
357 comms = console
359 Sets the default communication method (initially taken from the
360 name of the program, but can be overridden here).
361 console_position = <null>
363 Set the initial position of the console - if empty then let the
364 window manager decide. Format is '+<x>+<y>', i.e. '+0+0' is
365 top left hand corner of the screen, '+0-70' is bottom left hand
366 side of screen (more or less).
367 external_command_mode = 0600
369 File mode bits for the external_command_pipe.
370 external_command_pipe = <null>
372 Define the full path to an external command pipe that can be
373 written to for controlling some aspects of ClusterSSH, such as
374 opening sessions to more clusters.
375 Commands:
377 "open <tag|hostname>" - open new sessions to provided tag or
379 hostname
380 "retile" - force window retiling
382 e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>
384 external_cluster_command = <null>
386 Define the full path to an external command that can be used to
387 resolve tags to host names. This command can be written in any
388 language. The script must accept a list of tags to resolve and
389 output a list of hosts (space separated on a single line). Any
390 tags that cannot be resolved should be returned unchanged.
391 A non-0 exit code will be counted as an error, a warning will
393 be printed and output ignored.
394 If the external command is given a "-L" option it should output
396 a list of tags (space separated on a single line) it can
397 resolve
398 extra_cluster_file = <null>
400 Define an extra cluster file in the format of /etc/clusters.
401 Multiple files can be specified, separated by commas. Both ~
402 and $HOME are acceptable as a reference to the user's home
403 directory, e.g.
404 "extra_cluster_file = ~/clusters, $HOME/clus"
406 extra_tag_file = <null>
408 Define an extra tag file in the format of /etc/tags. Multiple
409 files can be specified, separated by commas. Both ~ and $HOME
410 are acceptable as a reference to the user's home directory,
411 e.g.
412 "extra_tag_file = ~/tags, $HOME/tags"
414 key_addhost = Control-Shift-plus
416 Default key sequence to open AddHost menu. See "KEY SHORTCUTS"
417 for more information.
418 hide_menu = 0
420 If set to 1, hide the menu bar (File, Hosts, Send, Help) in the
421 console.
422 key_clientname = Alt-n
424 Default key sequence to send cssh client names to client. See
425 "KEY SHORTCUTS" for more information.
426 key_localname = Alt-l
428 Default key sequence to send hostname of local server to
429 client. See "KEY SHORTCUTS" for more information.
430 key_paste = Control-v
432 Default key sequence to paste text into the console window.
433 See "KEY SHORTCUTS" for more information.
434 key_quit = Control-q
436 Default key sequence to quit the program (will terminate all
437 open windows). See "KEY SHORTCUTS" for more information.
438 key_retilehosts = Alt-r
440 Default key sequence to retile host windows. See "KEY
441 SHORTCUTS" for more information.
442 key_username = Alt-u
444 Default key sequence to send username to client. See "KEY
445 SHORTCUTS" for more information.
446 key_user_1 = Alt-1
448 key_user_2 = Alt-2
449 key_user_3 = Alt-3
450 key_user_4 = Alt-4
451 Default key sequence to send user defined macros to client. If
452 the matching macro_user_1 macro is undefined, the sequence is
453 passed straight to the terminal. See "KEY SHORTCUTS" for more
454 information.
455 macro_servername = %s
457 macro_hostname = %h
458 macro_username = %u
459 macro_newline = %n
460 macro_version = %v
461 macro_user_1 = %1
462 macro_user_2 = %2
463 macro_user_3 = %3
464 macro_user_4 = %4
465 Change the replacement macro used when either using a 'Send'
466 menu item, or when pasting text into the main console.
467 macro_user_1_command =
469 macro_user_2_command =
470 macro_user_3_command =
471 macro_user_4_command =
472 User defined macros - the macro is run through the shell on the
473 server and the output is sent to the client. For example,
474 "macro_user_1_command=echo echo macro_user_1"
476 would send the text C<echo macro_user_1> into the terminal session.
478 "macro_user_1_command=env | grep CSSH"
480 would send the CSSH environment variables to the client.
482 The following environment variables are set in the shell of the
484 macro process
485 "CSSH_SERVERNAME"
487 "CSSH_HOSTNAME"
488 "CSSH_USERNAME"
489 "CSSH_CONNECTION_STRING"
490 "CSSH_CONNECTION_PORT"
491 "CSSH_VERSION"
492 macros_enabled = yes
493 Enable or disable macro replacement. Note: this affects all
494 the "macro_*" variables above.
495 max_addhost_menu_cluster_items = 6
497 Maximum number of entries in the 'Add Host' menu cluster list
498 before scrollbars are used
499 max_host_menu_items = 30
501 Maximum number of hosts to put into the host menu before
502 starting a new column
503 menu_host_autotearoff = 0
505 menu_send_autotearoff = 0
506 When set to non-0 will automatically tear-off the host or send
507 menu at program start
508 mouse_paste = Button-2 (middle mouse button)
510 Default key sequence to paste text into the console window
511 using the mouse. See "KEY SHORTCUTS" for more information.
512 rsh = /path/to/rsh
514 ssh = /path/to/ssh
515 telnet = /path/to/telnet
516 Set the path to the specific binary to use for the
517 communication method, else uses the first match found in $PATH
518 rsh_args = <blank>
520 ssh_args = "-x -o ConnectTimeout=10"
521 telnet_args = <blank>
522 Sets any arguments to be used with the communication method
523 (defaults to ssh arguments).
524 NOTE: The given defaults are based on OpenSSH, not commercial
526 ssh software.
527 NOTE: Any "generic" change to the method (e.g., specifying the
529 ssh port to use) should be done in the medium's own config file
530 (see "ssh_config" and $HOME/.ssh/config).
531 screen_reserve_top = 0
533 screen_reserve_bottom = 60
534 screen_reserve_left = 0
535 screen_reserve_right = 0
536 Number of pixels from the screen's side to reserve when
537 calculating screen geometry for tiling. Setting this to
538 something like 50 will help keep cssh from positioning windows
539 over your window manager's menu bar if it draws one at that
540 side of the screen.
541 terminal = /path/to/xterm
543 Path to the X-Windows terminal used for the client.
544 terminal_args = <blank>
546 Arguments to use when opening terminal windows. Otherwise
547 takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.
548 terminal_chdir = 0
550 When non-0, set the working directory for each terminal as per
551 'terminal_chdir_path'
552 terminal_chdir_path = $HOME/.clusterssh/work/%s
554 Path to use as working directory for each terminal when
555 'terminal_chdir' is enabled. The path provided is passed
556 through the macro parser (see the section above on
557 'macros_enabled'.
558 terminal_font = 6x13
560 Font to use in the terminal windows. Use standard X font
561 notation.
562 terminal_reserve_top = 5
564 terminal_reserve_bottom = 0
565 terminal_reserve_left = 5
566 terminal_reserve_right = 0
567 Number of pixels from the terminal's side to reserve when
568 calculating screen geometry for tiling. Setting these will
569 help keep cssh from positioning windows over your scroll and
570 title bars or otherwise overlapping the windows too much.
571 terminal_colorize = 1
573 If set to 1 (the default), then "-bg" and "-fg" arguments will
574 be added to the terminal invocation command-line. The terminal
575 will be colored in a pseudo-random way based on the host name;
576 while the color of a terminal is not easily predicted, it will
577 always be the same color for a given host name. After a while,
578 you will recognize hosts by their characteristic terminal
579 color.
580 terminal_bg_style = dark
582 If set to "dark", the terminal background will be set to black
583 and the foreground to the pseudo-random color. If set to
584 "light", then the foreground will be black and the background
585 the pseudo-random color. If terminal_colorize is "zero", then
586 this option has no effect.
587 terminal_size = 80x24
589 Initial size of terminals to use. NOTE: the number of lines
590 (24) will be decreased when resizing terminals for tiling, not
591 the number of characters (80).
592 terminal_title_opt = -T
594 Option used with "terminal" to set the title of the window
595 terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
597 Option required by the terminal to allow XSendEvents to be
598 received
599 title = cssh
601 Title of windows to use for both the console and terminals.
602 unmap_on_redraw = no
604 Tell Tk to use the UnmapWindow request before redrawing
605 terminal windows. This defaults to "no" as it causes some
606 problems with the FVWM window manager. If you are experiencing
607 problems with redraws, you can set it to "yes" to allow the
608 window to be unmapped before it is repositioned.
609 use_all_a_records = 0
611 If a hostname resolves to multiple IP addresses, set to 1 to
612 connect to all of them, not just the first one found. See also
613 "--use-all-a-records"}
614 use_hotkeys = 1
616 Setting to 0 will disable all hotkeys.
617 use_natural_sort = 0
619 Windows will normally sort in alphabetical order, i.e.: host1,
620 host11, host2. Setting to this 1 will change the sort order,
621 i.e.: host1, host2, host11. NOTE: You must have the perl module
622 Sort::Naturally installed.
623 user = $LOGNAME
625 Sets the default user for running commands on clients.
626 window_tiling = 1
628 Perform window tiling (set to 0 to disable)
629 window_tiling_direction = right
631 Direction to tile windows, where "right" means starting top
632 left and moving right and then down, and anything else means
633 starting bottom right and moving left and then up
634 NOTE: The key shortcut modifiers must be in the form "Control",
636 "Alt" or "Shift", e.g. with the first letter capitalised and the
637 rest lower case. Keys may also be disabled individually by setting
638 to the word "null".
639 $HOME/.clusterssh/send_menu
641 This (optional) file contains items to populate the send menu. The
642 default entry could be written as:
643 <send_menu>
645 <menu title="Use Macros">
646 <toggle/>
647 <accelerator>ALT-p</accelerator>
648 </menu>
649 <menu title="Remote Hostname">
650 <command>%s</command>
651 <accelerator>ALT-n</accelerator>
652 </menu>
653 <menu title="Local Hostname">
654 <command>%s</command>
655 <accelerator>ALT-l</accelerator>
656 </menu>
657 <menu title="Username">
658 <command>%u</command>
659 <accelerator>ALT-u</accelerator>
660 </menu>
661 <menu title="Test Text">
662 <command>echo "ClusterSSH Version: %v%n</command>
663 </menu>
664 </send_menu>
665 Submenus can also be specified as follows:
667 <send_menu>
669 <menu title="Default Entries">
670 <detach>yes</detach>
671 <menu title="Hostname">
672 <command>%s</command>
673 <accelerator>ALT-n</accelerator>
674 </menu>
675 </menu>
676 </send_menu>
677 Caveats:
679 There is currently no strict format checking of this file.
681 The format of the file may change in the future
682 If the file exists, the default entry (Hostname) is not added
683 The following replacement macros are available (note: these can be
685 changed in the configuration file):
686 %s Hostname part of the specific connection string to each client,
688 minus any username or port
689 %u Username part of the connection string to each client
691 %h Hostname of server where cssh is being run from
693 %n "RETURN" code
695 NOTE: requires XML::Simple to be installed
697
699 If you have any ideas about how to fix the below bugs, please get in
700 touch and/or provide a patch.
701 • Swapping virtual desktops can cause a redraw of all the terminal
703 windows. This is due to a lack of distinction within Tk between
704 switching desktops and minimising/maximising windows. Until Tk can
705 tell the difference between the two events, there is no fix (apart
706 from rewriting everything directly in X).
707
709 If you have issues running ccon, first try:
710 "ccon -e [user@]<hostname>[:port]"
712 This performs two tests to confirm cssh is able to work properly with
714 the settings provided within the $HOME/.clusterssh/config file (or
715 internal defaults).
716 1. Test the terminal window works with the options provided
718 2. Test console works to a host with the configured arguments
720 Configuration options to watch for in ssh are:
722 • SSH doesn't understand "-o ConnectTimeout=10" - remove the option
724 from the $HOME/.clusterssh/config file
725 • OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
727 or use "ForwardX11Trusted yes" in $HOME/.ssh/ssh_config (if you
728 change the default ssh options from "-x" to "-X")
729
731 A web site for comments, requests, bug reports and bug fixes/patches is
732 available at: <https://github.com/duncs/clusterssh>
733 If you require support, please run the following commands and create an
735 issue via: <https://github.com/duncs/clusterssh/issues>
736 "perl -V"
738 "perl -MTk -e 'print $Tk::VERSION,$/'"
740 "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
742 "cat /etc/csshrc $HOME/.clusterssh/config"
744 Using the debug option (--debug) will turn on debugging output. Repeat
746 the option to increase the amount of debug. However, if possible
747 please only use this option with one host at a time, e.g. "cssh --debug
748 <host>" due to the amount of output produced (in both main and child
749 windows).
750
752 <https://github.com/duncs/clusterssh/wiki/>, "ssh", Tk::overview,
753 X11::Protocol, "perl"
754
756 Duncan Ferguson, "<duncan_j_ferguson at yahoo.co.uk>"
757
759 Copyright 1999-2018 Duncan Ferguson.
760 This program is free software; you can redistribute it and/or modify it
762 under the terms of either: the GNU General Public License as published
763 by the Free Software Foundation; or the Artistic License.
764 See http://dev.perl.org/licenses/ for more information.
766perl v5.38.0 2023-07-19 CCON(1)