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