User
Document of jttt - "Java TCP Tunneling Tool" version 2.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 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/ in the Client Machine to open
the remote web pages.
The “jttt 2.0” uses a web interface (web
server in Intermediate Machine) with Java Applets running in client ends (both
Client Machine and Server Machine in the picture above) to achieve the SSH Port
Forwarding functionality.
Client JAVA Applet to Achieve jttt tunnel port:8080 Intermediate Web Server port:9001 Server JAVA Applet to Achieve jttt tunnel port:80 jttt tunnel
jttt tunnel (Client:8080
=> Intermediate:9001)
(Intermediate:9001
=> Server:80)
The Intermediate Machine is running a
SSHd to waiting for connection and achieve the Port Forwarding function for
connections. It also has a web server to let clients to download the Applet for
executing the Port Forwarding request. Authentication of Client and Server
Machines is done through a password file in Intermediate Machine.
The Client Machine and Server Machine sides
only need to have web browser (e.g. Microsoft IE) with Java Runtime plug-in
(version 1.4 or above). The Client and Server achieve the SSH connection to
Intermediate Machine and the Port Forwarding functionality via Java Applet.
2. System Requirement
The requirement for Client,
Server, and Intermediate Machine are:
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).Having Apache Ant
installed. (http://ant.apache.org)
(6).Having a Web Server with
CGI scripts ability (Perl or Korn Shell 93 Scripts).
(7).You need a
"user account" in the Intermediate Machine. (No need to have root or
administrator account)
For the Client Machine:
(1).Operating System: OS
Independent
(2).Web Browser having Java
Plug-in version 1.4 or above.
For the Server Machine:
(1).Operating System: OS
Independent
(2).Web Browser having Java
Plug-in version 1.4 or above.
Make sure your environments meet all the
requirements above, and then you could continue the installation procedure.
3. How to Install
To
install jttt_2.0 in the Intermediate Machine, download jttt_2.0 package and unpack
it to a working directory. You don’t need the root privilege to install jttt
2.0 (and better not). You only need a user account in the Intermediate Machine
(in this example, we use a user account: jch280
in this machine: sparky.cs.nyu.edu).
We use the Apache Ant (the used version is Ant 1.5.3) to build and install jttt
2.0 in the Intermediate Machine. (The Client and Server don’t need to install
anything since they use a Java Applet to execute the program).
If you
don’t have Apache Ant installed on your Intermediate Machine, you could go to http://ant.apache.org
to download and install Apache Ant.
The
only thing you need to do is unpack the jttt package, and edit the build.properties file. Everything is
configured in the properties file. After you finish editing the properties file
(we’ll talk about this later in this chapter – “About the build.properties:
“), you
could simply use the following command to install jttt 2.0 in your Intermediate
Machine:
Suppose you download jttt_2.0.tar.gz to a
working directory “/home/jch280/_x/jttt_2.0”
% cd
/home/jch280/_x; gzip –d jttt_2.0.tar.gz; tar xf jttt_2.0.tar
% cd
/home/jch280/_x/jttt_2.0
% vi build.properties
(Don’t forget to edit this file BEFORE
you install)
% ant
install
Other
than the ‘install’ task, we also provide 2 more tasks for un-install the
software and clean the complied files. They are ‘deinstall’ and ‘clean’. This
is useful when you change any setting in the build.properties file, you need to re-install everything:
% cd
/home/jch280/_x/jttt_2.0
% ant
deinstall
% ant
clean
Notice
that the Apache Ant works following the way of the build.xml, which is
following the build.properties. The install/deinstall/clean of jttt 2.0 invoke
some system read/write actions based on the build.properties file. So please
make sure you well configure the build.properties file.
About the build.properties:
Now we
talk about the build.properties file
into a detail level. This file is located right in the directory where you
unpack the jttt_2.0.tar.gz package file. You SHOLD well configure this file to
match your system setting before you run Apache Ant to invoke installing jttt
2.0. Here is the explanation of every variable. You could use any editor (e.g.
vi) to edit this build.properties file.
sINSTALL_DIR
The
prefix installation directory, where you will install the jttt 2.0, for
example:
sINSTALL_DIR=/home/jch280/jttt_2.0
sSSHHostname
The
Hostname or IP Address of you Intermediate Machine, where there is a SSH Server
listening. For example:
sSSHHostname=sparky.cs.nyu.edu
sSSHServerType
This is
for setting up the type of your SSH server in Intermediate Machine. We use an
integer value to indicate what kind of SSH server it is. “1” is SECSH (from
ssh.com), and “2” is OpenSSH (from openssh.org). For example:
sSSHServerType=2
sSSHPort
The SSH
port to connect to. By default, the SSH port for most SSH server is in Port 22.
For example:
sSSHPort=22
sAccount
The user
account on the Intermediate Machine. You need a User Account in the
Intermediate Machine for doing the SSH authentication. For example:
sAccount=jch280
sSSHKEYconfigFile
The
location of authorization file for SSH connection. In most cases, if you use
SECSH, the authorization file is in $HOME/.ssh/authorization and if you use
OpenSSH, the authorization file is in $HOME/.ssh/authorized_keys
for
example:
sSSHKEYconfigFile=/home/jch280/.ssh/authorized_keys
sInterMediaServerPort
The
jttt 2.0 uses an additional TCP socket connection to perform our function. You
should choose a port which is currently unused on Intermediate Machine and is
accessible by your account in Intermediate Machine (in the example, the
‘jch280’ user account). For example:
sInterMediaServerPort=9000
sJTTTStartPort
When
jttt 2.0 perform the Port Forwarding functionality, it will allocate the ports
for Remote or Local Forwarding as needed. We need 100 free ports prepared for
further connection/request. For example, if you configure this value to:
sJTTTStartPort=9001
Then it
will reserve the ports from 9001 to 9100 for further usage. Make sure that
these 100 ports in Intermediate Machine are not allocated by any other program and
is accessible by your account.
sJavaHome
Where
you install your Java 2 SDK, for example:
sJavaHome=/opt/java
sShellExec
The
execution file for execute your Shell script. When running the jttt 2.0 we need
to run some Shell scripts (those .sh files under the sINSTALL_DIR/bin directory). Your choice could be sh, bash, or ksh,
For example:
sShellExec=/home/unixtool/bin/ksh
sWebHostname
This is
the web Hostname or IP address on which your web server is installed. Simply it
is the Web Server String in URL for the web browsers to connect to. Normally
this value is the same as the Hostname or IP Address of your Intermediate
Machine (the sSSHHostname variable
above). Only under some circumstances, you web server is reside in another
Machine (but it must share the File System with the sSSHHostname Machine). Our test Intermediate Machine is this case.
The SSH Server is sparky.cs.nyu.edu, but the web server is cs1.cs.nyu.edu (and
they two share the whole file system). In this case, the setting would be:
sWebHostname=cs1.cs.nyu.edu
Because
cs1.cs.nyu.edu is the real string which will appear in the URL for the browser
to connect to.
sHtmlDocPhysicalPath
sHtmlDocPath
On the
web server (in Intermediate Machine), the sHtmlDocPhysicalPath
is the physical path where we will put all the HTML files and the Applet Jar
file, and the sHtmlDocPath is the
path part of the URL which maps to the physical path. For example:
sHtmlDocPhysicalPath=/home/jch280/public_html/jttt_2.0
sHtmlDocPath=/~jch280/jttt_2.0
sCGIPhysicalPath
sCGIPath
On the
web server (in Intermediate Machine), the sCGIPhysicalPath
is the physical path where we will put all the CGI scripts, and the sCGIPath is the path part of the URL
which maps to the physical path. For example:
sCGIPhysicalPath=/home/jch280/public_html/cgi-bin/jttt_2.0
sCGIPath=/~jch280/cgi-bin/jttt_2.0
sCookieDomain
On the
CGI scripts we used, we use the Cookie to control the access of web pages. This
value (Hostname or IP address or Domain name) is used for CGI script to write the
cookies. Normally it will be the same as the sWebHostname value above. It is also OK that you only provide the
domain name (not including the host) as your Cookie Domain. For example:
sCookieDomain=cs1.cs.nyu.edu
or
sCookieDomain=cs.nyu.edu
sCookiePath
This value
is used for the CGI scripts to write the cookie. Normally we only use a “/” as
the Cookie path (which means this cookie could be access by other CGI scripts
located in other web paths). For example:
sCookiePath=/
sCGILanguage
sCGIExtension
sCGIExec
These 3
variables indicate how you like your CGI scripts to work. Current we provide 2 two
choices for CGI scripts: use Korn Shell 93 or Perl. If you choose Korn Shell 93
then the value of sCGILanguage is
restrictedly to “KornShell”, and if you choose Perl as your CGI script, the
value of sCGILanguage is restrictedly
to “Perl”. The variable sCGIExtension
is the CGI script extension that your web server can accept, e.g. “sh” or “pl”.
The variable sCGIExec indicates the
location of the execution file to execute the CGI scripts, this value should
match the sCGILanguage you chose. For
example, if you use Korn Shell 93, then the settings would be like:
sCGILanguage=KornShell
sCGIExtension=sh
sCGIExec=/home/unixtool/bin/ksh
or if
you use Perl as your Shell Scripts, the settings would be lie:
sCGILanguage=PERL
sCGIExtension=pl
sCGIExec=/usr/local/bin/perl
sUsername
sPassword
These
two values are used when you run jttt 2.0 in Client or Server Machine. In the
case if you don’t want to use a Java Applet. It is not the case of jttt 2.0
now, so you could ignore this 2 setting, just leave it. For example:
sUsername=jie
sPassword=xxxxxx
4. How to Run
Run jttt 2.0 in Intermediate Machine, and
you can achieve the tunneling function. The Server and Client Machines only
need to have Web browsers with JAVA plug-in (version 1.4 or above) to execute
the Java Applet. Here we use an example with configurations to explain how to
run jttt.
Firstly, you should run jttt 2.0
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_2.0 is installed in
/home/jch280/jttt_2.0 (your sINSTALL_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 sINSTALL_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 2.0 system, the format
is: every single line contains an username:password pair. no comments and 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 these two jttt user:pass
pairs.
(3).Go to sINSTALL_DIR/bin directory (in this example: /home/jch280/jttt/bin).
Run the shell script “run.sh”
% ./run.sh
(4).When the first
time you run it, it will generate the key files. This might take some time.
(5).When you see
the running message stops, it means that the Intermediate is set up and ready.
(6).Later after
you run the Applets in Server and Client Machines, you can run the shell script
sINSTALL_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.
Second, you could run jttt in the Server
Machine, via Web browser:
Here we use the VNC Software as the
example. The Server Machine is the one which is running the VNC Server (listen
on local port 5900). The VNC Software we used is the TightVNC (http://www.TightVNC.com).
Here we briefly explain how to set up the VNC Server to listen on port 5900
(display number: 0). You could do this via the setting the VNC Server
properties after you install it:
Assign a “VNC password”, this
is used to protect your desktop from any others’ access. Then you should
configure the ports number to 5900. And the last, you should also configure it
to “Allow loopback connection”. This is done in the “Advanced .. “ options:
When the VNC software is set
up, you could use this VNC software to test your setting or the whole jttt 2.0
mechanism. First in the Server Machine, you should achieve the “Remote
Forwarding”:
(1).Open a Web
Browser, e.g. Microsoft IE, point to the URL:
http://sWebHostname sHtmlDocPath/index.html
where sWebHostname
and sHtmlDocPath is the values, of
your web hostname and html document path setup for jttt 2.0 (in the
build.properties file). When installing jttt, you have set up these values in
the build.properties file. For example, if your sWebHostname is “cs1.cs.nyu.edu” and sHtmlDocPath is “~jch280/jttt_2.0”, then you should have your
browser point to this URL:
http://cs1.cs.nyu.edu/jttt_2.0/index.html
(2).Use the jttt
username:password pair (mentioned in the above) to login, e.g. in the above
example set up. The username:password is jie:xxxxxx
(3).After you
successfully logon, you should setup a “Remote Forwarding” for this Server
Machine. The “
(4).After you click
the “Remote Forwarding” button, it will launch a pup-up window to execute the
Applet code (so don’t block the pup-up function in your browser). Because this
Applet program is in a “signed Jar file”, you should grand the access before
you can execute it.
(5).If everything
goes smoothly, you will finally see the Applet Window having the string
“Connection: OK” and counting the seconds. This means that the Remote
Forwarding function is successfully built:
Finally, you could run jttt 2.0
in the Client Machine, via Web Browser:
(1).The same, open
an web browser, point to the URL as mentioned in the Server part above. And you
still use the same username:password pair:
(2).Since this is
a Client Machine, you could choose from the list on the “Client:” part in the
web page. In this case, the Server Machine port 5900 has been successfully
forwarded to the Intermediate Machine (port 9001). You could choose from the
list, use the comment string to tell. Then you should assign a “Local Port” in the current Client
Machine to forward its data to the Intermediate Machine port 9001 (and to the
Server Machine port 5900). Here we use the port 5903 (which means the VNC display number 3):
(3).By click the
“Local Forwarding”, it will pop-up another browser to execute the Applet
program. The same, it will require you to grand the access to the signed JAR
file (this step is exactly like those when setting up the Server Machine).
After all these are done, you will see the Applet window appears the string
“Connection: OK” and start to count the seconds. This means the local
forwarding in the Client Machine is successfully built:
(4).Now we need to
test if the tunnelings is successfully built between the Client Machine and the
Server Machine. You could launch a VNC Client program (here we use the Linux
pre-installed Remote Desktop Program), try to connect to the display number 3
(because we set up the local forwarding in port 5903) in “localhost”:
(5).The VNC Client Program will ask you
for the password to access the VNC Server, key-in what you just set up in the
VNC Server (in the Server Machine):
(6).If the tunnels is built correctly,
you will see the remote desktop, which is the desktop in the Server Machine.
5. Known Bugs and Faults
Actually this is not a bug but something
you should be aware of. The jttt 2.0 uses a jttt port (the “sInterMediaServerPort” setting in build.properties file) to provide the
private key content to a Server or Client Machine. This feature is inherited
from jttt 1.0. But currently the socket connection through “sInterMediaServerPort” would be only from
the localhost. If you are worried about the security issue, you could limit the
connection to “only from localhost”. And the methods to do this would be via a
OS setup, or a network packages filter software.
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, and the installation of jttt needs
the Apache Ant.
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)
Apache Ant is a Java-based
build tool by The Apache Software Foundation.
(http://ant.apache.org/)
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