--- /dev/null
+.\" -*-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>
~mdw / fwd / commitdiff