clusterssh for Debian
---------------------

The 4.01.x version of clusterssh migrates the configuration from ~/.csshrc
to ~/.clusterssh/config.  This conversion will be attempted automatically
if you start cssh if ~/.clusterssh/config does not exist.  It is left to 
the user to delete their .csshrc file.  Note that the conversion is not 
attempted if ~/.clusterssh/config is present.  It is suggested that you 
rename .csshrc after the conversion and test.  Clusterssh will read 
/etc/csshrc, ~/.csshrc, and ~/clusterssh/config in that order.  If you 
would like clusterssh to attempt the conversion again, you can restore
.csshrc and delete .clusterssh/config.

Similarly, clusters are now migrated to a separate file, 
~/.clusterssh/clusters, which should be referenced in the config file by 
the extra_cluster_file parameter.  The conversion process will attempt
to create the clusters file and update the config file, but YMMV.

In the current version of 4.01.01, the ~/.csshrc_send_menu file is still 
used.

Upstream development is active, so if you encounter problems with clusterssh
after upgrading, refer to the manpage: 
   $ man cssh

or the upstream changelog:

   $ zless /usr/share/doc/clusterssh/changelog.gz

for changes to options.  You may find it helpful to save a copy of
your ~/.clusterssh/config and create a clean copy, as described below.

* KEYBOARD MAPPING *

If you are having difficulty with keys being mapped to clusterssh functions
when you would prefer the keystrokes be sent directly to the cssh sessions,
you can control this behavior by editing ~/.clusterssh/config file and either
mapping (or unmapping) the key as appropriate.

You can quickly create the config file containing all of the default
settings with "cssh -u >".

Change settings in this file to suit your preferences.  For example, 
if you'd prefer that Control-v not paste text in the cut buffer, 
but instead send ^V to the terminals being controlled, change
this line:

	key_paste=Control-v

to this (if you don't want any keyboard mapping for paste):

	key_paste=null

or to some other key combination as appropriate.

You can invoke cssh with -dD to see debugging information about what
keystrokes were received and how they were interpreted and sent.

Note, the canonical source for this information is the manpage.  It is 
included here for convenience.


* TERMINAL EMULATORS * 

Clusterssh no longer allows the use of just any Debian terminal emulator 
that provides x-terminal-emulator, since a number of them don't support
the XSendEvents resource.  By default, clusterssh will invoke xterm.  To 
change this, create or modify your config file to contain the line:

	terminal = /path/to/my/favorite/terminal-emulator

Note that this terminal emulator must accept the "-xrm" command line 
switch to set XTerm.VT100.allowSendEvents:true (or something that
does the same thing).  If your terminal emulator provides equivalent
functionality with a different switch, or provides it implicitly, you
can set this with the parameter "terminal_allow_send_events" in 
the config file.

If you are having trouble getting clusterssh to work with uxterm,
you should either delete the "terminal_allow_send_events" option 
from your config file, or update the value to: 

  UXTerm.VT100.allowSendEvents:true

or simply:

  *.VT100.allowSendEvents:true

Older versions of clusterssh would create the .csshrc file with the
class set to "XTerm" which prevents the uxterm from receiving events.

The terminal emulator must also accept:

	-e <command>
	-font <font>
	
System-wide configure changes can be made by editing /etc/csshrc.

Debian terminal emulator packages tested and known NOT to work
with clusterssh:
---------------------------------------------------------------
(please send updates either directly to the maintainer or via
the bug tracking system)

gnome-terminal
konsole
kterm
xvt
xfce4-terminal
mlterm

Debian terminal emulator packages tested and believed to work:
--------------------------------------------------------------

xterm
rxvt
rxvt-beta
aterm (only with "terminal_allow_send_events =" in ~/.clusterssh/config)
wterm (only with "terminal_allow_send_events =" in ~/.clusterssh/config)
pterm (although it requires input focus before any output is displayed)
eterm (although it doesn't use the -font switch)

Note that xterm-wrappers like lxterm and uxterm that immediately
background themselves will NOT work.

If you use a script to spawn your terminals, make sure that it takes
takes $* as an argument, and that it doesn't background itself.


Changes from the upstream version and usage notes:
--------------------------------------------------

(As of the Debian packaging of upstream version 3.26, the
Debian version does not alter the behavior of ClusterSSH.)


FAQ:
----

* If you use cssh to to connect to a cluster and then issue a command
like:

   scp -p somehost:/tmp/foo .

and you don't already have keys setup for authentication, you will get
the error:

> ssh_exchange_identification: Connection closed by remote host

for every unauthenticated connection above the setting of MaxStartups
in /etc/ssh/sshd_config.  (If not present, this value defaults to 10.)

You can get around this by either using authorized_keys for authentication,
or increasing the value for MaxStartups and reloading sshd.

* If you receive errors like:

> Xlib: connection to ":0.0" refused by server
> Xlib: No protocol specified
>
> couldn't connect to display ":0.0" at /usr/lib/perl5/Tk/MainWindow.pm
> line 55.

when trying to invoke cssh as a different user than the one running your
X server, you can run:

	xhost +local:
	
as the same user running the X server to allow all local X clients to
connect to your X server.  Note that there is some security risk related
to this if other users have shell access to your system.  Please refer to
the manpage for Xsecurity for more information.

* If you're interested in changing the accelerator keys, read the manpage
and override the defaults in your ~/.csshrc file.

Comments, suggestions, and bug reports welcome!

 -- tony mancill <tmancill@debian.org>  Thu, 21 Jun 2012 20:40:21 -0700
