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.

* 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.  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.

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

* 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.

* You can now use the Meta key (ALT) inside of your cluster windows,
but be aware that the drop-down menus in the administration window 
will catch the following:

   ALT-f, Alt-o, Alt-s, and Alt-h (as well as capitalized letters)


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 box.  Please refer to
the manpage for Xsecurity for more information.

* On Debian sid with gnome-terminal, you may receive errors like:

> Option --login is no longer supported in this version of 
> gnome-terminal; you might want to create a profile with the 
> desired setting, and use the new --window-with-profile option

These are because /usr/bin/gnome-terminal.wrapper passes "--login"
if "-ls" is passed to it.  If this causes you grief, configure
your .csshrc with "terminal_options = -sb -sl 1024" or any option
string that doesn't include "-ls"

* 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, 29 Jun 2006 22:41:52 -0700