1 Introduction

1.1 Overview

The HTTP Tunneling Servlet is an add-on module that allows FileCatalyst Direct Clients to fall back to HTTP-based transfer when “auto” mode is used, or to always use HTTP in certain client scenarios.

Typically, FileCatalyst Direct Clients will fall back from Accelerated UDP to multi-stream FTP; the servlet adds one more layer, fallback to HTTP.

The benefit of HTTP-based transfer is that it is almost never blocked by corporate firewalls. As long as a user’s computer is able to connect to the internet, they should be able to transfer files over HTTP. Although HTTP-based transfers cannot be accelerated with the FileCatalyst Protocol, two two key benefits remain:

  • virtually guaranteed connectivity between client and server ends. End users will not need to have special configuration performed by their IT department in order to make a transfer
  • The reliability and scheduling benefits of the FileCatalyst product are still intact

The servlet will also translate HTTP requests to FTP for non-FileCatalyst FTP servers. If you have a legacy FTP server still in production, you may use the Servlet in conjunction with our client software (with a special Client Connect Key) in order to allow them to communicate with the legacy FTP server using the HTTP tunnel as well.

1.2 Choosing the Correct Hostname

Always keep in mind that the servlet is connecting to the Server on the user’s behalf. As far as the server knows, the Servlet is the “client”; therefore, consideration must be made to ensure direct communication without a Firewall or NAT getting in the way. After all, avoiding the Firewall and NAT are the primary reasons to use the Servlet in the first place.

To leverage the Servlet’s tunneling capabilities, it is usually deployed on the same network (or even the same physical machine) as the FileCatalyst or FTP server:

  • If they are on the same LAN, use the local IP of the server machine as hostname
  • If they are on the same physical machine, use “localhost” or 127.0.0.1 as hostname

2 Installation

2.1 Requirements

To install UnlimitedFTP Servlet, you will need:

  • An FTP server or FileCatalyst Server
  • A Servlet container. Any container can be used, for example Tomcat, JRun, Jetty, etc...
  • If you want https security, you need enable HTTPS. This is provided with most Servlet containers.
  • Your clients or customers need a FileCatalyst or Unlimi-Tech Java Applet, HotFolder or Command Line

2.2 Procedure

  1. Install a servlet container see the Tomcat installation instructions attached
  2. Save the file uftps.war to your Servlet Container's "webapps" directory
  3. Restart your servlet container

(For more specific instructions, consult your server's documentation about deploying web applications, or read the TomcatInstall documentation)

When deployed, you should be able to access a pre-configured UnlimitedFTP applet at: http://yourserver:port/uftps

You should be able to access the FTP Servlet directly at: http://yourserver:port/uftps/ftpservlet

The FTPServlet will also work with a standard <input type=file> tag. Please see formupload.html in the webapps/uftps directory for an example.

3 Config File

3.1 Config File Parameters

The config file will be generated automatically the first time you run the servlet, and is found in the webapps/uftps directory. The following is a description of each of the configurable parameters.

  • LICENSEKEY - your license key, it determines the number of simultanious service requests the servlet will accept.
  • LIVEMINS - how long (in minutes) an idle FTP connection will be allowed to sit before it is disconnected.
  • SO_TIMEOUT - how long (in milliseconds) a Socket will try to read for before giving up
  • SO_LINGER - how long (in milliseconds) a Socket will linger before giving up
  • MAXWAIT - how long (in milliseconds) a service request will wait before it is thrown out
  • MAXTX - is the maximum transfer rate (in KB/s) you want to allocate to each users downloads
  • MAXRX - the maximum transfer rate (in KB/s) you want to allocate to each users uploads
  • FILESIZELIMIT - the maximum file size (in bytes) that a user can upload or download
  • MULTISESSION - (true or false) tells whether a user can open multiple FTP sessions through the Servlet
  • LOGLOCATION - the path to the desired log location
  • FTPSERVLETPERMISSIONSCLASS - has to be a valid JAVA class, it must be in your classpath and it must implement FTPServletPermission. This class will give a fine-grained control of the functionality you wish to provide through the FTPServlet. (eg. read-only for certain directories)
  • TRANSFERMODE - Connection mode to the FTP server, it can me either FTP or FTPS (Implicit mode)

3.2 Sample config.txt

LIVEMINS=1
LICENSEKEY=
SO_TIMEOUT=30000
SO_LINGER=30000
MAXWAIT=120000
MAXTX=0
MAXRX=0
FILESIZELIMIT=0
MULTISESSION=false
LOGLOCATION=ftpservletlog.txt
FTPSERVLETPERMISSIONSCLASS=
TRANSFERMODE=FTP

4 Installation Instructions for Apache Tomcat

4.1 Overview

The following document provides instructions on how to perform a brand new install of Apache Tomcat on Windows, Linux or Solaris using Apache-Tomcat as the application server. The purpose of this document is to prepare a Tomcat servlet container for deployment of Unlimi-Tech and FileCatalyst Web applications, including FileCatalyst HTTP Tunneling Servlet.

4.2 Before You Start

Estimated installation time is about 30 minutes. Please have the following information ready before you begin installing:

  1. The target port number for Apache-Tomcat. The default HTTP port is 80, however this port is often already in use by another application. You will either have to disable such application or install Apache-Tomcat on a different port. The most commonly used alternative HTTP port is 8080.
  2. Root path (server URL) visible to the outside world.

    How will users connect to this service? Will they enter an IP address in their web browser or will you provide a domain name. (Example: servlet.mycompany.com)

    You will have to manually create this sub-domain.
  3. Configure your Firewall. The port of your choice forwarded on your firewall, to make applications running in Tomcat accessible by the outside world.
  4. Choose an Administrator password for Tomcat servlet container

4.3 Step One: Download JDK 6

The following link will take you to Sun’s website download section (size ~50MB): http://java.sun.com/javase/downloads/index.jsp

Make sure that you download the latest update for “JDK 6 ” for your respective platform. After the download is complete run the installer for Java SDK.

If you are installing 64-bit, be sure to download 64-bit installer

4.3.1 Linux and Solaris

In Linux and Solaris, the JAVA_HOME variable with the following command:

export JAVA_HOME=/pathto/j6sdk

This can be set in the user .profile which runs Tomcat (root or other), or in the environment variable file used by Tomcat ($CATALINA_HOME/bin/setenv.sh). See Tomcat documentation for more details.

4.3.2 64-bit Considerations

Once Java is installed, the environment variables need to be set up. This will ensure that if 32-bit Java is already installed, the Operating System will not continue to use 32-bit as the default:

  1. Open the the System control from the Control Panel.
  2. Select the Advanced System Settings and then click on the Environment Variables button.
  3. In the System Variables, add a new variable called JAVA_HOME. The value of this should be the location of the java files. Something like C:/program Files/Java/jdk1.6.0_17
  4. Then edit the System variable “Path” so that it includes a pointer to JAVA_HOME by adding ;%JAVA_HOME%\bin The semicolon is used to separate this from the path items that came before.

4.4 Step Two: Download Apache Tomcat 6

The following link will take you to Sun’s website download section (size ~90MB): http://tomcat.apache.org/download-60.cgi

Locate the latest Tomcat 6 Stable on the download menu

4.4.1 Windows Procedure

Download the Windows Installer. For easier administration later it is strongly recommended that you install Tomcat in top-level directory of your root: example:

c:\tomcat

Note: The install directory for Tomcat is also referred to as the CATALINA_HOME.

During the install you can change the Tomcat HTTP port to 80 (default HTTP, as opposed to the Tomcat default of 8080).

You are also presented with a Tomcat administrator login. This is to administer Tomcat servlet container. Provide a suitable password for this.

64-bit Windows: Download the 64bit Tomcat Service Wrappers from http://filecatalyst.com/support/download/tomcat64bitWrappers.zip and copy them into the tomcat bin directory, overwriting the existing files.

Verify Service: Once Tomcat is installed, you can verify it as a service Start → Settings → Control Panel → Administrative Tools → Services

4.4.2 Linux & Solaris Procedure

Download the tar.gz file and then use the following commands to expand the archive:

gunzip filename.tar.gz
tar -xvf filename.tar

It is recommended that the application be unzipped in a standard UNIX directory (/opt). The Tomcat installation directory (CATALINA_HOME) would therefore be “/opt/apache-tomcat-6.0.14/”.

Tomcat listener port number can be changed by modifying the configuration file, found at CATALINA_HOME/conf/server.xml

<Connector className="org.apache.coyote.tomcat4.CoyoteConnector"
port="80"
enableLookups="true" redirectPort="8443"
acceptCount="100" connectionTimeout="20000"
useURIValidationHack="false" disableUploadTimeout="true" /$gt;

To manually start Tomcat on Unix, execute CATALINA_HOME/bin/startup.sh

To have Tomcat automatically startup when the UNIX server boots up, it is recommended that the operating system be configured appropriately to include Tomcat startup as part of the boot process. This may vary based on operating system environment:

  • RC scripts (standard UNIX)
  • Solaris SMF (Solaris 10+)
  • YaST runlevels (Linux).

4.5 Step Three: Verify Installation

To verify if Tomcat is started, open up a browser on the server and go to the main Tomcat page:

http://localhost or http://<serverIP>:<serverPort>

The following splash page should be visible if Tomcat has been installed and started:

At this point your installation of Tomcat is complete, you will now be able to deploy any web applications in WAR format by just placing them in {tomcat_home}/webapps.

4.6 Step Four: Install SSL (optional)

You can find our Tomcat SSL tutorial at the following link:

http://www.utechsoft.com/support/resources/tomcat-ssl-csr.html

4.7 Additional Considerations

Here are some other considerations with respect to your Tomcat installation:

Tomcat ships with several default web applications, found in the {tomcat_home}/webapps directory. These defaults depend on the version of Tomcat and which installer you use.

  • The ROOT application contains the server's main page. Any file that you add under ${tomcat_home}/webapps/ROOT will be served.
  • The admin and manager applications are used for remote management. To use these applications, you must add users with roles admin and manager, respectively. The applications are then accessible from the main page, and can be used to add further users, start and stop webapps, etc. You should restrict the IP addresses that are allowed to run these applications by editing the files admin.xml and manager.xml in the ${tomcat_home}/conf/ directory.
  • The servlets-examples and jsp-examples should probably be removed from a production server, to minimize security exposure. You can do this from the manager application or by deleting those directories from ${tomcat_home}/webapps.
  • The tomcat-docs, balancer and webdav applications are probably harmless, but can also be removed if you want.

5 Support

5.1 Support Portal

Our support web site is available 24/7 is a great place to get answers: http://support.filecatalyst.com Be sure to search the knowledge base as well as visit the forums (one of the buttons in the header).

5.2 Phone, email and chat support

Phone and live chat are available 9am - 5pm EST.
  • Trouble Ticket : From the support portal, register then "Submit a Ticket." This is your best option for a highly visible support request.
  • Email : info@utechsoft.com
  • Live chat : http://support.filecatalyst.com (click Live Support button)
  • Phone: (613)667-2439
  • Toll-Free: (877)327-9387
  • Knowledge Base: Click Here