source: other-projects/trunk/gs3-release-maker/tasks/sshtaskdef/src/mindbright/README.097@ 14627

=================
= RELEASE NOTES =
=================

MindTerm, release 0.97 - Jan 10, 1999

MindTerm is an entirely FREE(*) SSH (currently v1.5) client program
written in 100% pure Java (non-certified). It can be run as a standalone
program or as an applet in a webpage. It is more than yet another ssh-
client, apart from beeing multi-platform/web-enabled, it's also a full
set of packages enabling people to make their own ssh-client and/or 
"ssh-aware" java-applications/applets (e.g. special/proprietary proxies,
ssh-aware applications/applets "speaking" to proprietary daemons behind
firewall, tunneling-only-client etc). It has one other notable feature
setting it apart from some other clients, a special ftp-tunnel which works
with "ordinary" ftpd's "behind" the sshd.

(*) Licensed under Gnu's General Public License (GPL), see the file
    COPYING or go to <http://www.gnu.org/copyleft/gpl.html>

New in this release (applet now more usable otherwise mainly terminal-enhancemnents):
    o  New copyright-policy (again :-). Now the code is GPL.
    o  Now uses random generator and MD5 hash from Logi Ragnarsson's (GPL'd) cryptonite
       (<http://www.hi.is/~logir/cryptonite/>, it's excelent check it out!) which
       makes the applet runnable from 'most' (at last :-) browsers
       (e.g. <many-OS's>/Netscape4.x, <many-OS's>/java-plugin, win32/IE4)
    o  Added support for selecting terminal-emulation (with 'set term
       <term-type>' in local command-shell, NOTE: the TERM env. variable is only
       set at initial login)
    o  Added several terminal-types (xterm-color/xterm/linux/scoansi etc.), only
       xterm/xterm-color tested more thoroughly, the rest is tested very briefly
    o  Colors work (in terminals supporting colors)
    o  Line-draw characters work (in terminals supporting it)
    o  Mouse works (only xterm/xterm-color)
    o  Function keys now work, sending respective terminal's esc-seq.
    o  PgUP, PgDN, Home and End keys can be used either "locally" for controlling the
       scroll-back buffer OR they can be set to send proper escape-sequences
       (use 'set lp <true|false>' in local command-shell)
    o  Fixed bug: Keyboard focus is lost when iconified in WinDOS (95/98/NT)
       (NOTE: this bugfix is quite strange, I don't understand this fully)
    o  Fixed bug: Keyboard focus never acquired when run as applet with plugin when
       NOT run in a separate frame

KNOWN BUGS:
    o  The fix for keyboard-focus when deiconified introduces an oddity when MindTerm
       is used as an applet (<param name=sepframe value="false">) where it snatches focus
       from the browser itself! :-). I will look into the whole thing...
    o  Keyboard focus seems still to be an issue when running as an applet inside
       the applet's own Frame when using the java-plugin (I'm bewildered, I definately need
       some more awt-studying...).
    o  One or two people have reported ArrayIndexOutOfBoundsException when
       typing <backspace>, I can not reproduce this, nor can I understand how
       this can happen :-(, please report if you experince/find this.
    o  Linux line-draw characters doesn't work when normal line-draw characters have
       been displayed?! (i.e. first use xterm then logout, switch term to linux and
       reconnect, now we are misinterpreting them??)
    o  Linux line-draw characters doesn't work when doing debug messages in
       terminal-interpreter)?!? (DEBUG is true in TerminalXTerm.java).
       This is a ghost, alternatively I'm too tired... Could this be related to the above? :-)
    o  Sometimes things seems to lock up (e.g. 1 minutes delay between 'login:'
       and 'password:'). I can't seem to find any explanation, a guess is that
       certain JIT's do something funny when for example compiling the DES.class file??.
       Try running with -nojit to see if it helps.

TODO-LIST (in no particular order):
    o  Property-files (on a per server basis) to be able to store
       parameters (e.g. server-host-keys, identity-file, port-number
       etc.). Also the terminal-settings will be saved between sessions
    o  SSH2 support (of course :-) (not for long...)
    o  Clean TermainlWin.update() a bit (maybe remove ATTR_BG/ATTR_FG and instead allways
       use them)
    o  Optimize some, e.g. lot's can be done final...
    o  Better key-mapping support (this is not easy given the KeyEvent in java...)
    o  Ansi IRM (insert mode) in terminal (TerminalWin.setInsertMode())
    o  Telnet (maybe "Kerbified" and/or "SSLified" aswell)
    o  Make the plugins more usable (clean/effective), maybe add some other proxy-service?
       (suggestions welcome!)
    o  Priority/mtu on a per tunnel basis (i.e. make some tunnels "more
       responsive" than others)
    o  Lot's of error-handling and general clean-up
    o  A GUI with a menubar and such, can be useful :-)
    o  Check all terminal modes to work correctly... (it is still quite untested)
    o  Scaling font in terminal instead of changing rows/cols when resizing terminal
    o  Documentation...
    o  et.c. et.c.

=================

MindTerm has been tested with jdk1.1.6(v5), jdk1.1.5 on Linux (with
2.0.x kernels), on Windows NT4 and Windows-95/98 also with
jdk1.1.7A/jdk1.2. As an applet also with Linux/Netscape-4.07,
Win32/Netscape-4.5, Win32/IE4.01, win32/java-plugin-1.2. All tests
were against sshd versions 1.2.17, 1.2.21, 1.2.25 and 1.2.26. Your
milage with other platforms/versions may vary. Please read this entire
text before starting to use MindTerm.

All comments and bug-reports should be sent to:
<[email protected]>

Information about this program and its source code can be found at:
<http://www.mindbright.se/mindterm/>

Features list:
    o  Password and RSA/rhosts-RSA authentication
    o  3DES/DES, Blowfish and RC4 block-ciphers
    o  Standard SSH port-forwarding (including X11-forwarding)
    o  Special FTP port-forwarding (see FTP-NOTE below)
    o  Plugin-architecture for adding other (than FTP)
       protocol-specific "proxies"
    o  Full vt102 support, also supports full xterm/xterm-color (with
       mouse) and some other terminals
    o  "applet-enabled", the class mindbright.applet.MindTerm can be used to run MindTerm
       as an applet (both in a separate Frame or in the Applet-Panel itself)
    o  Copy/paste with mouse selection ('copy-on-select' and insert-key pastes)
    o  Cursor-keys (with DECCKM toggle)
    o  PgUP, PgDN, Home and End keys can be used either "locally" for controlling the
       scroll-back buffer OR they can be set to send proper escape-sequences
    o  NonGUI mode, i.e. run at command-line without opening a
       terminal-window
    o  MTU option (to be able to controll maximum packet size)
    o  The ssh package can be used quite easily by itself to "SSH-enable"
       an arbitrary java-application
    o  The terminal and security packages can (of course) also be used by itself
    o  Cross-platform (it's java :-)

FTP-NOTE: The FTP port-forwarding is done entirely in the client, no
patching of the sshd is needed. The FTP port-forwarding is only
supported for local-port-forward, i.e. you can connect to a remote
FTP-server through the tunnel. It works "100% transparent" with
"modern" ftp-clients that use the PASV ftp-command (e.g. Netscape
navigator). Older (and not so smart) clients that still use the PORT
command are in trouble, since the remote-port-forwards only can be
initialized at startup (i.e. before the sshd goes into its
server-loop) the best we can do is to pre-allocate the remote-port at
startup and reuse it through-out an FTP session. The problem with this
is of course the ftpd's way of using the ftp-data port for connecting
back to the client hence rendering our remote-ports unusable by the
ftpd's ftp-data-port for about a minute after disconnect (i.e. when
the tcp-socket is in state TIME_WAIT). This is partly worked around by
pre-allocating a number of ports on the remote end using them in a
round-robin fashion enabling us to do some PORT-commands in a row, if
however we do too many in about a minutes time we're out of available
connections back to ourselves making the ftp-server angry :-). This
could of course easily be solved by patching the sshd but that might
not be feasible in all situations.


INSTALLATION:

In order to use this program you need the java-runtime (jdk or jre)
from Javasoft or any other party providing a port for your
platform. It should work with any 1.1.x or 1.2 jdk/jre (it also works
with Netscape's and Microsofs's browser-supplied java-runtimes).
Please read the installation notes for your respective platform before
trying to run MindTerm.

Examples of where the java-runtime can be found:

Linux:
    http://www.blackdown.org/java-linux.html

Win32 and Solaris:
    http://www.javasoft.com/products/

When you have installed the java-runtime and made yourself familiar
with how to use it you are ready to run the MindTerm. The
commandline-options of MindTerm are somewhat similar to those of the
free ssh-client for unix. When run with option '-?' MindTerm says:

usage: MindTerm [options] [<server> [<command>]]
Options:
  -l user     Log in using this user name.
  -d          No terminal-window, only dumb command-line and port-forwarding.
  -i file     Name of the RSA identity file (default: ~/.ssh/identity).
  -v          Verbose; display verbose debugging messages.
  -V          Display version number only.
  -a authtype Select authentication type: ``passwd'', ``rsa'', ``rhostsrsa''
  -c cipher   Select encryption algorithm: ``blowfish'', ``3des'', ``des''...
  -p port     Connect to this port.  Server must be on the same port.
  -L [/plugin/]listen-port:host:port Forward local port to remote address.
  -R [/plugin/]listen-port:host:port Forward remote port to local address.
Thank you for using MindTerm...

Note that you don't have to give any command-line options in order to run
MindTerm, all settings can be changed from a simple command-shell
inside the program (see below).

The program can be run with a command something like the following:

java -classpath <libpath>/classes.zip:<mindpath>/mindbright.jar mindbright.application.MindTerm

where:

<libpath> is wherever your java-runtime libraries resides. Note that if you use
          a CLASSPATH environment variable you might use that instead and just add
          the mindbright.jar to it like:
          CLASSPATH = CLASSPATH:/usr/local/myjavaapps/mindbright.jar

<mindpath> is wherever you put the mindbright.jar file.

In the case where you have added the file TO the class-path (i.e. not put
the file IN a directory in the class-path). The command would of course just be:

java mindbright.application.MindTerm

Note that when using Windows NT/95 you use ';' instead of ':' in the path, but you knew that.


'STANDALONE' USAGE:

When the program is started it does some initialisation, this can take
several seconds depending on the speed of your machine. When the
copyright notice has been printed you are prompted for the SSH-server
to connect to, this looks like:

Copyright (c) 1998,99 by Mindbright Technology AB, Stockholm, Sweden
Initializing random generator, please wait...done

(press ^D before logging in to enter local command-shell)

SSH-server: wintermute

To enter the local command-shell you press ctrl-D at the prompt
(i.e. before having logged in).  If running in "dumb" mode you might
have to press ENTER after pressing ctrl-D. Like:

...entering local command-shell (type 'h' for help).

mindterm> 

**When typing help (or just h) at the prompt in the local command-shell:

The following commands are available:

go                                    Start SSH-session with current settings.
quit                                  Quit program.
add <l|r> [/<plug>/]<port>:<host>:<port>  (see below).
del <l|r> <listen-port>|*             Delete local/remote forward (* = all).
list                                  Lists current parameters and forwards.
set [<parameter> <value>]             Set value of a parameter.
help                                  Display this list, but you knew that :-).

(do 'set' without arguments to list parameter-usage)

Examples of adding a remote/local tunnel:
> add r 4711:www.foo.com:80           Adds a remote tunnel at port 4711 back to
                                      www.foo.com port 80 without a plugin,
                                      i.e. default tunneling behaviour.
> add l /ftp/4711:ftp.bar.com:21      Adds a local tunnel going to ftp.bar.com
                                      port 21 using the ftp protocol-plugin to
                                      handle protocol specific needs.

NOTE: The first character of the command can be used instead of the full word.
NOTE2: Sometimes ftp-forward to localhost/127.0.0.1 fails, use hostname instead.

**When typing set (or just s) by itself at the prompt in the local command-shell:

Do 'set <parameter> <value>' where parameter is one of the following:
server   : name of server to connect to
port     : port on server to connect to
username : username to login as
cipher   : name of block cipher to use
authtype : method of authentication
sshdir   : home-directory of ssh-config
id-file  : name of file containing identity (rsa-keys)
x11-fwd  : indicates whether X11 display is forwarded or not
display  : display definition (i.e. <host>:<screen>)
mtu      : maximum packet size to use (0 means use default)
privport : indicates whether to use a privileged port or not (locally)
escseq   : sequence of characters to type to enter local command-shell
term     : type of terminal to emulate
lp       : use PgUp, PgDn, Home, End keys local or escape them to shell
fn       : name of font to use in terminal
fs       : size of font to use in terminal
sl       : number of lines to save in "scrollback" buffer
sb       : scrollbar position (or 'none' for no scrollbar)
rv       : set/unset reverse video
aw       : do autowrap of line if output reaches edge of screen
si       : reposition scroll-area to bottom on output to screen
sk       : reposition scroll-area to bottom on keyboard input
sc       : put <CR><NL> instead of <NL> at end of lines when selecting
(For possible parameter-values use 'list')

**When typing list (or just l) at the prompt in the local command-shell:

SSH settings:
server   : null
port     : 22
username : Administrator
cipher   : 3des ( none des 3des rc4 blowfish )
authtype : passwd ( rhosts rsa passwd rhostsrsa tis kerberos kerbtgt )
sshdir   : C:\WINNT\Profiles\Administrator\.ssh\
id-file  : identity
x11-fwd  : false (true/false)
display  : localhost:0
mtu      : <default> (4096 - 256k)
privport : false (true/false)
escseq   : '~$'

local tunnels:
         <none>
remote tunnels:
         <none>

Terminal settings (use 'set' to change):
terminal type (term)               : xterm-color ( xterm linux scoansi att6386 sun
 vt220 vt100 ansi vt52 xterm-color linux-lat  at386   vt102 )
local pagectrl-keys (lp)           : false (true/false)
terminal font (fn)                 : Courier (Dialog, SansSerif, Serif, Monospaced,
 DialogInput)
terminal font size (fs)            : 12 (system dep.)
save lines (sl)                    : 1024 (0 - 32k)
scroll bar (sb)                    : right (none/left/right)
reverse video (rv)                 : false (true/false)
auto wrap (aw)                     : true (true/false)
scroll to end on output (si)       : true (true/false)
scroll to end on key (sk)          : true (true/false)
copy <CR><NL> instead of <NL> (sc) : false (true/false)
(parameter names and permitted values in parentheses)


'APPLET' USAGE:

See page <http://www.mindbright.se/sshlogin.html


ABOUT THE AUTHOR
This software is written and maintained by Mats Andersson
<[email protected]> of Mindbright Technology in Sweden.