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

==========
= README =
==========

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>

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

NOTE: MindTerm contains code implementing the RSA algorithm which is
patented and subject to licensing in certain countries (e.g. U.S. and
Canada). It is therefore illegal to use MindTerm (even non-commercially)
without proper licensing from RSA in these countries.

However, if there is any interest I can write wrapper-code in java to
be able to use the rsa-ref code (i.e. through 'native' binding in
java). This will of course only work with the standalone version
(i.e. the applet can't be used). Please contact me if you are
interested in this. Also, if anybody knows of an existing java-wrapper
around the rsa-ref code please let me know. See <a href="ftp://ftp.rsa.com/rsar\
ef/README">here</a> for the rsa-ref
README (only for U.S. or Canadian citizens).

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



1.INSTALLATION:

To use as an applet please download file 'mindtermapplet.zip' or
compile the source-files (optionally bundling them into a
jar-file). Assuming you have the jar-file (mindbright.jar) you must
write an html-page as in the example in APPLET USAGE below. The applet
can be given permissions to function more as a "real" ssh-client
(i.e. be able to do tunneling and connect to an arbitrary
server). This functionality depends on your browser.

In a future version of Mindterm the jar-file may be signed using an
official certificate in which case it can request extra permissions in
for example the Netscape browser to be able to connect "freely" and also
utilize the system-clipboard.

In order to use this program as a standalone client please download
the file 'mindtermapplication.zip' or compile the source-files. You
also 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 (also read
about running java-programs with the runtime including running
programs residing in a jar-file).

Examples of where the java-runtime can be found:

Win32 and Solaris:
    http://www.javasoft.com/products/
Linux:
    http://www.blackdown.org/java-linux.html

MindTerm has been tested with jdk1.1.6(v5), jdk1.1.5 on Linux (with
2.0.x kernels). In linux with jdk1.1.7v1a, there seems to be something
wrong with the awt-stuff building the dialogs :-(. On Windows NT4 and
Windows-95/98 it is also tested 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.


2.GENERAL:

When started either as an applet or as a stand-alone program MindTerm
is fully configurable. You may supply all settable parameters (see
below) on the command-line or as applet-params. Additionally when used
as a stand-alone program you can choose to save all settings in one
single file (default-settings) OR on a per server basis, i.e. each
new sshd you connect to will have its settings in a separate file.

SSH-parameters:
(all these can be set to values in parenthesis where applicable)
server   : name of server to connect to (N/A)
port     : port on server to connect to (0-65535)
usrname  : username to login as (N/A)
cipher   : name of block cipher to use ( none des 3des rc4 blowfish )
authtyp  : method of authentication ( rhosts rsa passwd rhostsrsa tis kerberos kerbtgt )
idfile   : name of file containing identity, rsa-keys (N/A)
display  : display definition, i.e <host>:<screen> (N/A)
mtu      : maximum packet size to use, 0 means use default (4096 - 256k or 0)
escseq   : sequence of characters to type to enter local command-shell (N/A)
secrand  : level of security in random-seed, for generating session-key (0-2,
           0 is lowest (default) and 2 is highest (very slow :-))
(all these can be set to either 'true' or 'false')
x11fwd   : indicates whether X11 display is forwarded or not
prvport  : indicates whether to use a privileged source port or not
forcpty  : indicates whether to allocate a pty or not
remfwd   : indicates whether we allow remote connects to local forwards
idhost   : indicates whether to check hosts host-key in 'known_hosts'
portftp  : indicates whether to enable ftp 'PORT' command support

Terminal-parameters:
(all these can be set to either 'true' or 'false')
rv       : reverse video
aw       : autowrap of line if output reaches edge of window
rw       : reverse autowrap when going off left edge of window
al       : auto-linefeed
sk       : reposition scroll-area to bottom on keyboard input
si       : reposition scroll-area to bottom on output to screen
lp       : use PgUp, PgDn, Home, End keys locally or escape them to shell
sc       : put <CR><NL> instead of <NL> at end of lines when selecting
vi       : visible cursor
ad       : ASCII Line-draw-characters
le       : do local echo
sf       : scale font when resizing window (not yet implemeted)
ct       : map <ctrl>+<space> to <NUL> (e.g. for 'mark set' in emacs)
(all these can be set to values in parenthesis where applicable)
te       : name of terminal to emulate ( xterm linux scoansi att6386 sun vt220
           vt100 ansi vt52 xterm-color linux-lat  at386   vt102 )
fn       : name of font to use in terminal (Dialog, SansSerif, Serif, Monospaced,
           Helvetica, TimesRoman, Courier, DialogInput, ZapfDingbats)
fs       : size of font to use in terminal (N/A)
sl       : number of lines to save in "scrollback" buffer (0 - 32k)
sb       : scrollbar position (none/left/right)
bg       : background color ('#0'...'#15' or '<r>,<g>,<b>',
           #<n> means "standard" terminal color <n> these are:
           0  = black
           1  = red
           2  = green
           3  = yellow
           4  = blue
           5  = magenta
           6  = cyan
           7  = white
           8  = bright black (!)
           9  = bright red
           10 = bright green
           11 = bright yellow
           12 = bright blue
           13 = bright magenta
           14 = bright cyan
           15 = bright white
           alternatively rgb-values (decimal) are give e.g. 255,0,0 for red)
fg       : foreground color ('#0'...'#15' or '<r>,<g>,<b>', see above)
rg       : resize gravity, fixpoint of screen when resizing (southwest/northwest)
bs       : character to send on BACKSPACE ('BS' or 'DEL')

There are also special properties to set tunnels, these are:

local0, local1, ... ,localN
remote0, remote1, ... ,remoteN

Their syntax is as follows:

localN   : [/<plugin>/<local-port>:<remote-ip>:<remote-port>
remoteN   : [/<plugin>/<remote-port>:<local-ip>:<local-port>

They are enumerated, i.e. if you have three local-forward-definitions
they will be local0, local1 and local2. The same goes for
remoteN. These properties are used in the exact same way as all other
properties (i.e. they can either be entered on the command-line, as
applet-params or in the property-files).

For example to set up tunnels to telnet, imap and smtp on the local
ports 4711, 4712 and 4713 to the remote side:

java -cp mindbright.jar mindbright.application.MindTerm -server www.mindbright.se
    -local0 4711:localhost:23 -local1 4712:localhost:143 -local2 4713:localhost:25


There is a local command shell where all settings can be viewed and/or
altered.  To enter this command-shell you press ctrl-D at the prompt
(i.e. before having logged in) or you can select the 'Local command
shell' option in the 'MindTerm Main' menu.  If are running in "dumb"
mode you might have to press ENTER after pressing ctrl-D.

This is what is displayed when entering the command-shell:

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

mindterm> 


The following commands are available in the command-shell:

go                                    Start SSH-session with current settings.
quit                                  Quit program (or disconnect if connected).
add <l|r> [/<plug>/]<port>:<host>:<port>  (see below).
del <l|r> <listen-port>|*             Delete local/remote forward (* = all).
list [ssh | term]                     Lists ssh- and/or terminal-settings.
set [<parameter> <value>]             Set value of a ssh-parameter.
tset [<parameter> <value>]            Set value of a terminal-parameter.
key [<bits>]                          Generate RSA key-pair (of length <bits>).
help                                  Display this list, but you knew that :-).


3.STANDALONE USAGE:

Examples of how to start MindTerm as a standalone program:
(NOTE: the whole command to start the runtime is written on one line)

Linux/jdk1.1.6:

/usr/local/java/bin/java -classpath /usr/local/java/lib/classes.zip:
    /home/mats/java/mindbright.jar mindbright.application.MindTerm

Win32/jdk1.1.x:

c:\jdk1.1.x\bin\java -classpath c:\jdk1.1.6\lib\classes.zip;c:\mindbright\mindbright.jar
    mindbright.application.MindTerm

Win32/jre1.1.x:

c:\jdk1.1.x\bin\java -cp c:\mindbright\mindbright.jar
    mindbright.application.MindTerm

Win32/jdk/jre1.2:

c:\jdk1.2\bin\java -cp c:\mindbright\mindbright.jar
    mindbright.application.MindTerm

Win32/jview:

jview /cp:p mindbright.jar mindbright.application.MindTerm


When run as a standalone application MindTerm takes two types of
command-line options. One type is preceeded with a single hyphen ('-').
These are the parameters (see above) followed with their respective
value, for example:

java -cp mindbright.jar mindbright.application.MindTerm -server www.mindbright.se
    -port 22 -x11fwd true -authtyp rsa

The other type of options are given with two preceeding hyphens
('--'). These are the special MindTerm stand-alone options. When run
with the stand-alone option '--?' the following is displayed:

usage: MindTerm [options] [properties] [command]
Options:
  --c            Enable local command-shell.
  --d            No terminal-window, only dumb command-line and port-forwarding.
  --h dir        Name of the MindTerm home-dir (default: ~/.ssh/).
  --p <no | def> Use no property-files or only default property-file.
  --q            Quiet; don't query for server/username if given.
  --v            Verbose; display verbose debugging messages.
  --V            Display version number only.


These are the valid stand-alone options.

The stand-alone options MUST be first on the command-line (right after
the program-name). For example:

java -cp mindbright.jar mindbright.application.MindTerm --p no --h /home/mats/mindterm
     -server www.mindbright.se -port 22 -x11fwd true -authtyp rsa

The stand-alone version of MindTerm uses a file called 'known_hosts'
to identify the hosts that you connect to (to avoid man-in-the-middle
attacks after first contact with server). This file has the exact same
format (and functionality) as the file 'known_hosts' which is used by
the unix version of the standard ssh-client. If you do not wish to use
this feature you must disable it with the parameter 'idhost' as in:

java -cp mindbright.jar mindbright.application.MindTerm --p no --h /home/mats/mindterm
     -server www.mindbright.se -idhost false
                                   ^^^^^^^^^^^^^

All parameters are saved in a default-settings file, this file can be
manually edited (or explicitly saved from the 'Main Menu' -> 'Save
default properties') for personalization of MindTerm. When MindTerm is
run for the first time it creates the default file. When running
MindTerm after this the default settings will be loaded before any
command-line options are applied (if the "--p def" command-line option
was given at start up, the defaults will also be saved at exit). All
servers visited will have their own settings saved to separate files
making it possible to use different settings for each server. This
feature may be disabled with the "--p def" option. If the "--p no"
option is given NO property-files will be used making all settings
done last only for the current session.

Note, when a server is given in the default config and the program is
started without "--p def" or "--p no" this server's config will be
saved to a separate file at exit or when a new server is connected
to. This implies that the server-field in the default config should be
left empty if you plan to use many different servers (and want their
settings saved).


4.APPLET USAGE:

See page <http://www.mindbright.se/norm_sshlogin.html> for an example
on how to use the applet. As stated above all settable parameters may
be set with applet-params, for example:

<applet archive="mindbright.jar" code=mindbright.applet.MindTerm.class width=580 height=400>
<!-- These parameters are parameters that are listed in 'GENERAL' above -->
<param name=port value="22">
<param name=cipher value="3des">

<!-- These parameters are special for the applet, compareable to '--' standalone -->
<param name=rows value="26"><!-- number of rows in terminal -->
<param name=cols value="80"><!-- number of columns in terminal -->
<param name=sepframe value="false"><!-- wheter to run in a separate frame or not -->
<param name=verbose value="true"><!-- output verbose debug-info to java-console -->
<param name=sshhome value="c:\ssh\"><!-- If authorized to access local files, this is home-dir -->
</applet>

You may give any number of parameters to the applet. You only have to
supply the ones you want, all values have default settings so you need
not supply any parameters if you choose.


5.MINDTUNNEL SSHD

TODO:
For now check <http://www.mindbright.se/mindtunnel.html>


6.OTHER

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/>

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