\input texinfo @c -*-texinfo-*-

@c %**start of header
@setfilename freehost.info
@settitle FreeHost 3270 version 0.1
@setchapternewpage odd
@c %**end of header

@ifinfo
Copyright (C) 1998, 2001 Art Gillespie

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no 
Back-Cover Texts.  A copy of the license is included in the section entitled 
"GNU Free Documentation License".

@end ifinfo

@titlepage
@title FreeHost 3270 User's Manual
@subtitle version 0.1
@author Art Gillespie
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1998, 2001, Art Gillespie

Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
or any later version published by the Free Software Foundation;
with no Invariant Sections, with no Front-Cover Texts, and with no 
Back-Cover Texts.  A copy of the license is included in the Licenses 
appendix.

@end titlepage


@ifnottex

@node Top, Overview, (dir), (dir)
@comment node-name, next, previous, up
@top FreeHost 3270

This document describes the FreeHost3270 system.  It applies to
version 0.1.  For the latest version of FreeHost3270 and this
documentation, please visit http://freehost3270.sourceforge.net
@end ifnottex

@menu
* Overview::                    
* Installation::                
* Licenses::                    

Licenses



Licenses


@end menu

@node Overview, Installation, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Overview

@node What is FreeHost 3270?, Architecture, Overview, Overview
@comment  node-name,  next,  previous,  up
@section What is FreeHost 3270?
FreeHost 3270 is a set of Java Servlets and a Java Applet that enable sites to deploy TN3270 applications to multiple clients via the Web (or on an intranet or VPN).  With FreeHost 3270, a single servlet container + web server can deliver TN3270 clients as well as proxied connectivity to a virtually limitless number of users through their browser.   The FreeHost 3270 client applet was written to be compatible with the earliest Java implementations and does not require that users download the Java 1.2 plugin for VM compatability.
@node Architecture,  , What is FreeHost 3270?, Overview
@comment  node-name,  next,  previous,  up
@section Architecture

@section Helping out
FreeHost 3270 needs all the help it can get.  Anyone interested in testing, submitting patches, writing documentation, suggesting new features, and so on is welcome to do so at @url{http://sourceforge.net/projects/freehost3270}.
@section Reporting bugs
If you think you've found a bug in FreeHost 3270, you probably have... please don't keep it to yourself.  Bug reports are an invaluable part of open-source participation.  Visit our bug-tracking system at @url{http://sourceforge.net/projects/freehost3270/}.  Of course, you're always welcome to patch against the latest sources @ref{Where to get FreeHost 3270} and send patches to @email{agillesp@@i-no.com}. 


@node Installation, Licenses, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter Installation

@node Where to get FreeHost 3270, Installing FreeHost 3270, Installation, Installation
@comment  node-name,  next,  previous,  up
@section Where to get FreeHost 3270
You can always download the latest release of FreeHost 3270 at @url{http://www.sourceforge.net/projects/freehost3270/}

For those who want/need access to the latest source updates, anonymous CVS access is available.  
The following commands should do the trick.
@example
cvs -d:pserver:anonymous@cvs.freehost3270.sourceforge.net:/cvsroot/freehost3270 login
@end example
When CVS prompts you for a password, press @key{ENTER}, then
@example
cvs -z3 -d:pserver:anonymous@cvs.freehost3270.sourceforge.net:/cvsroot/freehost3270 co freehost3270
@end example
Eventually, I'll put a separate section on building from source in this here documentation. In the meantime, there's a standard ant @file{build.xml} file in the top-level project directory.  Make sure you have ant installed @url{http://jakarta.apache.org/ant/}, cd to @file{my-development-dir/freehost3270} type 'ant', and you should be all set.


@node Installing FreeHost 3270, Configuration, Where to get FreeHost 3270, Installation
@comment  node-name,  next,  previous,  up
@section Installing FreeHost 3270

Installing FreeHost 3270 is so easy, it hurts to think about it.  Simply drop the @file{freehost-version.war} file from the distribution in your Servlet Container's @file{./webapps/} directory.

If your servlet container requires you to restart in order to deploy a new war, do so.

The configuration defaults in the distrubition are sensible enough that you should be able to test your FreeHost 3270 installation now.  Open your favorite browser and point it at whatever url makes sense in your environment:

@url{http://localhost:8080/freehost3270/freehost}

The FreeHost TN3270 Emulator should pop up and connect to Harvard's HOLLIS information system.  (Assuming your host is connected to the web and is able to get out on port 23.)

@node Configuration, Troubleshooting, Installing FreeHost 3270, Installation
@comment  node-name,  next,  previous,  up
@section Configuring FreeHost 3270
FreeHost 3270 is configured through the @file{WEB-INF/freehost.properties} file.  What follows
is a short description of each entry@footnote{In release 0.2, the configuration will move to an xml-based configuration file.};.


@deffn Config sessionServerHost
The SessionServer host that tn3270 clients will connect back to.  Note that in the case of the Java TN3270 emulator applet, this hostname must match the hostname that was used to deliver the applet in order to satisfy Java Applet sandbox security conditions.
@end deffn

@deffn Config sessionServerPort
The port the SessionServer will listen on.  Note that in the next release (0.2), this will no longer be necessary as all communication will take place through HTTP Tunneling.  In the meantime, hosts and clients must ensure that this port is open on their networks for listening and connecting, respectively.
@end deffn

@deffn Config hostList
A pipe-delimited list of hosts.  These are the hosts that clients will see in their 'Connect' menu.  If the @var{manualEntry} configuration variable is set to 'false', these are the @emph{only} hosts the client will be able to connect to.  Each host entry has the format:
@example
<hostname>|<port>|<friendlyname>
@end example
where @var{friendlyname} is the name that clients will see in their 'Connect' menu.
@end deffn

@deffn Config manualEntry
If set to true, allows users to enter their own hosts as well as select from the hosts specified in @var{hostList}
@end deffn

@deffn Config helpabout
String that will appear in the TN3270 Java Applet's 'help->about' dialog.  Administrators may want to put support contact information here for users.
@end deffn

@deffn Filtering filterList
Comma-separated list of ip filters.  Wildcards are allowed
@example
127.0.*  The entire class C subnet.
127.0.0.* The entire class D subnet.
@end example
The semantic meaning of these filters is modified by the @var{filterMode} configuation directive.
@end deffn

@deffn Filtering filterMode
Specifies behavior of filters in filterList.
@itemize
@item 0 = none
@item 1 = allow from (all hosts specified in filter list)
@item 2 = disallow from (all hosts @emph{except} specified in filter list)
@end itemize
@end deffn

@deffn Admin adminEmail
The e-mail address of the FreeHost 3270 administrator.  The FreeHost SessionServer will send e-mail to this address according to the email* options below.
@end deffn

@deffn Admin smtpserver
The SMTP server to use for sending administrative e-mails
@end deffn

@deffn Admin emailNotifyXSessionsAreActive
If > 0, send an email when the SessionServer has this many sessions concurrently active.
@end deffn

@deffn Admin emailNotifyHostNotResponding
If true, send an e-mail to @var{adminEmail} if connections to the TN3270 gateway host should fail.
@end deffn

@node Troubleshooting,  , Configuration, Installation
@comment  node-name,  next,  previous,  up
@section Troubleshooting
If you're having any problems getting FreeHost 3270 to work the way you expect it to, be sure to check the FreeHost 3270 home page at @url{http://freehost3270.sourceforge.net} and the project page at SourceForge: @url{http://sourceforge.net/projects/freehost3270}.  Here you'll find mailing list archives and how to subscribe to the user's mailing list, where you can have your question answered by other FreeHost 3270 users and developers.

In the meantime, here are couple of common problems and their common solutions:

@itemize
@item @emph{The Java TN3270 applet never shows me the TN3270 connection I'm expecting.}  In order:
@enumerate
@item Check to see that the host that the SessionServer servlet is running on can connect to the TN3270 gateway host.
@item Check to ensure that the sessionServerHost configuration variable in @file{freehost.properties} matches the host you typed in your browser...  The Java Applet Security Manager will only let applets connect to the @emph{same host from which they were served}, so if you have @var{localhost} in your @file{freehost.properties} and you typed in @url{http://www.myserver.org/}, the applet won't be able to connect to the SessionServer servlet.
@item If the client is behind a firewall, be sure they can connect out on the port specified by @var{sessionServerPort} in @file{freehost.properties}.  Naturally, getting a corporate network lackey to open a port is difficult at best (as it should be).  I've found that you can set the SessionServer port to 443 (the HTTPS port) and succeed in most firewall environments.  Good news, though; in version 0.2, FreeHost 3270 will support HTTP Tunneling (connect back to the SessionServer on port 80, using HTTP headers and HTTP keep-alive), so this won't be an issue for much longer.
@end enumerate
@item @emph{I get a burning sensation when I urinate.}  Go see a doctor immediately.  Be prepared to make some embarrassing phone calls.
@end itemize

@node Licenses,  , Installation, Top
@comment node-name, next, previous, up
@appendix Licenses

@node Library Copying, GNU Free Documentation License, Licenses, Licenses
@menu
@end menu

@appendixsec GNU LESSER GENERAL PUBLIC LICENSE

@cindex LGPL, Lesser General Public License
@center Version 2.1, February 1999

@display
Copyright @copyright{} 1991, 1999 Free Software Foundation, Inc.
59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

[This is the first released version of the Lesser GPL.  It also counts
as the successor of the GNU Library Public License, version 2, hence the
version number 2.1.]
@end display

@appendixsubsec Preamble

  The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
Licenses are intended to guarantee your freedom to share and change
free software---to make sure the software is free for all its users.

  This license, the Lesser General Public License, applies to some
specially designated software---typically libraries---of the Free
Software Foundation and other authors who decide to use it.  You can use
it too, but we suggest you first think carefully about whether this
license or the ordinary General Public License is the better strategy to
use in any particular case, based on the explanations below.

  When we speak of free software, we are referring to freedom of use,
not price.  Our General Public Licenses are designed to make sure that
you have the freedom to distribute copies of free software (and charge
for this service if you wish); that you receive source code or can get
it if you want it; that you can change the software and use pieces of it
in new free programs; and that you are informed that you can do these
things.

  To protect your rights, we need to make restrictions that forbid
distributors to deny you these rights or to ask you to surrender these
rights.  These restrictions translate to certain responsibilities for
you if you distribute copies of the library or if you modify it.

  For example, if you distribute copies of the library, whether gratis
or for a fee, you must give the recipients all the rights that we gave
you.  You must make sure that they, too, receive or can get the source
code.  If you link other code with the library, you must provide
complete object files to the recipients, so that they can relink them
with the library after making changes to the library and recompiling
it.  And you must show them these terms so they know their rights.

  We protect your rights with a two-step method: (1) we copyright the
library, and (2) we offer you this license, which gives you legal
permission to copy, distribute and/or modify the library.

  To protect each distributor, we want to make it very clear that
there is no warranty for the free library.  Also, if the library is
modified by someone else and passed on, the recipients should know
that what they have is not the original version, so that the original
author's reputation will not be affected by problems that might be
introduced by others.

  Finally, software patents pose a constant threat to the existence of
any free program.  We wish to make sure that a company cannot
effectively restrict the users of a free program by obtaining a
restrictive license from a patent holder.  Therefore, we insist that
any patent license obtained for a version of the library must be
consistent with the full freedom of use specified in this license.

  Most GNU software, including some libraries, is covered by the
ordinary GNU General Public License.  This license, the GNU Lesser
General Public License, applies to certain designated libraries, and
is quite different from the ordinary General Public License.  We use
this license for certain libraries in order to permit linking those
libraries into non-free programs.

  When a program is linked with a library, whether statically or using
a shared library, the combination of the two is legally speaking a
combined work, a derivative of the original library.  The ordinary
General Public License therefore permits such linking only if the
entire combination fits its criteria of freedom.  The Lesser General
Public License permits more lax criteria for linking other code with
the library.

  We call this license the @dfn{Lesser} General Public License because it
does @emph{Less} to protect the user's freedom than the ordinary General
Public License.  It also provides other free software developers Less
of an advantage over competing non-free programs.  These disadvantages
are the reason we use the ordinary General Public License for many