User
Document of jttt - "Java TCP Tunneling Tool" version 1.0
Date:
Developers
(user names in sourceforge.net)
Jeffkorn
jiechau
Outlines:
1.
What is jttt?
2.
System Requirement
3.
How to Install
4.
How to Run
5.
Known Bugs and Faults
6.
The License Comments
7.
Contact Us
1.
What is jttt?
"Java TCP Tunneling Tool" is
meant to construct a network mechanism to extend the usage of most TCP services
between Firewalls. For example, you have a Server (running web server) and a
Client, both resided inside their own firewalls, then you can use an
Intermediate Machine and run jttt on all these 3 machines to build the tunnels,
to let the Client open web pages from the Server. Illustrate with:
Client port:8080 Intermediate port:9001 Server port:80 jttt tunnel
jttt tunnel (Client:8080
=> Intermediate:9001)
(Intermediate:9001
=> Server:80)
Originally we use "http://Server:80/"
to open the web pages. Since The Server is resided inside firewall, we use jttt
and an Intermediate Machine to patch the connection. Now you use http://localhost:8080/
to open the remote web pages.
2.
System Requirement
Firstly because this is a beta
version, it can be executed on a limited environment. The requirement for
Client, Server, and Intermediate Machine are:
For the Client Machine:
(1).Operating System: OS
Independent
(2).Having J2SE (Java 2 SDK,
Standard Edition) 1.4 or above installed.
For the Server Machine:
(1).Operating System: OS
Independent
(2).Having J2SE (Java 2 SDK,
Standard Edition) 1.4 or above installed.
For the Intermediate Machine:
(1).Operating System:
UNIX-based OS (because we would use Shell Script)
(2).Having J2SE (Java 2 SDK,
Standard Edition) 1.4 or above installed.
(3).Having SSH
Server (sshd) installed, either the SECSH (from ssh.com) or OpenSSH
(from openssh.org) is ok.
[P.S.] SECSH,
"SSH Secure Shell" is the SSH Communication Security's
official
release (implementation) of Secure Shell. (please reference:
http://www.ssh.com). OpenSSH is another implementation of SSH, plesase visit: http://www.openssh.org
(4).The SSH Server should be
running Secure Shell Protocol version 2.
(5).You need a
"user account" in the Intermediate Machine. (No need to have root or
administrator account)
Make sure your environments meet all the
requirements above, then you could continue the installation procedure.
3.
How to Install
The installation only needs you to unpack
this package, and modify some settings in some scripts or configuration file.
The “jttt.properties” configuration file:
First of all, there is an configuration
file in $INSTALL_DIR/bin/jttt.properties. No matter you are running jttt in the
Client, Server or Intermediate Machine, you need to edit this jttt.properties
to meet your environment. Here is the explanation of the variables in jttt.properties:
These 4 variables are for the
Intermediate Machine:
SSHServerType=2
The SSH Server version in your
Intermediate Machine.
SSHServerType=1 means you use SECSH (from
ssh.com)
SSHServerType=2 means you use OpenSSH
(from openssh.org)
sInterMediaServerPort=9000
The listening port in the Intermediate Machine,
it is used for Client and Server Machines to build communication. This is a TCP
port to listen on, for the Client and Server to connect to the Intermediate
Machine. You can choose any port number other then 9001~9100 (these 100 ports
are reserved in jttt programs). Here we use port 9000 as example.
sINSTALL_DIR=/home/jch280/jttt
The directory in the Intermediate Machine,
where you put your jttt package (the $INSTALL_DIR).
sSSHKEYconfigFile=/home/jch280/.ssh/authorized_keys
The Public Key Authorization File,
associated to the account (here the example is 'jch280') you own in the Intermediate
Machine. In the normal cases, if your Intermediate Machine runs SECSH, then
this file is $HOME/.ssh2/authorization. And if your Intermediate Machine runs
OpenSSH, then this file is $HOME/.ssh/authorized_keys
These 5 variables are for the Clint or
Server Machines:
sHostname=sparky.cs.nyu.edu
The Hostname or IP Address of you
Intermediate Machine
sServerPort=9000
The listening port in Intermediate
Machine, used for Client and Server Machines to build communication. (the same
as "sInterMediaServerPort" above).
sAccount=jch280
Your user account to access the
Intermediate Machine.
sUsername=jie
sPassword=xxxxxx
sUsername and sPassword is the jttt
user:pass pairs you set up in the $INSTALL_DIR/data/password.txt the Client and
Server machines use these data to access the Intermediate Machine. You could
edit the $INSTALL_DIR/data/password.txt manually.
Installation for the Client
Machine:
(1).Download the
jttt release package, and unpack it to your installed directory, let's call it
$INSTALL_DIR. This way you would have the directory structure looks like this,
then it's correct:
$INSTALL_DIR/bin
$INSTALL_DIR/lib
$INSTALL_DIR/data
(2).Edit the $INSTALL_DIR/bin/jttt.properties
Installation for the Server
Machine:
(the same installation
procedure as the Client Machine)
Installation for the
Intermediate Machine:
(1).Download the
jttt release package, and unpack it to your installed directory, let's call it
$INSTALL_DIR. This way you would have the directory structure looks like this,
then it's correct:
$INSTALL_DIR/bin
$INSTALL_DIR/lib
$INSTALL_DIR/data
(2).Edit the file
$INSTALL_DIR/bin/jttt.properties
(the same as mentioned above
in Client Machine part)
(3).Edit 2 files:
Edit
$INSTALL_DIR/bin/keepAlive.sh:
In "keepAlive.sh", you should
edit the very first line to indicate the Shell to execute this script.
Currently we use KornShell 93. (#!/home/unixtool/bin/ksh in our test system).
You could assign the correct path to your own Shell, any Shell would be ok. Then
you should edit these 2 variables to meet your system setting:
sHomeDir= <set to your
$INSTALL_DIR>
JAVA_HOME= <set to your
JAVA installed directory>
For example, if you unpack the jttt
package to /home/jch280/jttt (your $INSTALL_DIR=/home/jch280/jttt) and your JDK
is installed in /opt/java, then these 2 lines would looks like this:
sHomeDir=/home/jch280/jttt
JAVA_HOME= /opt/j2sdk1.4.2
Edit
$INSTALL_DIR/bin/check.sh:
In "check.sh", you should edit
the very first line to indicate the Shell to execute this script. Currently we
use KornShell 93. (#!/home/unixtool/bin/ksh in our test system). You could
assign the correct path to your own Shell, any Shell would be ok. Then you
should edit these 2 variables to meet your system setting:
sHomeDir= <set to your
$INSTALL_DIR>
sAuthorizationFile= <set to
your SSH Public Key authorization file>
For example, if you unpack the jttt
package to /home/jch280/jttt (your $INSTALL_DIR=/home/jch280/jttt) and your SSH
Public Key authorization file is /home/jch280/.ssh2/authorization, then these 2
lines would looks like this:
sHomeDir=/home/jch280/jttt
sAuthorizationFile=/home/jch280/.ssh/authorized_keys
About the authorization file, by default
every user account in the system will have the authorization file in the
default location: "$HOME/.ssh2/authorization" (for SECSH) and
"$HOME/.ssh/authorized_keys" (for OpenSSH). This file is used for the
Public Key Authentication method in SSH2 protocol. The format of this file differ
from SSH Servers. But you don't need to worry about the content of this file.
The only thing you need to know is where it is. For more information, you could
reference:
http://www.ssh.com/support/documentation/online/ssh/adminguide/30/Public-Key_Authentication-2.html
http://www.ssh.com/support/documentation/online/ssh/winhelp/32/manually_editing_the_authorization_file.html
http://www.openbsd.org/cgi-bin/man.cgi?query=sshd
(3).Finally, don't forget to make these
.sh files as 'executable' by owner (chmod)
4.
How to Run
Run jttt in Client, Server and
Intermediate Machine, and you can achieve the tunneling function. Here we use
an example with configuration to explain how to run jttt.
Firstly, you should run jttt
in the Intermediate Machine:
(1).Assume you
have an account 'jch280' in the Intermediate Machine, and the Intermediate
Machine's hostname is sparky.cs.nyu.edu. The jttt is installed in
/home/jch280/jttt (your $INSTALL_DIR) and the SSH Server is running (for
example, using OpenSSH), with your own Public Key authorization file in
/home/jch280/.ssh/authorized_keys
(2).Configure the
$INSTALL_DIR/data/password.txt file by manually editing it. (in this example:
/home/jch280/data/password.txt) This file contains username:password pairs for
using the jttt system, the format is: every single line contains an
username:password pair. no comments, no spaces allowed. For example:
jie:xxxxxx
jlk:yyyyyy
This means you have 2 jttt users: user
"jie" has password "xxxxxx", and the second user
"jlk" has password "yyyyyy". You can add your own
user:pass. In the later examples, we will continue use this 2 jttt user:pass
pair.
(3).Go to $INSTALL_DIR/bin
directory (in this example: /home/jch280/jttt/bin)
(4).Run Intermediate with no argument
(they are all defined in the jttt.properties file)
% java -classpath .:jttt.jar Intermediate
Notice that you should run the command
exactly as above, especially you CAN'T omit the "." from the
classpath argument. This is for the ClassLoader in Java program to load ResourceBundle
file.
(4).When the first
time you run it, it will generate the key files. When you see the running
message stops, it means that the Intermediate is set up and ready.
(5).Later when you
start the jttt in Server and Client Machine, you could run the shell script
$INSTALL_DIR/bin/check.sh in Intermediate Machine from time to time, to monitor
the connection from Server Machines. You could do this by opening another
terminal in the Intermediate Machine and run the check.sh.
Secondly, you should run jttt
in the Server Machine:
(1).Running jttt
on Server Machine is done by first switching to the directory $INSTALL_DIR/bin
(2).Run JTTT with the
following 3 arguments:
% java -classpath .:jttt.jar JTTT
<forward_method> <local_port_to_forward> <comment_string>
Again, you CAN'T omit the "."
from the classpath argument.
forward_method:
The Port Forwarding methods in SSH, its value is either "Remote" or
"Local". In the Server machine you SHOULD use only
"Remote". Notice that you should key-in exactly "Remote"
("R" is in upper case, with all other letters in lower case).
local_port_to_forward:
The TCP port you want to forward in the Server. For example, if you want to
forward the web server, then it's "80". Notice that if you forward a
TCP service which listening on a port lower than 1024, then you should make
sure you have the privilege to bypass the security restriction.
comment_string:
Given a comment string. This is used for the Client side to tell apart from
different services. (The case is, you might run as many jttt instances using a
same user:pass pair). Here we use the string "my_web" as example.
In our example, the command
executing in Server would be like this:
% java -classpath .:jttt.jar JTTT Remote
80 "my_web"
Finally, you could run jttt in
the Client Machine now:
(1).Running jttt on Server Machine is
done by first switching to the directory
$INSTALL_DIR/bin
(2). Run
JTTT with the following 3 arguments:
% java -classpath .:jttt.jar JTTT
<forward_method> <local_port_to_forward> <comment_string>
Still, you CAN'T omit the "."
from the classpath argument.
forward_method:
The Port Forwarding methods in SSH, its value is either "Remote" or
"Local". In the Client machine you SHOULD use only "Local".
Notice that you should key-in exactly "Local" ("L" is in
upper case, with all other letters in lower case).
local_port_to_forward:
Give a port to launch the forwardign service in the Client Machine. You can
choose a free port in the Client machine (a port number which is not currently blocked
by any application running on Client Machine). Later the TCP service would be
forward to this port in the Client Machine.
comment_string:
Given a comment string. In the Client machine, you could input
"client" here.
In our example, the command
executing in Client would be like this:
% java -classpath .:jttt.jar
Local 8080 "client"
During the execution, you'll be prompt
asked to input a port number. You should follow the appearing message to key-in
a correct port number. For example, if you see this message as follows, then
you should key-in 9001 (and enter) only.
choose from:
"(9001:my_web), " -- please keyin only the ……
9001
(3).Now in the
Client machine, you could open a web browser to test the connection, by open
the URL "http://localhost:8080/"
5.
Known Bugs and Faults
Known Bugs:
(1).Once the jttt program dies in
Intermediate Machine, then it won't restart automatically. You should manually
restart all the machines.
(2).Any jttt program dying in Client,
Server, or Intermediate Machine will cause the whole mechanism to fail. You
should manually restart it.
Faults:
(1).jttt uses a
jtttt_port (in our example, it's the listening port 9000) in the Intermediate
Machine to communicate to Client or Server. All the data exchanges through port
9000 is not secured. This includes:
1. The jttt_uesrname and
jttt_password you set (e.g. jie:xxxxxx)
2. The Public Key file
transmit from Intermediate to Server or Client
But this communication only exists in the
first few second when you launch the JTTT program in Client or Server. The
later communication is all through SSH.
(2).Currently use
port 22 to transmit SSH data (SSH's default port), we don't support the way to
configure it to other port numbers.
(3).In the
Intermediate Machine, you could use $INSTALL_DIR/bin/check.sh to monitor the
connections. But you can only do this via open another terminal in Intermediate
to launch this shell script. You can't do this in the running JAVA terminal.
6.
The License Comments
jttt - Java TCP Tunneling Tool
http://sourceforge.net/projects/jttt/
Copyright (C) 2003 Jeffrey L.
Korn and Jie C. Huang. All Rights Reserved.
Written by: 2003 Jie C. Huang
<jiechau@users.sourceforge.net>
This program is free software;
you can redistribute it and/or
modify it under the terms of
the GNU General Public License
as published by the Free
Software Foundation; either version 2
of the License, or (at your
option) any later version.
This program is distributed in
the hope that it will be useful,
but WITHOUT ANY WARRANTY;
without even the implied warranty of
MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the
GNU General Public License for
more details.
You should have received a
copy of the GNU General Public License
along with this program; if
not, write to the Free Software
Foundation, Inc.,
The jttt Project is written in
JAVA and uses the J2SSH and Log4J libraries.
Therefore:
"This product includes software
developed by the
SSHTools open source projects
(http://sourceforge.net/projects/sshtools/).
"This product includes software
developed by the
Apache Software Foundation
(http://www.apache.org/)."
J2SSH is a package in project
"SSHTools - Java SSH Solutions" which (UNIX name: sshtools) is a SourceForge.net
project admin/develpoed by martianx and rpernavas.
(http://sourceforge.net/projects/sshtools/)
Log4J is a project of
"Apache Jakarta Project" by The Apache Software Foundation.
(http://jakarta.apache.org/log4j/docs/index.html)
In order to simplify the process of
executing the command, I packed every ".class" files (including the
jttt programs, jttt source codes, the J2SSH library, and the Log4J library)
into one jar file, the jttt.jar file. All I was trying to do was to simplify
the process of executing the command, and nothing else. You could use the
"jar" (in J2SDK Standard Edition) command to unpack this jar file.
After the extraction, all the J2SSH library is resided under the path: com\sshtools\j2ssh\
and all the Log4J library is resided under the path:
org\apache\commons\logging\.
7.
Contact Us
Developers:
jeffkorn
<jeffkorn@users.sourceforge.net>
jiechau
<jiechau@users.sourceforge.net>
Project Home Page:
http://sourceforge.net/projects/jttt/
jttt is an independent
research project admin/develpoed by jeffkorn and jiechau and is hosted on
SourceForge.net: http://sourceforge.net/