==========
= README =
==========
!!! UNDER CONSTRUCTION, SEE FAQ FOR SOME RELEVANT INFO !!!

MindTerm is an entirely FREE(*) SSH (currently v1.5) client program written in
100% pure Java (non-certified). It can be run as a stand-alone program or as an
applet in a webpage. It can be run with or without a GUI (stand-alone). 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. However, it is
more than yet another ssh-client, apart from beeing multi-platform and
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).

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


1.OVERVIEW
blablabla


2.QUICKSTART
blablabla


3.INSTALLATION

In order to use this program as a standalone client please download the file
'mindtermapplication.zip' or compile the source-files (optionally bundling them
into a jar-file). 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:

Linux:
	http://www.blackdown.org/java-linux.html
	http://www.alphaworks.ibm.com/tech/linuxjvm

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

Macintosh:
	http://www.apple.com/java/

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 (e.g. mindterm.jar) you must write an html-page as in the example in
"4.APPLET USAGE" below. If you are using a cryptographically signed binary
version of MindTerm as an applet from your Netscape or IE browser you will be
able to use it exactly as the stand-alone version (or any other ssh-client),
i.e. connect to any host, set up tunnels, save/load settings from file, use
system clip-board etc. The applet might also be given these permissions
"manually" depending on your browser/appletviewer.

Please read this entire text before starting to use MindTerm! Good luck, some
would say you'll need it.


4.MENUS

The easiest way to learn how MindTerm works and what features it provides is to
look through this brief walk-through of all menus in MindTerm.

4.1 File
4.1.1 New Terminal (Ctrl+Shift+N)
This will create a new MindTerm window with the same settings as the first
MindTerm window of this session, i.e. all parameters (command-line or applet)
given to MindTerm at startup will have effect in each new terminal created.

4.1.2 Clone Terminal (Ctrl+Shift+O)
This will create a new MindTerm window with the exact same settings as the
window it is created from. If the window contains a connected session, the new
window will be automatically logged in to the same ssh-server. Note that the new
window will not have any open tunnels since the window from where it is created
have the tunnels opened (preventing the new window from opening them).

4.1.3 Connect... (Ctrl+Shift+C)
4.1.4 Disconnect (Ctrl+Shift+D)
4.1.5 Load Settings...
4.1.6 Save Settings (Ctrl+Shift+S)
4.1.7 Save Settings As...
4.1.8 Create RSA Identity...
4.1.9 Capture To File...
4.1.10 Send ASCII File...
4.1.11 Close (Ctrl+Shift+E)
4.1.12 Exit (Ctrl+Shift+X)


4.2 Edit
4.2.1 Copy (Ctrl+Ins)
4.2.2 Paste (Shift+Ins)
4.2.3 Copy & Paste
4.2.4 Select All (Ctrl+Shift+A)
4.2.5 Find... (Ctrl+Shift+F)
4.2.6 Clear Screen
4.2.7 Clear Scrollback
4.2.8 VT Reset


4.3 Settings
4.3.1 SSH Connection... (Ctrl+Shift+H)
4.3.2 Terminal... (Ctrl+Shift+T)
4.3.3 Terminal Misc... (Ctrl+Shift+M)
4.3.4 Local Command-Shell
4.3.5 Auto Save Settings
4.3.6 Auto Load Settings


4.4 Tunnels
4.4.1 Basic...
4.4.2 Advanced...
4.4.3 Tunnel Wizard...
4.4.4 Current Connections...


4.5
4.5.1 Help Topics...
4.5.2 About MindTerm


5.PARAMETERS

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 (see "6.STANDALONE USAGE") or as applet-params (see "7.APPLET
USAGE"). Additionally when access to the local file system is available you can
choose to save all settings to file 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)
realsrv  : real address of sshd if it is behind a firewall, only used with
           protocol-plugins (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')
alive    : Connection keep-alive interval in seconds (0-600, 0 means none)
x11fwd   : indicates whether X11 display is forwarded or not (true/false)
prvport  : indicates whether to use a privileged source port or not (true/false)
forcpty  : indicates whether to allocate a pty or not (true/false)
remfwd   : indicates whether we allow remote connects to local forwards (true/false)
idhost   : indicates whether to check hosts host-key in 'known_hosts' (true/false)
portftp  : indicates whether to enable ftp 'PORT' command support (true/false)

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
im       : insert mode
al       : do 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
vb       : visual bell
ct       : map <ctrl>+<space> to <NUL>
dc       : toggle 80/132 columns
da       : enable 80/132 switching
cs       : copy on mouse-selection
fn       : name of font to use in terminal
fs       : size of font to use in terminal
gm       : geometry of terminal

(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 )
sl       : number of lines to save in "scrollback" buffer (0-8192)
sb       : scrollbar position (left, right, none)
bg       : background color (black, red, green, yellow, blue,
           magenta, cyan, white, or one of these with 'i_' before
           for intensified version e.g. i_white, OR you may use an
           arbitrary RGB-value such as: 125,102,247)
fg       : foreground color (same as 'bg')
rg       : resize gravity, fixpoint of screen when resizing (top, bottom)
bs       : character to send on BACKSPACE (BS, DEL)
de       : character to send on DELETE (BS, DEL)
sd       : delimeter characters for click-selection (N/A)

There are also special properties to configure 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

(NOTE: 'localhost' here means "locally" on the ssh-server, i.e. the telnet,
imap, and smtp servers all run on the same machine as the ssh-server)


There is also an optional (activated with '--c' or 'cmdsh') 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 'Settings' menu.  If you 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 :-).


6.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.x:

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


Win32/jdk1.1.x:

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


Win32/jre1.1.x:

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


Win32/jdk/jre1.2:

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


Win32/jview: (microsoft's JVM supplied with IE4 and later, older version does
not work)

jview /cp:p mindtermfull.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 "5.PARAMETERS") 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.
  --f <file>     Use settings from the given file.
  --h dir        Name of the MindTerm home-dir (default: ~/mindterm/).
  --m <no | pop> Use no menus or popup menu instead of menubar.
  --p <save | load | both | none>
                 Sets automatic save/load flags for property-files.
  --q            Quiet; don't query for server/username if given.
  --v            Verbose; display verbose debugging messages.
  --V            Display version number only.
  --?            Display this help.


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 both --h /home/mats/mindterm
	 -server www.mindbright.se -port 22 -x11fwd true -authtyp rsa

When access to the local file-system is available 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 both --h /home/mats/mindterm
	 -server www.mindbright.se -idhost false
                                   ^^^^^^^^^^^^^

The parameters (the ones given with one preceding hyphen) are by default saved
in settings files on a per server basis. The settings files are automatically
loaded when connecting to a specific server. The automatic save and load feature
can be disabled in which case settings must be explicitly loaded/saved. The
settings file can also be manually edited.


blablabla


7.APPLET USAGE

See page <http://www.mindbright.se/newssh.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="mindterm.jar" code=mindbright.application.MindTerm.class width=580 height=400>
<!-- These parameters are parameters that are listed in "5.PARAMETERS" -->
<param name=port value="22">
<param name=cipher value="3des">
<param name=gm value="80x32+0-0">
<param name=local0 value="4711:wintermute:23">
<param name=local1 value="/ftp/4712:wintermute:21">

<!-- These parameters are special for the applet, compareable to '--' standalone -->
<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=debug value="true"><!-- give more debug-info to java-console -->
<param name=quiet value="true"><!-- quiet mode, don't query for server/username if given -->
<param name=cmdsh value="true"><!-- enable/disable local command-shell -->
<param name=menus value="pop2"><!-- enable/disable pulldown or popup menus -->
<param name=menus value="autoprops"><!-- enable/disable automatic save/load of settings -->
<param name=menus value="propsfile"><!-- file containing settings (properties) to load -->
<param name=menus value="commandline"><!-- complete commandline if running a single command only -->
<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.

An applet may be run in basically three ways, namely with an applet-enabled
browser, with a java-plugin installed in a browser or with a standalone
appletviewer. All three ways are perfectly legal ways of running MindTerm note
however that the html-code for running an applet using a java-plugin is not the
same as for running it with an appletviewer or an applet-enabled browser.

blablabla (more on java-plugin, differences between browser-versions, signed
applets etc.)


8.USING FTP TUNNELS
blablabla

9.ABOUT CRYPTOGRAPHIC SIGNATURES
blablabla


10.TESTED PLATFORMS

MindTerm has been tested with jdk1.1.6(v5), jdk1.1.5 (blackdown-ports) and ibm's
jdk1.1.6 port on Linux (with 2.0.x and 2.2.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.


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


12.MINDVNC VNC CLIENT
TODO:
For now check <http://www.mindbright.se/english/technology/products/mindvnc.html>


13.OTHER

All comments and bug-reports should be sent to:
<mindterm@mindbright.se>

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
<mats@mindbright.se> of Mindbright Technology in Sweden.


14.RSA LICENSE

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



