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

The 3.x version is a complete rewrite of the 2.x source code.  Significant
changes in this version are support for the Meta key (ALT) and the use of
X11::Protocol inside the code.

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 ~/.csshrc 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 creating a $HOME/.csshrc file and either
mapping (or unmapping) the key as appropriate.

You can quickly create a .csshrc file containing all of the default
settings with "cssh -u > ~/.csshrc"  Note that if you already have a
.csshrc file, it will be overwritten with the defaults.  To simply
see what settings are being used, invoke "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 * 

Also of note is the fact that 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 ~/.csshrc 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 
~/.csshrc.  

If you are having trouble getting clusterssh to work with uxterm,
you should either delete the "terminal_allow_send_events" option 
from your .csshrc 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 ~/.csshrc)
wterm (only with "terminal_allow_send_events =" in ~/.csshrc)
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>  Mon, 08 Jun 2009 16:44:36 -0700