1CTEL(1) User Contributed Perl Documentation CTEL(1)
2
6 ctel - Cluster administration tool
7
9 This documentation is for version: 4.14
10
12 ctel [-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] [-p <port>] [-Q] [-y <rows>] [-s] [-r '<filename>'] [-t
16 '<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 telnet 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 "ctel -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 "telnet".
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 --port <port>, -p <port>
131 Specify an alternate port for connections.
132 --quiet, -Q
134 Do not output extra text when using some options
135 --rows <rows>, -y <rows>
137 Number of rows
138 --show-history, -s
140 Show history within console window.
141 --tag-file '<filename>', -r '<filename>'
143 Use supplied file as additional tag file (see also "FILES")
144 --term-args '<STRING>', -t '<STRING>'
146 Specify arguments to be passed to terminals being used.
147 --tile, -g
149 Toggle window tiling (overriding the config file).
150 --title '<title>', -T '<title>'
152 Specify the initial part of the title used in the console and
153 client windows.
154 --unique-servers, -u
156 Toggle connecting to each host only once when a hostname has been
157 specified multiple times.
158 --usage, -?
160 Show synopsis and exit
161 --use-all-a-records, -A
163 If a hostname resolves to multiple IP addresses, toggle whether or
164 not to connect to all of them, or just the first one (see also
165 config file entry).
166 --version, -v
168 Show version information and exit
169
171 The following arguments are supported:
172 [user@]<hostname>[:port] ...
174 Open an xterm to the given hostname and connect to the
175 administration console. The optional port number can be used if
176 the server is not listening on the standard port.
177 <tag> ...
179 Open a series of xterms defined by <tag> in one of the
180 supplementary configuration files (see "FILES").
181 Note: specifying a username on a cluster tag will override any
183 usernames defined in the cluster.
184
186 The following key shortcuts are available within the console window,
187 and all of them may be changed via the configuration files.
188 Control-Shift-plus
190 Open the 'Add Host(s) or Cluster(s)' dialogue box. Multiple host
191 or cluster names can be entered, separated by spaces.
192 Alt-n
194 Paste in the hostname part of the specific connection string to
195 each client, minus any username or port, e.g.
196 "scp /etc/hosts server:files/<Alt-n>.hosts"
198 would replace the <Alt-n> with the client's name in each window.
200 Alt-l
202 Paste in the hostname of the server cssh is being run on
203 Alt-q
205 Quit the program and close all connections and windows.
206 Alt-r
208 Retile all the client windows.
209 Alt-u
211 Paste in the username for the connection
212 Alt-1
214 Alt-2
215 Alt-3
216 Alt-4
217 Run the matching user defined macro on the server and send the
218 output to the client
219
221 Open up a session to 3 servers
222 $ ctel server1 server2 server3
223 Open up a session to a cluster of servers identified by the tag 'farm1'
225 and give the controlling window a specific title, where the tag is
226 defined in one of the default configuration files
227 $ ctel -T 'Web Farm Cluster 1' farm1
228 Connect to different servers using different login names. NOTE: this
230 can also be achieved by setting up appropriate options in the
231 configuration files. Do not close the console when the last terminal
232 exits.
233 $ ctel user1@server1 admin@server2
234 Open up a cluster defined in a non-default configuration file
236 $ ctel -c $HOME/cssh.extra_clusters db_cluster
237 Override the configured/default port to use 2022 instead
239 $ ctel -p 2022 server1 server2
240
242 /etc/clusters, $HOME/.clusterssh/clusters
243 These files contain a list of tags to server names mappings. When
244 any name is used on the command line it is checked to see if it is
245 a tag. If it is a tag, then the tag is replaced with the list of
246 servers. The format is as follows:
247 <tag> [user@]<server>[:port] [user@]<server>[:port] [...]
249 e.g.
251 # List of servers in live
253 live admin1@server1 admin2@server2:2022 server3 server4
254 All comments (marked by a #) and blank lines are ignored. Tags may
256 be nested, but be aware of using recursive tags as they are not
257 checked for.
258 Servers can be defined using expansion macros:
260 "webservers websvr{a,b,c}"
262 would be expanded to
264 "webservers websvra websvrb websvrc"
266 and
268 "webservers websvr{6..9}"
270 would be expanded to
272 "webservers websvr6 websvr7 websvr8 websvr9"
274 Extra cluster files may also be specified either as an option on
276 the command line (see "cluster-file") or in the user's
277 $HOME/.clusterssh/config file (see "extra_cluster_file"
278 configuration option).
279 NOTE: the last tag read overwrites any pre-existing tag of that
281 name.
282 NOTE: there is a special cluster tag called "default" - any tags or
284 hosts included within this tag will be automatically opened if
285 nothing is specified on the command line.
286 /etc/tags, $HOME/.clusterssh/tags
288 Very similar to clusters files but the definition is reversed. The
289 format is:
290 <host> <tag> [...]
292 This allows one host to be specified as a member of a number of
294 tags. This format can be clearer than using clusters files.
295 Extra tag files may be specified either as an option (see
297 "tag-file") or within the user's $HOME/.clusterssh/config file (see
298 "extra_tag_file" configuration option).
299 NOTE: All tags are added together
301 /etc/csshrc & $HOME/.clusterssh/config
303 This file contains configuration overrides - the defaults are as
304 marked. Default options are overwritten first by the global file,
305 and then by the user file.
306 NOTE: values for entries do not need to be quoted unless it is
308 required for passing arguments, e.g.
309 "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""
311 should be written as
313 "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"
315 auto_close = 5
317 Close terminal window after this many seconds. If set to 0
318 will instead wait on input from the user in each window before
319 closing. See also --autoclose and --no-autoclose
320 auto_quit = 1
322 Automatically quit after the last client window closes. Set to
323 0 to disable. See also --autoquit
324 auto_wm_decoration_offsets = no
326 Enable or disable alternative algorithm for calculating
327 terminal positioning.
328 comms = telnet
330 Sets the default communication method (initially taken from the
331 name of the program, but can be overridden here).
332 console_position = <null>
334 Set the initial position of the console - if empty then let the
335 window manager decide. Format is '+<x>+<y>', i.e. '+0+0' is
336 top left hand corner of the screen, '+0-70' is bottom left hand
337 side of screen (more or less).
338 external_command_mode = 0600
340 File mode bits for the external_command_pipe.
341 external_command_pipe = <null>
343 Define the full path to an external command pipe that can be
344 written to for controlling some aspects of ClusterSSH, such as
345 opening sessions to more clusters.
346 Commands:
348 "open <tag|hostname>" - open new sessions to provided tag or
350 hostname
351 "retile" - force window retiling
353 e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>
355 external_cluster_command = <null>
357 Define the full path to an external command that can be used to
358 resolve tags to host names. This command can be written in any
359 language. The script must accept a list of tags to resolve and
360 output a list of hosts (space separated on a single line). Any
361 tags that cannot be resolved should be returned unchanged.
362 A non-0 exit code will be counted as an error, a warning will
364 be printed and output ignored.
365 If the external command is given a "-L" option it should output
367 a list of tags (space separated on a single line) it can
368 resolve
369 extra_cluster_file = <null>
371 Define an extra cluster file in the format of /etc/clusters.
372 Multiple files can be specified, separated by commas. Both ~
373 and $HOME are acceptable as a reference to the user's home
374 directory, e.g.
375 "extra_cluster_file = ~/clusters, $HOME/clus"
377 extra_tag_file = <null>
379 Define an extra tag file in the format of /etc/tags. Multiple
380 files can be specified, separated by commas. Both ~ and $HOME
381 are acceptable as a reference to the user's home directory,
382 e.g.
383 "extra_tag_file = ~/tags, $HOME/tags"
385 key_addhost = Control-Shift-plus
387 Default key sequence to open AddHost menu. See "KEY SHORTCUTS"
388 for more information.
389 hide_menu = 0
391 If set to 1, hide the menu bar (File, Hosts, Send, Help) in the
392 console.
393 key_clientname = Alt-n
395 Default key sequence to send cssh client names to client. See
396 "KEY SHORTCUTS" for more information.
397 key_localname = Alt-l
399 Default key sequence to send hostname of local server to
400 client. See "KEY SHORTCUTS" for more information.
401 key_paste = Control-v
403 Default key sequence to paste text into the console window.
404 See "KEY SHORTCUTS" for more information.
405 key_quit = Control-q
407 Default key sequence to quit the program (will terminate all
408 open windows). See "KEY SHORTCUTS" for more information.
409 key_retilehosts = Alt-r
411 Default key sequence to retile host windows. See "KEY
412 SHORTCUTS" for more information.
413 key_username = Alt-u
415 Default key sequence to send username to client. See "KEY
416 SHORTCUTS" for more information.
417 key_user_1 = Alt-1
419 key_user_2 = Alt-2
420 key_user_3 = Alt-3
421 key_user_4 = Alt-4
422 Default key sequence to send user defined macros to client. If
423 the matching macro_user_1 macro is undefined, the sequence is
424 passed straight to the terminal. See "KEY SHORTCUTS" for more
425 information.
426 macro_servername = %s
428 macro_hostname = %h
429 macro_username = %u
430 macro_newline = %n
431 macro_version = %v
432 macro_user_1 = %1
433 macro_user_2 = %2
434 macro_user_3 = %3
435 macro_user_4 = %4
436 Change the replacement macro used when either using a 'Send'
437 menu item, or when pasting text into the main console.
438 macro_user_1_command =
440 macro_user_2_command =
441 macro_user_3_command =
442 macro_user_4_command =
443 User defined macros - the macro is run through the shell on the
444 server and the output is sent to the client. For example,
445 "macro_user_1_command=echo echo macro_user_1"
447 would send the text C<echo macro_user_1> into the terminal session.
449 "macro_user_1_command=env | grep CSSH"
451 would send the CSSH environment variables to the client.
453 The following environment variables are set in the shell of the
455 macro process
456 "CSSH_SERVERNAME"
458 "CSSH_HOSTNAME"
459 "CSSH_USERNAME"
460 "CSSH_CONNECTION_STRING"
461 "CSSH_CONNECTION_PORT"
462 "CSSH_VERSION"
463 macros_enabled = yes
464 Enable or disable macro replacement. Note: this affects all
465 the "macro_*" variables above.
466 max_addhost_menu_cluster_items = 6
468 Maximum number of entries in the 'Add Host' menu cluster list
469 before scrollbars are used
470 max_host_menu_items = 30
472 Maximum number of hosts to put into the host menu before
473 starting a new column
474 menu_host_autotearoff = 0
476 menu_send_autotearoff = 0
477 When set to non-0 will automatically tear-off the host or send
478 menu at program start
479 mouse_paste = Button-2 (middle mouse button)
481 Default key sequence to paste text into the console window
482 using the mouse. See "KEY SHORTCUTS" for more information.
483 rsh = /path/to/rsh
485 ssh = /path/to/ssh
486 telnet = /path/to/telnet
487 Set the path to the specific binary to use for the
488 communication method, else uses the first match found in $PATH
489 rsh_args = <blank>
491 ssh_args = "-x -o ConnectTimeout=10"
492 telnet_args = <blank>
493 Sets any arguments to be used with the communication method
494 (defaults to ssh arguments).
495 NOTE: The given defaults are based on OpenSSH, not commercial
497 ssh software.
498 NOTE: Any "generic" change to the method (e.g., specifying the
500 ssh port to use) should be done in the medium's own config file
501 (see "ssh_config" and $HOME/.ssh/config).
502 screen_reserve_top = 0
504 screen_reserve_bottom = 60
505 screen_reserve_left = 0
506 screen_reserve_right = 0
507 Number of pixels from the screen's side to reserve when
508 calculating screen geometry for tiling. Setting this to
509 something like 50 will help keep cssh from positioning windows
510 over your window manager's menu bar if it draws one at that
511 side of the screen.
512 terminal = /path/to/xterm
514 Path to the X-Windows terminal used for the client.
515 terminal_args = <blank>
517 Arguments to use when opening terminal windows. Otherwise
518 takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.
519 terminal_chdir = 0
521 When non-0, set the working directory for each terminal as per
522 'terminal_chdir_path'
523 terminal_chdir_path = $HOME/.clusterssh/work/%s
525 Path to use as working directory for each terminal when
526 'terminal_chdir' is enabled. The path provided is passed
527 through the macro parser (see the section above on
528 'macros_enabled'.
529 terminal_font = 6x13
531 Font to use in the terminal windows. Use standard X font
532 notation.
533 terminal_reserve_top = 5
535 terminal_reserve_bottom = 0
536 terminal_reserve_left = 5
537 terminal_reserve_right = 0
538 Number of pixels from the terminal's side to reserve when
539 calculating screen geometry for tiling. Setting these will
540 help keep cssh from positioning windows over your scroll and
541 title bars or otherwise overlapping the windows too much.
542 terminal_colorize = 1
544 If set to 1 (the default), then "-bg" and "-fg" arguments will
545 be added to the terminal invocation command-line. The terminal
546 will be colored in a pseudo-random way based on the host name;
547 while the color of a terminal is not easily predicted, it will
548 always be the same color for a given host name. After a while,
549 you will recognize hosts by their characteristic terminal
550 color.
551 terminal_bg_style = dark
553 If set to "dark", the terminal background will be set to black
554 and the foreground to the pseudo-random color. If set to
555 "light", then the foreground will be black and the background
556 the pseudo-random color. If terminal_colorize is "zero", then
557 this option has no effect.
558 terminal_size = 80x24
560 Initial size of terminals to use. NOTE: the number of lines
561 (24) will be decreased when resizing terminals for tiling, not
562 the number of characters (80).
563 terminal_title_opt = -T
565 Option used with "terminal" to set the title of the window
566 terminal_allow_send_events = -xrm '*.VT100.allowSendEvents:true'
568 Option required by the terminal to allow XSendEvents to be
569 received
570 title = cssh
572 Title of windows to use for both the console and terminals.
573 unmap_on_redraw = no
575 Tell Tk to use the UnmapWindow request before redrawing
576 terminal windows. This defaults to "no" as it causes some
577 problems with the FVWM window manager. If you are experiencing
578 problems with redraws, you can set it to "yes" to allow the
579 window to be unmapped before it is repositioned.
580 use_all_a_records = 0
582 If a hostname resolves to multiple IP addresses, set to 1 to
583 connect to all of them, not just the first one found. See also
584 "--use-all-a-records"}
585 use_hotkeys = 1
587 Setting to 0 will disable all hotkeys.
588 use_natural_sort = 0
590 Windows will normally sort in alphabetical order, i.e.: host1,
591 host11, host2. Setting to this 1 will change the sort order,
592 i.e.: host1, host2, host11. NOTE: You must have the perl module
593 Sort::Naturally installed.
594 user = $LOGNAME
596 Sets the default user for running commands on clients.
597 window_tiling = 1
599 Perform window tiling (set to 0 to disable)
600 window_tiling_direction = right
602 Direction to tile windows, where "right" means starting top
603 left and moving right and then down, and anything else means
604 starting bottom right and moving left and then up
605 NOTE: The key shortcut modifiers must be in the form "Control",
607 "Alt" or "Shift", e.g. with the first letter capitalised and the
608 rest lower case. Keys may also be disabled individually by setting
609 to the word "null".
610 $HOME/.clusterssh/send_menu
612 This (optional) file contains items to populate the send menu. The
613 default entry could be written as:
614 <send_menu>
616 <menu title="Use Macros">
617 <toggle/>
618 <accelerator>ALT-p</accelerator>
619 </menu>
620 <menu title="Remote Hostname">
621 <command>%s</command>
622 <accelerator>ALT-n</accelerator>
623 </menu>
624 <menu title="Local Hostname">
625 <command>%s</command>
626 <accelerator>ALT-l</accelerator>
627 </menu>
628 <menu title="Username">
629 <command>%u</command>
630 <accelerator>ALT-u</accelerator>
631 </menu>
632 <menu title="Test Text">
633 <command>echo "ClusterSSH Version: %v%n</command>
634 </menu>
635 </send_menu>
636 Submenus can also be specified as follows:
638 <send_menu>
640 <menu title="Default Entries">
641 <detach>yes</detach>
642 <menu title="Hostname">
643 <command>%s</command>
644 <accelerator>ALT-n</accelerator>
645 </menu>
646 </menu>
647 </send_menu>
648 Caveats:
650 There is currently no strict format checking of this file.
652 The format of the file may change in the future
653 If the file exists, the default entry (Hostname) is not added
654 The following replacement macros are available (note: these can be
656 changed in the configuration file):
657 %s Hostname part of the specific connection string to each client,
659 minus any username or port
660 %u Username part of the connection string to each client
662 %h Hostname of server where cssh is being run from
664 %n "RETURN" code
666 NOTE: requires XML::Simple to be installed
668
670 If you have any ideas about how to fix the below bugs, please get in
671 touch and/or provide a patch.
672 · Swapping virtual desktops can cause a redraw of all the terminal
674 windows. This is due to a lack of distinction within Tk between
675 switching desktops and minimising/maximising windows. Until Tk can
676 tell the difference between the two events, there is no fix (apart
677 from rewriting everything directly in X).
678
680 If you have issues running ctel, first try:
681 "ctel -e [user@]<hostname>[:port]"
683 This performs two tests to confirm cssh is able to work properly with
685 the settings provided within the $HOME/.clusterssh/config file (or
686 internal defaults).
687 1. Test the terminal window works with the options provided
689 2. Test telnet works to a host with the configured arguments
691 Configuration options to watch for in ssh are:
693 · SSH doesn't understand "-o ConnectTimeout=10" - remove the option
695 from the $HOME/.clusterssh/config file
696 · OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
698 or use "ForwardX11Trusted yes" in $HOME/.ssh/ssh_config (if you
699 change the default ssh options from "-x" to "-X")
700
702 A web site for comments, requests, bug reports and bug fixes/patches is
703 available at: <https://github.com/duncs/clusterssh>
704 If you require support, please run the following commands and create an
706 issue via: <https://github.com/duncs/clusterssh/issues>
707 "perl -V"
709 "perl -MTk -e 'print $Tk::VERSION,$/'"
711 "perl -MX11::Protocol -e 'print $X11::Protocol::VERSION,$/'"
713 "cat /etc/csshrc $HOME/.clusterssh/config"
715 Using the debug option (--debug) will turn on debugging output. Repeat
717 the option to increase the amount of debug. However, if possible
718 please only use this option with one host at a time, e.g. "cssh --debug
719 <host>" due to the amount of output produced (in both main and child
720 windows).
721
723 <https://github.com/duncs/clusterssh/wiki/>, "ssh", Tk::overview,
724 X11::Protocol, "perl"
725
727 Duncan Ferguson, "<duncan_j_ferguson at yahoo.co.uk>"
728
730 Copyright 1999-2018 Duncan Ferguson.
731 This program is free software; you can redistribute it and/or modify it
733 under the terms of either: the GNU General Public License as published
734 by the Free Software Foundation; or the Artistic License.
735 See http://dev.perl.org/licenses/ for more information.
737perl v5.30.1 2020-01-28 CTEL(1)