==============================================================================
README for http-in 0.3                                              2000-08-12
==============================================================================

Copyright 2000 by Eberhard Mattes <em-gw@windhager.de>
Donated to the public domain.  No warranty.


Introduction
============

NOTE: http-in is work in progress.  This is a pre-release.  Features,
usage, and configuration will change.

http-in forwards HTTP requests from the outside (i.e., the Internet)
to a web server inside (i.e., on the "secured" side of the firewall).

http-in does not yet attempt to protect the HTTP server from
data-driven attacks.


Installation
============

1. After installing the TIS Firewall Toolkit, unpack http-in.tar.gz
   or em-gw.tar.gz into the main directory of the TIS Firewall Toolkit:

        cd /sources/fwtk
        gunzip </dist/em-gw.tar.gz | tar xf -

2. If your `make' tool requires `.include' instead of `include',
   replace `include' with `.include' in http-in/Makefile and
   libem/Makefile.  (This can also be done by running `fixmake' of the
   TIS Firewall Toolkit.)

3. Compile the libraries and the program:

        cd libem
        make
        cd ../http-in
        make

4. Copy http-in to the target directory:

        cp http-in /usr/local/etc

   (see the definition of DEST in Makefile.config for the target
   directory).

5. Configure http-in by editing netperm-table, see below.

6. Start http-in (don't forget to arrange for http-in being started
   automatically when the system comes up), see below.


Compilation problems
====================

If your system does not have vsnprintf(), add

  #define DONT_HAVE_VSNPRINTF

to firewall.h and retry.  http-in requires an ANSI/ISO C compiler and
a POSIX.1 operating system.  If you don't have these, you have to port
http-in to your system yourself.


Configuration
=============

http-in is -- like the TIS FWTK programs -- configured by rules in
netperm-table.  It reads all rules using the http-in (or the name
specified on the command line) and * keywords.

Note that "netperm-table" must be readable by the user ID and group ID
configured with the "userid" and "groupid" attributes; otherwise
http-in will fail after receiving SIGHUP.

http-in understands the following attributes:

  add-header <NAME>

     Send a request header line containing <NAME> as header field name
     and the client's IP address as value to the server (e.g., for
     logging or authentication).  Example:

        http-in: add-header X-Client

     will cause http-in to send the line

        X-Client: 123.123.123.123

     to the HTTP server (where 123.123.123.123 is the IP address of
     the client connecting to http-in).

  client-timeout <TIMEOUT>

     Define the number of seconds http-in is idle (without network
     activity) before disconnecting from the client.  The default
     value is 120 seconds.  Only the first "client-timeout" line is
     read.  Currently, if server-timeout is greater than
     client-timeout, server-timeout will override client-timeout after
     processing the request header.

     Example:

          http-in: client-timeout 300

  groupid <GROUP>

     Run with group ID <GROUP>.

     Example:
          http-in: groupid nogroup

  logfile <FILENAME>

     Append one line for each request to the file <FILENAME>.  Common
     log file format is used for that file.  You can tell http-in to
     reopen the log file (without reconfiguration) by sending SIGUSR1.
     This can be used for rotating log files.  Note, however, that
     http-in will continue writing to the previous log file for any
     open connections.

     Initially, the log file is opened before changing the user and
     group IDs.  The log file should be writable by the user ID and
     group ID configured with the "userid" and "groupid" attributes;
     otherwise http-in will fail after receiving SIGHUP or SIGUSR1.
     The simplest solution is to not use "userid" and "groupid".

     Example:
          http-in: logfile /var/log/http-in.log

  overall-timeout <TIMEOUT>

     Limit the overall duration of a connection to <TIMEOUT> seconds.
     By default, there's no limit.  Only the first "overall-timeout"
     line is read.  After <TIMEOUT> seconds, the connection is
     terminated without sending a message sent to the client.  Data in
     transfer will be truncated.

     Example:

          http-in: overall-timeout 600

  server <HOST>

     Forward to the HTTP server on <HOST>.  <HOST> can be an IP address
     or a hostname.  Port 80 will be used.  This attribute is
     mandatory.

  server-timeout <TIMEOUT>

     Define the number of seconds http-in is idle (without network
     activity) before disconnecting from the server.  The default
     value is 120 seconds.  Only the first "server-timeout" line is
     read.

     Example:

          http-in: server-timeout 300

  userid <USER>

     Run with user ID <USER>.

     Example:
          http-in: userid nouser


Running http-in
================

http-in can be run either from inetd:

        http-in [ -name <KEY> ]

or as daemon:

        http-in -daemon <PORT> [ -name <KEY> ]
        http-in -fastdaemon [<HOST>:]<PORT> [-pf <PIDFILE>] [ -name <KEY> ]

If <KEY> is specified, http-in will read configuration rules using
<KEY> instead of "http-in".  This can be used for having different
configurations of http-in on different ports (or IP addresses).

<PORT> is the port number.  When started as normal daemon (with the
-daemon option), http-in will reread the configuration rules for each
connection.

When started as fast daemon (with the -fastdaemon option), http-in
will read the configuration once, when started, to save time.  Any
changes made to "netperm-table" after starting http-in as fast daemon
will be ignored.  However, you can force http-in to reread the
configuration by sending it SIGHUP.  Note however, that http-in leaks
some memory when it receives SIGHUP.  http-in may terminate if the
configuration contains errors while http-in rereads the configuration.

If the -pf option is used, the process ID (to which SIGHUP should be
sent for letting http-in reread "netperm-table") will be written to
the file <PIDFILE>.  That file is opened before http-in has changed
its user ID and group ID to the values configured in "netperm-table".


Version 0.1 2000-05-27
----------------------

- First pre-release

Version 0.2 2000-05-30
----------------------

- Send only one CRLF after "Connection: close"

Version 0.3 2000-08-12
----------------------

- Don't terminate copying until all data has been sent to the client

- Use common log file format

==============================================================================
                                THE END
==============================================================================
