Various changes. Add configuration grammar to help text. Change to

[fwd] / fw.1

.\" -*-nroff-*-
.ie t .ds o \(bu
.el .ds o o
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
.TH fw 1 "1 July 1999" fw
.SH NAME
fw \- port forwarder
.SH SYNOPSIS
.B fw
.RB [ \-db ]
.RB [ \-f
.IR file ]
.IR config-stmt ...
.SH DESCRIPTION
The
.B fw
program is a simple port forwarder.  It supports a number of features
the author hasn't found in similar programs:
.TP
.I "Connection logging"
Each connection attempt to the forwarder is logged, giving the time of
the connection, the DNS-resolved hostname (if available), and the user
name resulting from an RFC931 lookup.  These lookups are done
asynchronously to the main forwarder's operation.
.TP
.I "Access control"
Each forwarded port may have an access control list attached to it.
Only authorized hosts are allowed to connect.  Access control checks are
performed by quick checks on the client's IP address.
.TP
.I "Nonblocking single-process design"
The internal structure of the server is completely nonblocking.  The
connections don't block; the reading and writing don't block; the name
lookups don't block.  This is all done in a single process, with the
single exception of the DNS resolver.
.SS "Command line options"
The
.B fw
program understands a few simple command line options:
.TP
.B "\-h, \-\-help"
Displays a screen of help text on standard output and exits
successfully.
.TP
.B "\-v, \-\-version"
Writes the version number to standard output and exits successfully.
.TP
.B "\-u, \-\-usage"
Writes a terse usage summary to standard output and exits successfully.
.TP
.BI "\-f, \-\-file=" file
Read configuration information from
.IR file .
.TP
.B "\-d, \-\-dump"
Writes a dump of the final configuration to standard output and exits
successfully.
.TP
.B "\-b, \-\-background, \-\-fork"
Forks into the background after reading the configuration and
initializing properly.
.PP
Any further command line arguments are interpreted as configuration
lines to be read.  Configuration supplied in command line arguments has
precisely the same syntax as configuration in files.  If there are no
configurmation statements on the command line, and no
.B \-f
options were supplied, configuration is read from standard input, if
stdin is not a terminal.
.SS "Configuration language"
The forwarder understands a simple free-form configuration language,
described by the following BNF-like grammar:
.PP
.ll +20
.I config
::=
.IR stmt ...
.br
.I stmt
::=
.I fwd-stmt
|
.I acl-stmt
.br
.I fwd-stmt
::=
.B forward
.RB [ port ]
.I port
.RB [ to ]
.I addr
.RB [ : ]
.I port
.RI [ fwd-attr ]
.RB [ ; ]
.br
.I fwd-attr
::=
.B {
.IR acl-stmt ...
.B }
.br
.I acl-stmt
::=
.RB ( allow
|
.BR deny )
.RB [ from ]
.I addr
.RB [ /
.IR mask ]
.RB [ ; ]
.ll -20
.PP
In the above, a
.I port
may be a port number or service name defined in
.BR /etc/services ;
an
.I addr
may be a hostname or an IP address in dotted-quad notation; a
.I mask
may be either a netmask in dotted-quad notation or the integer number of
set bits in the netmask (e.g., 
.B /24
means the same as
.B /255.255.255.0
as a netmask).
.PP
A forwarding statement makes
.B fw
listen on the first-named port and open connections to the given address
and port when it 
.PP
ACL statements within a brace enclosed attribute list attached to a
forwarding statement apply only to that particular port; ACL statements
outside the scope of a forwarding statement contribute to a
.IR "global ACL" .
When an incoming connection is detected, it is first matched against
each rule in the port's local ACL in turn.  If there's no match there,
it's then looked up in the global ACL.  If that doesn't match either,
the connection is either refused or accepted, whichever is the opposite
of the last rule tried.  If there are no rules, all connections are
allowed since this is more useful than denying all connections.
.PP
Comments may be included in a configuration file.  They are introduced
by a
.RB ` # '
character, and continue until the end of the line.  When reading
configuration from the command line, each argument is considered to be a
separate line.
.SS "Logging"
The
.B fw
program logs each incoming connection.  Since the log entry is made
after the connection is established (since it needs to perform DNS and
RFC931 lookups), it includes the actual time of the connection in the
message body.
.PP
If the server is run in the foreground (i.e., the
.B \-b
flag isn't specified) log messages are sent to standard error.  If the
server is in the background, log messages are sent to the system log
service (see
.BR syslogd (8))
with facility
.B LOG_DAEMON
and level
.BR LOG_NOTICE .
.SS "The DNS resolver"
The background resolver works by creating child resolver processes.
There's a fixed limit of 10 concurrent resolvers: resolution jobs are
queued until a resolver becomes free.  Resolver processes persist for
multiple resolution jobs, although they are killed if they're idle for
more than a minute.
.PP
It's unlikely that the resolver's use of processes will become a problem
even for fairly heavily loaded servers.
.SH "BUGS"
I don't know of any bugs at all in
.BR fw .
If there are any, please let me know so I can fix them.  Provide the
version number from
.BR "fw \-\-version" ,
your operating system name and version, and complete descriptions of
what you did to cause the bug and what
.B fw
did wrong at that point.
.PP
I'm particularly concerned about security-related bugs.  If you find
any, please let me know
.I really
quickly.  I've taken some care to avoid security holes in
.B fw
but if there are any I've missed, I want to zap them as quickly as I
can.
.PP
Things which would be nice, but that I haven't done yet, are:
.hP \*o
Optionally notice connections from privileged ports and bind the
forwarding socket to a local privileged port.
.SH "AUTHOR"
Mark Wooding, <mdw@nsict.org>