Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CSFTP(1)	      User Contributed Perl Documentation	      CSFTP(1)

       csftp - Cluster administration tool

       This documentation is for version: 4.16

       csftp [-a '<command>'] [-K <seconds>] [-q] [-c '<filename>'] [-x
       <cols>] [-C '<filename>'] [--debug [[...] || <INTEGER>]]	[-d] [-e
       '<[user@]<host>[:port]>'] [--fillscreen]	[-f '<font>'] [-h] [-L
       '[tag]']	[-H] [-o '<STRING>'] [-p <port>] [-Q] [-y <rows>] [-s] [-r
       '<filename>'] [-t '<STRING>'] [-g] [-T '<title>'] [-u] [-?] [-A]	[-l
       '<username>'] [-v]

       Also see	the individual man pages for each of these utilities

       ccon - Use 'console' as the communication method
       crsh - Use 'rsh'	as the communication method
       cssh - Use 'ssh'	as the communication method
       ctel - Use 'telnet' as the communication	method

       The command opens an administration console and an xterm	to all
       specified hosts.	 Any text typed	into the administration	console	is
       replicated to all windows.  All windows may also	be typed into

       This tool is intended for (but not limited to) cluster administration
       where the same configuration or commands	must be	run on each node
       within the cluster.  Performing these commands all at once via this
       tool ensures all	nodes are kept in sync.

       Connections are opened using sftp which must be correctly installed and

       Extra caution should be taken when editing files	as lines may not
       necessarily be in the same order;  assuming line	5 is the same across
       all servers and modifying that is dangerous.  It's better to search for
       the specific line to be changed and double-check	all terminals are as
       expected	before changes are committed.

   Further Notes
       Please also see "KNOWN BUGS".

       o   The dotted line on any sub-menu is a	tear-off, i.e. click on	it and
	   the sub-menu	is turned into its own window.

       o   Unchecking a	hostname on the	Hosts sub-menu will unplug the host
	   from	the cluster control window, so any text	typed into the console
	   is not sent to that host.  Re-selecting it will plug	it back	in.

       o   If your window manager menu bars are	obscured by terminal windows
	   see the "screen_reserve_XXXXX" options in the
	   $HOME/.clusterssh/config file (see "FILES").

       o   If the terminals overlap too	much see the "terminal_reserve_XXXXX"
	   options in the $HOME/.clusterssh/config file	(see "FILES").

       o   When	using ClusterSSH on a large number of systems to connect to a
	   single system using an SSH utility (e.g. you	issue a	command	to to
	   copy	a file using scp from the remote computers to a	single host)
	   and when these connections require authentication (i.e. you are
	   going to authenticate with a	password), the sshd daemon at that
	   location may	refuse connections after the number "MaxStartups"
	   limit in sshd_config	is exceeded.  (If this value is	not set, it
	   defaults to 10).  This is expected behavior;	sshd uses this
	   mechanism to	prevent	DoS attacks from unauthenticated sources.
	   Please tune sshd_config and reload the SSH daemon, or consider
	   using the ~/.ssh/authorized_keys mechanism for authentication if
	   you encounter this problem.

       o   If client windows fail to open, try running:

	   "csftp -e {single host name}"

	   This	will test the mechanisms used to open windows to hosts.	 This
	   could be due	to either the "-xrm" terminal option which enables
	   "AllowSendEvents" (some terminals do	not require this option, other
	   terminals have another method for enabling it - see your terminal
	   documentation) or the configuration of "sftp".

       Some of these options may also be defined within	the configuration
       file.  Default options are shown	as appropriate.

       --action	'<command>', -a	'<command>'
	   Run the command in each session, e.g. "-a 'vi /etc/hosts'" to drop
	   straight into a vi session.

       --autoclose <seconds>, -K <seconds>
	   Number of seconds to	wait before closing finished terminal windows.

       --autoquit, -q
	   Toggle automatically	quitting after the last	client window has
	   closed (overriding the config file).

       --cluster-file '<filename>', -c '<filename>'
	   Use supplied	file as	additional cluster file	(see also "FILES").

       --cols <cols>, -x <cols>
	   Number of columns

       --config-file '<filename>', -C '<filename>'
	   Use supplied	file as	additional configuration file (see also

       --debug [[...] || <INTEGER>]
	   Enable debugging.  Either a level can be provided or	the option can
	   be repeated multiple	times.	Maximum	level is 9.

       --dump-config, -d
	   Dump	the current configuration in the same format used by the
	   $HOME/.clusterssh/config file.

       --evaluate '<[user@]<host>[:port]>', -e '<[user@]<host>[:port]>'
	   Display and evaluate	the terminal and connection arguments to
	   display any potential errors.  The <hostname> is required to	aid
	   the evaluation.

	   Resize terminal windows to fill the whole available screen

       --font '<font>',	-f '<font>'
	   Specify the font to use in the terminal windows. Use	standard X
	   font	notation such as "5x8".

       --help, -h
	   Show	basic help text	and exit

       --list '[tag]', -L '[tag]'
	   List	available cluster tags.	Tag is optional.  If a tag is provided
	   then	hosts for that tag are listed.	NOTE: format of	output changes
	   when	using "--quiet"	or "-Q"	option.

       --man, -H
	   Show	full help text (the man	page) and exit

       --options '<STRING>', -o	'<STRING>'
	   Specify arguments to	be passed to ssh when making the connection.
	   NOTE: options for ssh should	normally be put	into the ssh
	   configuration file; see "ssh_config"	and $HOME/.ssh/config for more

	   Default: -x -o ConnectTimeout=10

       --port <port>, -p <port>
	   Specify an alternate	port for connections.

       --quiet,	-Q
	   Do not output extra text when using some options

       --rows <rows>, -y <rows>
	   Number of rows

       --show-history, -s
	   Show	history	within console window.

       --tag-file '<filename>',	-r '<filename>'
	   Use supplied	file as	additional tag file (see also "FILES")

       --term-args '<STRING>', -t '<STRING>'
	   Specify arguments to	be passed to terminals being used.

       --tile, -g
	   Toggle window tiling	(overriding the	config file).

       --title '<title>', -T '<title>'
	   Specify the initial part of the title used in the console and
	   client windows.

       --unique-servers, -u
	   Toggle connecting to	each host only once when a hostname has	been
	   specified multiple times.

       --usage,	-?
	   Show	synopsis and exit

       --use-all-a-records, -A
	   If a	hostname resolves to multiple IP addresses, toggle whether or
	   not to connect to all of them, or just the first one	(see also
	   config file entry).

       --username '<username>',	-l '<username>'
	   Specify the default username	to use for connections (if different
	   from	the currently logged in	user).	NOTE: will be overridden by

       --version, -v
	   Show	version	information and	exit

       The following arguments are supported:

       [user@]<hostname>[:port]	...
	   Open	an xterm to the	given hostname and connect to the
	   administration console.  The	optional port number can be used if
	   the server is not listening on the standard port.

       <tag> ...
	   Open	a series of xterms defined by <tag> in one of the
	   supplementary configuration files (see "FILES").

	   Note: specifying a username on a cluster tag	will override any
	   usernames defined in	the cluster.

       The following key shortcuts are available within	the console window,
       and all of them may be changed via the configuration files.

	   Open	the 'Add Host(s) or Cluster(s)'	dialogue box.  Multiple	host
	   or cluster names can	be entered, separated by spaces.

	   Paste in the	hostname part of the specific connection string	to
	   each	client,	minus any username or port, e.g.

	   "scp	/etc/hosts server:files/<Alt-n>.hosts"

	   would replace the <Alt-n> with the client's name in each window.

	   Paste in the	hostname of the	server cssh is being run on

	   Quit	the program and	close all connections and windows.

	   Retile all the client windows.

	   Paste in the	username for the connection

	   Run the matching user defined macro on the server and send the
	   output to the client

       Open up a session to 3 servers
	   $ csftp server1 server2 server3

       Open up a session to a cluster of servers identified by the tag 'farm1'
       and give	the controlling	window a specific title, where the tag is
       defined in one of the default configuration files
	   $ csftp -T 'Web Farm	Cluster	1' farm1

       Connect to different servers using different login names.  NOTE:	this
       can also	be achieved by setting up appropriate options in the
       configuration files.  Do	not close the console when the last terminal
	   $ csftp user1@server1 admin@server2

       Open up a cluster defined in a non-default configuration	file
	   $ csftp -c $HOME/cssh.extra_clusters	db_cluster

       Override	the configured/default port to use 2022	instead
	   $ csftp -p 2022 server1 server2

       /etc/clusters, $HOME/.clusterssh/clusters
	   These files contain a list of tags to server	names mappings.	 When
	   any name is used on the command line	it is checked to see if	it is
	   a tag.  If it is a tag, then	the tag	is replaced with the list of
	   servers.  The format	is as follows:

	   <tag> [user@]<server>[:port]	[user@]<server>[:port] [...]


	       # List of servers in live
	       live admin1@server1 admin2@server2:2022 server3 server4

	   All comments	(marked	by a #)	and blank lines	are ignored.  Tags may
	   be nested, but be aware of using recursive tags as they are not
	   checked for.

	   Servers can be defined using	expansion macros:

	   "webservers websvr{a,b,c}"

	   would be expanded to

	   "webservers websvra websvrb websvrc"


	   "webservers websvr{6..9}"

	   would be expanded to

	   "webservers websvr6 websvr7 websvr8 websvr9"

	   Extra cluster files may also	be specified either as an option on
	   the command line (see "cluster-file") or in the user's
	   $HOME/.clusterssh/config file (see "extra_cluster_file"
	   configuration option).

	   NOTE: the last tag read overwrites any pre-existing tag of that

	   NOTE: there is a special cluster tag	called "default" - any tags or
	   hosts included within this tag will be automatically	opened if
	   nothing is specified	on the command line.

       /etc/tags, $HOME/.clusterssh/tags
	   Very	similar	to clusters files but the definition is	reversed.  The
	   format is:

	   <host> <tag>	[...]

	   This	allows one host	to be specified	as a member of a number	of
	   tags.  This format can be clearer than using	clusters files.

	   Extra tag files may be specified either as an option	(see
	   "tag-file") or within the user's $HOME/.clusterssh/config file (see
	   "extra_tag_file" configuration option).

	   NOTE: All tags are added together

       /etc/csshrc & $HOME/.clusterssh/config
	   This	file contains configuration overrides -	the defaults are as
	   marked.  Default options are	overwritten first by the global	file,
	   and then by the user	file.

	   NOTE: values	for entries do not need	to be quoted unless it is
	   required for	passing	arguments, e.g.

	   "terminal_allow_send_events="-xrm '*.VT100.allowSendEvents:true'""

	   should be written as

	   "terminal_allow_send_events=-xrm '*.VT100.allowSendEvents:true'"

	   auto_close =	5
	       Close terminal window after this	many seconds.  If set to 0
	       will instead wait on input from the user	in each	window before
	       closing.	See also --autoclose and --no-autoclose

	   auto_quit = 1
	       Automatically quit after	the last client	window closes.	Set to
	       0 to disable.  See also --autoquit

	   auto_wm_decoration_offsets =	no
	       Enable or disable alternative algorithm for calculating
	       terminal	positioning.

	   command_pre =
	   command_post	=
	       Add extra commands around the communication method.  For

	       command_pre= . $HOME/virtualenvs/default/bin/active ;
	       command_post= | ct

	       would allow for using Python virtual envronments	and then
	       piping all shell	output through "chromaterm" for	syntax
	       highlighting.  Note: you	must use appropriate command
	       separators/terminators to keep the meaning of the command
	       pipline (such as	";" and	"|" between commands).

	       These are not put through macro parsing.

	   comms = sftp
	       Sets the	default	communication method (initially	taken from the
	       name of the program, but	can be overridden here).

	   console_position = <null>
	       Set the initial position	of the console - if empty then let the
	       window manager decide.  Format is '+<x>+<y>', i.e. '+0+0' is
	       top left	hand corner of the screen, '+0-70' is bottom left hand
	       side of screen (more or less).

	   external_command_mode = 0600
	       File mode bits for the external_command_pipe.

	   external_command_pipe = <null>
	       Define the full path to an external command pipe	that can be
	       written to for controlling some aspects of ClusterSSH, such as
	       opening sessions	to more	clusters.


	       "open <tag|hostname>" - open new	sessions to provided tag or

	       "retile"	- force	window retiling

	       e.g.: "echo 'open localhost'" /path/to/external_command_pipe >>

	   external_cluster_command = <null>
	       Define the full path to an external command that	can be used to
	       resolve tags to host names.  This command can be	written	in any
	       language.  The script must accept a list	of tags	to resolve and
	       output a	list of	hosts (space separated on a single line).  Any
	       tags that cannot	be resolved should be returned unchanged.

	       A non-0 exit code will be counted as an error, a	warning	will
	       be printed and output ignored.

	       If the external command is given	a "-L" option it should	output
	       a list of tags (space separated on a single line) it can

	   extra_cluster_file =	<null>
	       Define an extra cluster file in the format of /etc/clusters.
	       Multiple	files can be specified,	separated by commas.  Both ~
	       and $HOME are acceptable	as a reference to the user's home
	       directory, e.g.

	       "extra_cluster_file = ~/clusters, $HOME/clus"

	   extra_tag_file = <null>
	       Define an extra tag file	in the format of /etc/tags.  Multiple
	       files can be specified, separated by commas.  Both ~ and	$HOME
	       are acceptable as a reference to	the user's home	directory,

	       "extra_tag_file = ~/tags, $HOME/tags"

	   key_addhost = Control-Shift-plus
	       Default key sequence to open AddHost menu.  See "KEY SHORTCUTS"
	       for more	information.

	   hide_menu = 0
	       If set to 1, hide the menu bar (File, Hosts, Send, Help)	in the

	   key_clientname = Alt-n
	       Default key sequence to send cssh client	names to client.  See
	       "KEY SHORTCUTS" for more	information.

	   key_localname = Alt-l
	       Default key sequence to send hostname of	local server to
	       client.	See "KEY SHORTCUTS" for	more information.

	   key_paste = Control-v
	       Default key sequence to paste text into the console window.
	       See "KEY	SHORTCUTS" for more information.

	   key_quit = Control-q
	       Default key sequence to quit the	program	(will terminate	all
	       open windows).  See "KEY	SHORTCUTS" for more information.

	   key_retilehosts = Alt-r
	       Default key sequence to retile host windows.  See "KEY
	       SHORTCUTS" for more information.

	   key_username	= Alt-u
	       Default key sequence to send username to	client.	 See "KEY
	       SHORTCUTS" for more information.

	   key_user_1 =	Alt-1
	   key_user_2 =	Alt-2
	   key_user_3 =	Alt-3
	   key_user_4 =	Alt-4
	       Default key sequence to send user defined macros	to client.  If
	       the matching macro_user_1 macro is undefined, the sequence is
	       passed straight to the terminal.	 See "KEY SHORTCUTS" for more

	   macro_servername = %s
	   macro_hostname = %h
	   macro_username = %u
	   macro_newline = %n
	   macro_version = %v
	   macro_user_1	= %1
	   macro_user_2	= %2
	   macro_user_3	= %3
	   macro_user_4	= %4
	       Change the replacement macro used when either using a 'Send'
	       menu item, or when pasting text into the	main console.

	   macro_user_1_command	=
	   macro_user_2_command	=
	   macro_user_3_command	=
	   macro_user_4_command	=
	       User defined macros - the macro is run through the shell	on the
	       server and the output is	sent to	the client.  For example,

	       "macro_user_1_command=echo echo macro_user_1"

			   would send the text C<echo macro_user_1> into the terminal session.

	       "macro_user_1_command=env | grep	CSSH"

			   would send the CSSH environment variables to	the client.

	       The following environment variables are set in the shell	of the
	       macro process

	   macros_enabled = yes
	       Enable or disable macro replacement.  Note: this	affects	all
	       the "macro_*" variables above.

	   max_addhost_menu_cluster_items = 6
	       Maximum number of entries in the	'Add Host' menu	cluster	list
	       before scrollbars are used

	   max_host_menu_items = 30
	       Maximum number of hosts to put into the host menu before
	       starting	a new column

	   menu_host_autotearoff = 0
	   menu_send_autotearoff = 0
	       When set	to non-0 will automatically tear-off the host or send
	       menu at program start

	   mouse_paste = Button-2 (middle mouse	button)
	       Default key sequence to paste text into the console window
	       using the mouse.	 See "KEY SHORTCUTS" for more information.

	   rsh = /path/to/rsh
	   ssh = /path/to/ssh
	   telnet = /path/to/telnet
	       Set the path to the specific binary to use for the
	       communication method, else uses the first match found in	$PATH

	   rsh_args = <blank>
	   ssh_args = "-x -o ConnectTimeout=10"
	   telnet_args = <blank>
	       Sets any	arguments to be	used with the communication method
	       (defaults to ssh	arguments).

	       NOTE: The given defaults	are based on OpenSSH, not commercial
	       ssh software.

	       NOTE: Any "generic" change to the method	(e.g., specifying the
	       ssh port	to use)	should be done in the medium's own config file
	       (see "ssh_config" and $HOME/.ssh/config).

	   screen_reserve_top =	0
	   screen_reserve_bottom = 60
	   screen_reserve_left = 0
	   screen_reserve_right	= 0
	       Number of pixels	from the screen's side to reserve when
	       calculating screen geometry for tiling.	Setting	this to
	       something like 50 will help keep	cssh from positioning windows
	       over your window	manager's menu bar if it draws one at that
	       side of the screen.

	   terminal = /path/to/xterm
	       Path to the X-Windows terminal used for the client.

	   terminal_args = <blank>
	       Arguments to use	when opening terminal windows.	Otherwise
	       takes defaults from $HOME/.Xdefaults or $HOME/.Xresources file.

	   terminal_chdir = 0
	       When non-0, set the working directory for each terminal as per

	   terminal_chdir_path = $HOME/.clusterssh/work/%s
	       Path to use as working directory	for each terminal when
	       'terminal_chdir'	is enabled.  The path provided is passed
	       through the macro parser	(see the section above on

	   terminal_font = 6x13
	       Font to use in the terminal windows.  Use standard X font

	   terminal_reserve_top	= 5
	   terminal_reserve_bottom = 0
	   terminal_reserve_left = 5
	   terminal_reserve_right = 0
	       Number of pixels	from the terminal's side to reserve when
	       calculating screen geometry for tiling.	Setting	these will
	       help keep cssh from positioning windows over your scroll	and
	       title bars or otherwise overlapping the windows too much.

	   terminal_colorize = 1
	       If set to 1 (the	default), then "-bg" and "-fg" arguments will
	       be added	to the terminal	invocation command-line.  The terminal
	       will be colored in a pseudo-random way based on the host	name;
	       while the color of a terminal is	not easily predicted, it will
	       always be the same color	for a given host name.	After a	while,
	       you will	recognize hosts	by their characteristic	terminal

	   terminal_bg_style = dark
	       If set to "dark", the terminal background will be set to	black
	       and the foreground to the pseudo-random color.  If set to
	       "light",	then the foreground will be black and the background
	       the pseudo-random color.	 If terminal_colorize is "zero", then
	       this option has no effect.

	   terminal_size = 80x24
	       Initial size of terminals to use. NOTE: the number of lines
	       (24) will be decreased when resizing terminals for tiling, not
	       the number of characters	(80).

	   terminal_title_opt =	-T
	       Option used with	"terminal" to set the title of the window

	   terminal_allow_send_events =	-xrm '*.VT100.allowSendEvents:true'
	       Option required by the terminal to allow	XSendEvents to be

	   title = cssh
	       Title of	windows	to use for both	the console and	terminals.

	   unmap_on_redraw = no
	       Tell Tk to use the UnmapWindow request before redrawing
	       terminal	windows.  This defaults	to "no"	as it causes some
	       problems	with the FVWM window manager.  If you are experiencing
	       problems	with redraws, you can set it to	"yes" to allow the
	       window to be unmapped before it is repositioned.

	   use_all_a_records = 0
	       If a hostname resolves to multiple IP addresses,	set to 1 to
	       connect to all of them, not just	the first one found.  See also

	   use_hotkeys = 1
	       Setting to 0 will disable all hotkeys.

	   use_natural_sort = 0
	       Windows will normally sort in alphabetical order, i.e.: host1,
	       host11, host2.  Setting to this 1 will change the sort order,
	       i.e.: host1, host2, host11. NOTE: You must have the perl	module
	       Sort::Naturally installed.

	   user	= $LOGNAME
	       Sets the	default	user for running commands on clients.

	   window_tiling = 1
	       Perform window tiling (set to 0 to disable)

	   window_tiling_direction = right
	       Direction to tile windows, where	"right"	means starting top
	       left and	moving right and then down, and	anything else means
	       starting	bottom right and moving	left and then up

	   NOTE: The key shortcut modifiers must be in the form	"Control",
	   "Alt" or "Shift", e.g. with the first letter	capitalised and	the
	   rest	lower case.  Keys may also be disabled individually by setting
	   to the word "null".

	   This	(optional) file	contains items to populate the send menu.  The
	   default entry could be written as:

	       <menu title="Use	Macros">
	       <menu title="Remote Hostname">
	       <menu title="Local Hostname">
	       <menu title="Username">
	       <menu title="Test Text">
		   <command>echo "ClusterSSH Version: %v%n</command>

	   Submenus can	also be	specified as follows:

	       <menu title="Default Entries">
		 <menu title="Hostname">


	   There is currently no strict	format checking	of this	file.
	   The format of the file may change in	the future
	   If the file exists, the default entry (Hostname) is not added

	   The following replacement macros are	available (note: these can be
	   changed in the configuration	file):

	   %s  Hostname	part of	the specific connection	string to each client,
	       minus any username or port

	   %u  Username	part of	the connection string to each client

	   %h  Hostname	of server where	cssh is	being run from

	   %n  "RETURN"	code

	   NOTE: requires XML::Simple to be installed

       If you have any ideas about how to fix the below	bugs, please get in
       touch and/or provide a patch.

       o   Swapping virtual desktops can cause a redraw	of all the terminal
	   windows.  This is due to a lack of distinction within Tk between
	   switching desktops and minimising/maximising	windows.  Until	Tk can
	   tell	the difference between the two events, there is	no fix (apart
	   from	rewriting everything directly in X).

       If you have issues running csftp, first try:

       "csftp -e [user@]<hostname>[:port]"

       This performs two tests to confirm cssh is able to work properly	with
       the settings provided within the	$HOME/.clusterssh/config file (or
       internal	defaults).

       1.  Test	the terminal window works with the options provided

       2.  Test	sftp works to a	host with the configured arguments

       Configuration options to	watch for in ssh are:

       o   SSH doesn't understand "-o ConnectTimeout=10" - remove the option
	   from	the $HOME/.clusterssh/config file

       o   OpenSSH-3.8 using untrusted ssh tunnels - use "-Y" instead of "-X"
	   or use "ForwardX11Trusted yes" in $HOME/.ssh/ssh_config (if you
	   change the default ssh options from "-x" to "-X")

       A web site for comments,	requests, bug reports and bug fixes/patches is
       available at: <>

       If you require support, please run the following	commands and create an
       issue via: <>

       "perl -V"

       "perl -MTk -e 'print $Tk::VERSION,$/'"

       "perl -MX11::Protocol -e	'print $X11::Protocol::VERSION,$/'"

       "cat /etc/csshrc	$HOME/.clusterssh/config"

       Using the debug option (--debug)	will turn on debugging output.	Repeat
       the option to increase the amount of debug.  However, if	possible
       please only use this option with	one host at a time, e.g. "cssh --debug
       <host>" due to the amount of output produced (in	both main and child

       <>, "ssh", Tk::overview,
       X11::Protocol, "perl"

       Duncan Ferguson,	"<duncan_j_ferguson at>"

       Copyright 1999-2018 Duncan Ferguson.

       This program is free software; you can redistribute it and/or modify it
       under the terms of either: the GNU General Public License as published
       by the Free Software Foundation;	or the Artistic	License.

       See for more information.

perl v5.32.1			  2021-08-28			      CSFTP(1)


Want to link to this manual page? Use this URL:

home | help