.\" -*-nroff-*-
-.ie t .ds o \(bu
-.el .ds o o
+.\"
+.\" $Id: fw.1,v 1.15 2003/01/24 20:13:04 mdw Exp $
+.\"
+.\" Manual page for fw
+.\"
+.\" (c) 1999 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the `fw' port forwarder.
+.\"
+.\" `fw' is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" `fw' is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with `fw'; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\" ---- Revision history ---------------------------------------------------
+.\"
+.\" $Log: fw.1,v $
+.\" Revision 1.15 2003/01/24 20:13:04 mdw
+.\" Fix bogus examples. Explain quoting rules for `exec' endpoints.
+.\"
+.\" Revision 1.14 2002/02/23 00:05:12 mdw
+.\" Fix spacing around full stops (at last!).
+.\"
+.\" Revision 1.13 2002/02/22 23:45:01 mdw
+.\" Add option to change the listen(2) parameter.
+.\"
+.\" Revision 1.12 2001/02/23 09:11:29 mdw
+.\" Update manual style.
+.\"
+.\" Revision 1.11 2001/02/05 19:47:11 mdw
+.\" Minor fixings to wording.
+.\"
+.\" Revision 1.10 2001/02/03 20:30:03 mdw
+.\" Support re-reading config files on SIGHUP.
+.\"
+.\" Revision 1.9 2000/03/23 00:37:33 mdw
+.\" Add option to change user and group after initialization. Naughtily
+.\" reassign short equivalents of --grammar and --options.
+.\"
+.\" Revision 1.8 1999/12/22 15:44:43 mdw
+.\" Fix some errors, and document new option.
+.\"
+.\" Revision 1.7 1999/10/22 22:45:15 mdw
+.\" Describe new socket connection options.
+.\"
+.\" Revision 1.6 1999/10/10 16:46:29 mdw
+.\" Include grammar and options references at the end of the manual.
+.\"
+.\" Revision 1.5 1999/09/26 18:18:05 mdw
+.\" Remove a fixed bug from the list. Fix some nasty formatting
+.\" misfeatures.
+.\"
+.\" Revision 1.4 1999/08/19 18:32:48 mdw
+.\" Improve lexical analysis. In particular, `chmod' patterns don't have to
+.\" be quoted any more.
+.\"
+.\" Revision 1.3 1999/07/30 06:49:00 mdw
+.\" Minor tidying and typo correction.
+.\"
+.\" Revision 1.2 1999/07/26 23:31:04 mdw
+.\" Document lots of new features and syntax.
+.\"
+.
+.\"----- Various bits of fancy styling --------------------------------------
+.
+.\" --- Indented paragraphs with right-aligned tags ---
+.
.de hP
.IP
\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
..
-.TH fw 1 "1 July 1999" fw
+.
+.\" --- Verbatim-oid typesetting ---
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.
+.\" --- Grammar markup ---
+.\"
+.\" This is mainly for the benefit of the automatic scripts which
+.\" generate the grammar summary.
+.
+.de GS
+.PP
+..
+.de GE
+.PP
+..
+.
+.de OS
+.PP
+..
+.de OD
+.RS
+..
+.de OE
+.RE
+..
+.
+.\" --- Other bits of styling ---
+.
+.ie t \{\
+. ds o \(bu
+. ds ss \s8\u
+. ds se \d\s0
+. if \n(.g \{\
+. fam P
+. \}
+.\}
+.el \{\
+. ds o o
+. ds ss ^
+. ds se
+.\}
+.
+.\"--------------------------------------------------------------------------
+.
+.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
+.
+.\"--------------------------------------------------------------------------
.SH NAME
+.
fw \- port forwarder
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.B fw
-.RB [ \-db ]
+.RB [ \-dlq ]
.RB [ \-f
.IR file ]
+.RB [ \-s
+.IR user ]
+.RB [ \-g
+.IR group ]
.IR config-stmt ...
-.SH DESCRIPTION
+.
+.\"--------------------------------------------------------------------------
+.SH "DESCRIPTION"
+.
The
.B fw
program is a simple port forwarder. It supports a number of features
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.
+.TP
+.I "Support for Unix-domain sockets"
+Connections from and to Unix-domain sockets can be handled just as
+easily as more normal Internet sockets. Access control doesn't work on
+Unix domain sockets, though. (Yet.)
.SS "Command line options"
The
.B fw
.B "\-u, \-\-usage"
Writes a terse usage summary to standard output and exits successfully.
.TP
+.B "\-G, \-\-grammar"
+Writes a summary of the configuration file grammar to standard output
+and exits successfully.
+.TP
+.B "\-O, \-\-options"
+Writes a summary of the source and target options to standard output and
+exits successfully.
+.TP
.BI "\-f, \-\-file=" file
Read configuration information from
.IR file .
+Equivalent to an
+.RB ` include
+.IR file '
+configuration file statement.
.TP
-.B "\-d, \-\-dump"
-Writes a dump of the final configuration to standard output and exits
-successfully.
-.TP
-.B "\-b, \-\-background, \-\-fork"
+.B "\-d, \-\-daemon, \-\-fork"
Forks into the background after reading the configuration and
initializing properly.
+.TP
+.B "\-l, \-\-syslog, \-\-log"
+Emit logging information to the system log, rather than standard error.
+.TP
+.B "\-q, \-\-quiet"
+Don't output any logging information. This option is not recommended
+for normal use, although it can make system call traces clearer so I use
+it when debugging.
+.TP
+.BI "\-s, \-\-setuid=" user
+Change uid to that of
+.IR user ,
+which may be either a user name or uid number, after initializing all
+the sources. This will usually require elevated privileges.
+.TP
+.BI "\-g, \-\-setgid=" group
+Change gid to that of
+.IR group ,
+which may be either a group name or gid number, after initializing all
+the sources. If the operating system understands supplementary groups
+then the supplementary groups list is altered to include only
+.IR group .
.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
+configuration 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
+.
+.\"--------------------------------------------------------------------------
+.SH "CONFIGURATION LANGUAGE"
+.
+The
+.B fw
+program has a fairly sophisticated configuration language to let you
+describe which things should be forwarded where and what special
+features there should be.
+.SS "Lexical structure"
+There are four types of characters.
+.TP
+.I "word constituent characters"
+Word constituent characters are gathered together into words.
+Depending on its surrounding context, a word might act as a keyword or a
+string. All alphanumerics are word constituents, as is the hyphen
+.RB ` \- '.
+Other characters may change their status in future versions.
+.TP
+.I "self-delimiting characters"
+Self-delimiting characters always stand alone. They act as punctuation,
+shaping the sequence of words into more complex grammatical forms. The
+characters
+.RB ` { ',
+.RB ` } ',
+.RB ` [ ',
+.RB ` ] ',
+.RB ` / ',
+.RB ` , ',
+.RB ` = ',
+.RB ` : ',
+.RB ` ; '
+and
+.RB ` . '
+are self-delimiting. Note that while some characters, e.g.,
+.RB ` [ '
+and
+.RB ` ; ',
+require escaping by the shell, they are mostly optional in the grammar
+and can tend to be omitted in quick hacks at the shell prompt.
+.TP
+.I "whitespace characters"
+Whitespace characters separate words but are otherwise ignored. All
+`normal' whitespace characters (e.g., space, tab and newline) are
+considered to be whitespace for these purposes.
+.TP
+.I "special characters"
+There are three special characters. The
+.RB ` # '
+character, if it appears at the start of a word, introduces a
+.I comment
+which extends to the end of the current line or command-line argument.
+Within a word, it behaves like a normal word-constituent character. The
+backslash
+.RB ` \e '
+escapes the following character causing it to be interpreted as a word
+constituent regardless of its normal type. The double-quote
+.RB ` """" '
+escapes all characters other than backslashes up to the next
+double-quote and causes them to be regarded as word constituents. Note
+that you don't have to quote a whole word. The backslash can escape a
+quote character allowing you to insert it into a word if really
+necessary.
+.
+.SS "Basic syntax"
+The overall syntax looks a bit like this:
+.GS "Basic syntax"
+.I file
::=
-.IR stmt ...
+.I empty
+|
+.I file
+.I stmt
+.RB [ ; ]
.br
.I stmt
::=
-.I fwd-stmt
+.I option-stmt
+|
+.I fw-stmt
+.br
+.I fw-stmt
+::=
+.B fw
+.I source
+.I options
+.RB [ to | \-> ]
+.I target
+.I options
+.br
+.I options
+::=
+.B {
+.I option-seq
+.B }
+.br
+.I option-seq
+::=
+.I empty
+|
+.I option-stmt
+.RB [ ; ]
+.I option-seq
+.GE
+If you prefer, the keyword
+.RB ` fw '
+may be spelt
+.RB ` forward '
+or
+.RB ` from '.
+All are equivalent.
+.
+.SS "Sources and targets"
+Forwarding is set up by attaching
+.I targets
+to
+.IR sources .
+Sources are things which are capable of
+.I initiating
+one end of a data flow on their own, while targets are things which are
+capable of setting up the other end on demand. In the case of a TCP
+port forwarder, the part which listens for incoming client connections
+is the source, while the part which sets up outgoing connections to the
+destination server is the target.
+.PP
+Essentially, all
+.B fw
+does is set up a collection of sources and targets based on your
+configuration file so that when a source decides to initiate a data
+flow, it tells its target to set its end up, and then squirts data back
+and forth between the two until there's no more.
+.PP
+Some sources are
+.IR persistent :
+they stay around indefinitely setting up multiple attachments to
+targets. Others are
+.IR transient :
+they set up one connection and then disappear. If all the sources
+defined are transient, then
+.B fw
+will quit when no more active sources remain and all connections have
+terminated.
+.PP
+The
+.B fw
+program is fairly versatile. It allows you to attach any supported type
+of source to any supported type of target. This will, I hope, be the
+case in all future versions.
+.PP
+The syntax of a
+.I source
+or
+.I target
+depend on the source or target type, and are therefore described in the
+sections specific to the various types.
+.
+.SS "Options structure"
+Most of the objects that
+.B fw
+knows about (including sources and targets, but also other more specific
+things such as socket address types) can have their behaviour modified
+by
+.IR options .
+The options available at a particular point in the configuration depend
+on the
+.IR context .
+A global option, outside of a
+.I fw-stmt
+has no context unless it is explicitly qualified, and affects global
+behaviour. A local option, applied to a source or target in a
+.IR fw-stmt ,
+has the context of the type of source or target to which it is applied,
+and affects only that source or target.
+.PP
+Note that it's important to distinguish between an option's context
+(which is affected by its qualification) and its local or global
+status. No matter how qualified, a global option will always control
+default options for objects, and a local option will only affect a
+specific source or target.
+.PP
+The syntax for qualifying options is like this:
+.GS "Option syntax"
+.I option-stmt
+::=
+.I q-option
+.br
+.I q-option
+::=
+.I option
+.br
+ |
+.I prefix
+.B .\&
+.I q-option
+.br
+ |
+.I prefix
+.B {
+.I option-seq
+.B }
+.br
+.I prefix
+::=
+.I word
+.GE
+Thus, you may qualify either an individual option or a sequence of
+options. The two are equivalent; for example,
+.VS
+exec.rlimit {
+ core = 0;
+ cpu = 60;
+}
+.VE
+means the same as
+.VS
+exec.rlimit.core = 0;
+exec.rlimit.cpu = 0;
+.VE
+For each option, there is a sequence of prefixes which maximally qualify
+that option. An option prefixed with this sequence is
+.IR "fully qualified" .
+In actual use, some or all of those prefixes may be omitted. However,
+it's possible for the option to become
+.I ambiguous
+if you do this. For example, the option
+.B fattr.owner
+may refer either to
+.B file.fattr.owner
+or to
+.BR socket.unix.fattr.owner .
+In this case, the ambiguity is benign: a local option will have as its
+context an appropriate source or target, and both global options
+actually control the same default. However, the option
+.B logging
+may mean either
+.B socket.logging
+or
+.BR exec.logging ,
+which have separate defaults, and which one you actually get depends on
+the exact implementation of
+.BR fw 's
+option parser. (Currently this would resolve to
+.BR exec.logging ,
+although this may change in a later version.)
+.PP
+In this manual, options are usually shown in their fully-qualified form.
+.
+.SS "File attributes for created files: `fattr'"
+Both the
+.B file
+and
+.B socket
+sources and targets can create new filesystem objects. The
+.B fattr
+options allow control over the attributes of the newly-created objects.
+Both
+.B file
+and
+.B socket
+use the same set of defaults, so a prefix of
+.B fattr
+is good enough for setting global options, and the implicit context
+disambiguates local options.
+.PP
+The following file attribute options are supported:
+.OS "File attribute options (`fattr')"
+.IB prefix .fattr.mode
+.RB [ = ]
+.I mode
+.OD
+Sets the permissions mode for a new file. The
+.I mode
+argument may be either an octal number or a
+.BR chmod (1)-style
+string which acts on the default permissions established by the
+prevailing
+.BR umask (2)
+setting. The characters
+.RB ` = '
+and
+.RB ` , '
+do not have to be quoted within the mode string.
+.OE
+.OS "File attribute options (`fattr')"
+.IB prefix .fattr.owner
+.RB [ = ]
+.I user
+.OD
+Sets the owner for newly created files. On non-broken systems you will
+need to be the superuser to set the owner on a file. The
+.I user
+may either be a numeric uid or a username. The default is not to change
+the owner of the file once it's created. The synonyms
+.B uid
+and
+.B user
+are accepted in place of
+.BR owner .
+.OE
+.OS "File attribute options (`fattr')"
+.IB prefix .fattr.group
+.RB [ = ]
+.I group
+.OD
+Sets the group for newly created files. You will usually need to be a
+member of the group in question order to set the group of a file. The
+.I group
+may either be a numeric gid or a group name. The default is not to
+change the group of the file once it's created. The synonym
+.B gid
+is accepted in place of
+.BR group .
+.OE
+.
+.SS "The `file' source and target types"
+The
+.B file
+source and target allow data to move to and from objects other
+than sockets within the Unix filesystem. (Unix-domain sockets are
+handled using the
+.B socket
+source and target.)
+.PP
+If a
+.B file
+is used as a source, it is set up immediately.
+.PP
+The syntax of
+.B file
+sources and targets is like this:
+.GS "File sources and targets"
+.I source
+::=
+.I file
+.br
+.I target
+::=
+.I file
+.br
+.I file
+::=
+.B file
+.RB [ .\& ]
+.I fspec
+.RB [ ,
+.IR fspec ]
+.br
+.I fspec
+::=
+.I fd-spec
+|
+.I name-spec
+|
+.I null-spec
+.br
+.I fd-spec
+::=
+.RB [[ : ] fd [ : ]]
+.IR number \c
+.RB | stdin | stdout
+.br
+.I name-spec
+::=
+.RB [[ : ] file [ : ]]
+.I file-name
+.br
+.I file-name
+::=
+.I path-seq
|
-.I acl-stmt
+.B [
+.I path-seq
+.B ]
.br
-.I fwd-stmt
+.I path-seq
+::=
+.I path-elt
+|
+.I path-seq
+.I path-elt
+.br
+.I path-elt
+::=
+.B /
+|
+.I word
+.br
+.I null-spec
+::=
+.RB [ : ] null [ : ]
+.GE
+The
+.I file
+specification describes two files, the first to be used as input, the
+second to be used as output, each described by an
+.IR fspec .
+.PP
+If none of the keywords
+.RB ` fd ',
+.RB ` name '
+or
+.RB ` null '
+are given, the type of an
+.I fspec
+is deduced from its nature: if it matches one of the strings
+.RB ` stdin '
+or
+.RB ` stdout ',
+or begins with a digit, it's considered to be a file descriptor;
+otherwise it's interpreted as a filename.
+.PP
+A
+.RB ` name '
+spec describes a file by its name within the filesystem. It is opened
+when needed and closed again after use. For output files, the precise
+behaviour is controlled by options described below.
+.PP
+A
+.RB ` null '
+spec attaches the input or output of the source or target to
+.BR /dev/null .
+.PP
+An
+.RB ` fd '
+spec uses an existing open file descriptor, given either by number or a
+symbolic name. The name
+.RB ` stdin '
+refers to standard input (file descriptor 0 on normal systems) and
+.RB ` stdout '
+refers to standard output (file descriptor 1). The names work in
+exactly the same way as the equivalent file descriptor numbers.
+.PP
+If the output
+.I fspec
+is omitted, the input
+.I fspec
+is used for both input and output. Exception: if the input refers to
+standard input then the output will refer to standard output instead.
+.PP
+All
+.B file
+options apply equally to sources and targets. The options are as
+follows:
+.OS "File options"
+.B file.create
+.RB [ = ]
+.BR yes | no
+.OD
+Whether to create the output file if it doesn't exist. If
+.B no
+(the default), an error is reported if the file doesn't exist. If
+.BR yes ,
+the file is created if it doesn't exist.
+.OE
+.OS "File options"
+.B file.open
+.RB [ = ]
+.BR no | truncate | append
+.OD
+Controls the behaviour if the output file already exists. If
+.BR no ,
+an error is reported. If
+.B truncate
+(the default), the existing file is replaced by the new data. If
+.BR append ,
+the new data is appended to the file.
+.OE
+.OS "File options"
+.BR file.fattr.*
+.OD
+The
+.B file
+source and target also accept
+.B fattr
+options for controlling the attributes of the created file.
+.OE
+.PP
+Under no circumstances will
+.B fw
+create a file through a `dangling' symbolic link.
+.
+.SS "The `exec' source and target types"
+The
+.B exec
+source and target execute programs and allow access to their standard
+input and output streams. Both source and target have the same syntax,
+which is as follows:
+.GS "Exec source and target"
+.I source
+::=
+.I exec
+.br
+.I target
+::=
+exec
+.br
+.I exec
+::=
+.BR exec
+.RB [ .\& ]
+.I cmd-spec
+.br
+.I cmd-spec
+::=
+.I shell-cmd
+|
+.RI [ prog-name ]
+.B [
+.I argv0
+.I arg-seq
+.B ]
+.br
+.I arg-seq
+::=
+.I word
+|
+.I arg-seq
+.I word
+.br
+.I shell-cmd
+::=
+.I word
+.br
+.I argv0
+::=
+.I word
+.GE
+If a single word is given, it is a
+.I shell-cmd
+and will be passed to the Bourne shell for execution. If a
+bracket-enclosed sequence of words is given, it is considered to be a
+list of arguments to pass to the program: if a
+.I prog-name
+is also supplied, it names the file containing the program to execute;
+otherwise the file named by the first argument
+.RI ( argv0 )
+is used.
+.PP
+Note that the shell command or program name string must, if present,
+have any delimiter characters (including
+.RB ` / '
+and
+.RB ` . ')
+quoted; this is not required in the
+.RB ` [ '-enclosed
+argument list.
+.PP
+The standard input and output of the program are forwarded to the other
+end of the connection. The standard error stream is caught by
+.B fw
+and logged.
+.PP
+The
+.B exec
+source and target both understand the same set of options. The list of
+options supported is as follows:
+.OS "Exec options"
+.B exec.logging
+.RB [ = ]
+.BR yes | no
+.OD
+Whether to log the start and end of executed programs. If
+.B yes
+(the default), a log message is emitted when the program is started
+listing its process id, and another is emitted when the program finishes
+giving its process id and exit status. If
+.BR no ,
+these messages are not emitted. However the standard error stream is
+still logged. The
+.B log
+abbreviation is accepted as a synonym for
+.BR logging .
+.OE
+.OS "Exec options"
+.B exec.dir
+.RB [ = ]
+.I file-name
+.OD
+Sets the current directory from which the the program should be run.
+The default is not to change directory. The synonyms
+.BR cd ,
+.B chdir
+and
+.B cwd
+are accepted in place of
+.BR dir .
+.OE
+.OS "Exec options"
+.B exec.root
+.RB [ = ]
+.I file-name
+.OD
+Sets the root directory for the program, using the
+.BR chroot (2)
+system call. You must be the superuser for this option to work. The
+default is not to set a root directory. The synonym
+.B chroot
+is accepted in place of
+.BR root .
+.OE
+.OS "Exec options"
+.B exec.user
+.RB [ = ]
+.I user
+.OD
+Sets the user (real and effective uid) to run the program as. This will
+usually require superuser privileges to work. The default is not to
+change uid. The synonym
+.B uid
+is accepted in place of
+.BR user .
+.OE
+.OS "Exec options"
+.B exec.group
+.RB [ = ]
+.I group
+.OD
+Sets the group (real and effective gid) to run the program as. If
+running with superuser privileges, the supplementary groups list is
+cleared at the same time. The default is not to change gid (or clear
+the supplementary groups list). The synonym
+.B gid
+is accepted in place of
+.BR group .
+.OE
+.OS "Exec options"
+.BI exec.rlimit. limit \c
+.RB [ .hard | .soft ]
+.RB [ = ]
+.I value
+.OD
+Set resource limits for the program. The
+.I limit
+may be one of the resource limit names described in
+.BR setrlimit (2),
+in lower-case and without the
+.B RLIMIT_
+prefix; for example,
+.B RLIMIT_CORE
+becomes simply
+.BR core .
+The
+.I value
+is a number, followed optionally by
+.B k
+to multiply by 1024 (2\*(ss10\*(se),
+.B m
+to multiply by 1048576 (2\*(ss20\*(se), or
+.B g
+to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
+versions of these if they want. If
+.B .hard
+or
+.B .soft
+was specified, only the hard or soft limit is set; otherwise both are
+set to the same value. Only the superuser can raise the hard limit.
+The soft limit cannot be set above the hard limit.
+.OE
+.OS "Exec options"
+.B exec.env.clear
+.OD
+Clears the program's environment.
+.OE
+.PP
+.B exec.env.unset
+.I var
+.OD
+Removes
+.I var
+from the program's environment. It is not an error if no variable named
+.I var
+exists.
+.OE
+.OS "Exec options"
+.BR exec.env. [ set ]
+.I var
+.RB [ = ]
+.I value
+.OD
+Assigns the variable
+.I var
+the value
+.I value
+in the program's environment, possibly replacing the existing value.
+The
+.B set
+may be omitted if the
+.B env
+qualifier is present.
+.OE
+.PP
+Note that environment variable modifications are performed in order,
+global modifications before local ones.
+.
+.SS "The `socket' source and target types"
+The
+.B socket
+source and target provide access to network services. Support is
+currently provided for TCP/IP and Unix-domain sockets, although other
+address types can be added with reasonable ease.
+.PP
+The syntax for socket sources and targets is:
+.GS "Socket source and target"
+.ll +8i
+.I source
+::=
+.I socket-source
+.br
+.I target
+::=
+.I socket-target
+.br
+.I socket-source
+::=
+.RB [ socket [ .\& ]]
+.RB [[ : ] \c
+.IR addr-type \c
+.RB [ : ]]
+.I source-addr
+.br
+.I socket-target
+::=
+.RB [ socket [ .\& ]]
+.RB [[ : ] \c
+.IR addr-type \c
+.RB [ : ]]
+.I target-addr
+.ll -8i
+.GE
+The syntax of the source and target addresses depend on the address
+types, which are described below. The default address type, if no
+.I addr-type
+is given, is
+.BR inet .
+.PP
+Socket sources support options; socket targets do not. The source
+options provided are:
+.OS "Socket options"
+.B socket.conn
+.RB [ = ]
+.IR number | \c
+.BR unlimited | one-shot
+.OD
+Controls the behaviour of the source when it receives connections. A
+.I number
+limits the number of simultaneous connections. The value
+.B unlimited
+(or
+.BR infinite )
+removes any limit on the number of connections possible. The value
+.B one-shot
+will remove the socket source after a single successful connection.
+(Connections refused by access control systems don't count here.)
+The default is to apply a limit of 256 concurrent connections. Use of
+the
+.B unlimited
+option is not recommended.
+.OE
+.OS "Socket options"
+.B socket.listen
+.RB [ = ]
+.I number
+.OD
+Sets the maximum of the kernel incoming connection queue for this socket
+source. This is the number given to the
+.BR listen (2)
+system call. The default is 5.
+.OE
+.OS "Socket options"
+.B socket.logging
+.RB [ = ]
+.BR yes | no
+.OD
+Whether to log incoming connections. If
+.B yes
+(the default) incoming connections are logged, together with information
+about the client (where available) and whether the connection was
+accepted or refused. If
+.BR no ,
+log messages are not generated.
+.OE
+.PP
+Address types also provide their own options.
+.
+.SS "The `inet' socket address type"
+The
+.B inet
+address type provides access to TCP ports. The
+.B inet
+source and target addresses have the following syntax:
+.GS "Socket source and target"
+.I inet-source-addr
::=
-.B forward
.RB [ port ]
.I port
-.RB [ to ]
-.I addr
+.br
+.I inet-target-addr
+::=
+.I address
.RB [ : ]
.I port
-.RI [ fwd-attr ]
+.br
+.I address
+::=
+.I addr-elt
+|
+.I address
+.I addr-elt
+.br
+.I addr-elt
+::=
+.B .\&
+|
+.I word
+.GE
+A
+.I port
+may be given as a port number or a service name from the
+.B /etc/services
+file (or YP map if you do that sort of thing). A
+.B hostname
+may be a textual hostname or a numerical IP address.
+.PP
+The
+.B inet
+source address accepts the following options:
+.OS "Socket options"
+.BR socket.inet. [ allow | deny ]
+.RB [ from ]
+.I address
+.RB [ /
+.IR address ]
+.OD
+Adds an entry to the source's access control list. If only one
+.I address
+is given, the entry applies only to that address; if two are given, the
+first is a network address and the second is a netmask either in
+dotted-quad format or a simple number of bits (e.g.,
+.B /255.255.255.192
+and
+.B /26
+mean the same), and the entry applies to any address which, when masked
+by the netmask, is equal to the masked network address.
+.OE
+.PP
+The access control rules are examined in the order: local entries first,
+then global ones, each in the order given in the configuration file.
+The first matching entry is used. If no entries match, the behaviour is
+the
+.I opposite
+of the last entry tried. If there are no entries defined, the default
+is to allow all clients.
+.
+.SS "The `unix' socket address type"
+The
+.B unix
+address type allows access to Unix-domain sockets. The syntax for
+.B unix
+source and target addresses is like this:
+.GS "Socket source and target"
+.I unix-source-addr
+::=
+.I file-name
+.br
+.I unix-target-addr
+::=
+.I file-name
+.GE
+The following options are supported by the
+.B unix
+source address type:
+.OS "Socket options"
+.BR socket.unix.fattr. *
+.OD
+The
+.B unix
+source address accepts
+.B fattr
+options to control the attributes of the socket file created.
+.OE
+.PP
+Sockets are removed if
+.B fw
+exits normally (which it will do if it runs out of sources or
+connections, or if
+.B fw
+shuts down in a clean way).
+.SH "EXAMPLES"
+To forward the local port 25 to a main mail server:
+.VS
+from 25 to mailserv:25
+.VE
+To attach a fortune server to a Unix-domain socket:
+.VS
+from unix:/tmp/fortunes
+to exec [/usr/games/fortune] { user nobody }
+.VE
+To fetch a fortune from the server:
+.VS
+from file stdin, stdout to unix:/tmp/fortunes
+.VE
+To emulate
+.BR cat (1):
+.VS
+from file stdin, null to file null, stdout
+.VE
+.
+.\"--------------------------------------------------------------------------
+.SH "SIGNAL HANDLING"
+.
+The
+.B fw
+program responds to various signals when it's running. If it receives
+.B SIGTERM
+or
+.BR SIGINT ,
+.B fw
+performs a
+.I graceful
+shutdown: it removes all of its sources, and will exit when no more
+connections are running. (Note that if the disposition
+.B SIGINT
+was to ignore it,
+.B fw
+does not re-enable the signal. You'll have to send
+.B SIGTERM
+in that case.) If
+.B fw
+receives
+.BR SIGQUIT ,
+it performs an
+.I abrupt
+shutdown: it removes all sources and extant connections and closes down
+more-or-less immediately.
+.PP
+Finally, if any configuration files (other than standard input) were
+provided to
+.B fw
+on its command line using the
+.B \-f
+option, a
+.B SIGHUP
+signal may be sent to instruct
+.B fw
+to reload its configuration. Any existing connections are allowed to
+run their course. If no such configuration files are available,
+.B fw
+just logs a message about the signal and continues.
+.PP
+.
+.\"--------------------------------------------------------------------------
+.SH "GRAMMAR SUMMARY"
+.
+.SS "Basic syntax"
+.I file
+::=
+.I empty
+|
+.I file
+.I stmt
.RB [ ; ]
.br
-.I fwd-attr
+.I stmt
+::=
+.I option-stmt
+|
+.I fw-stmt
+.br
+.I fw-stmt
+::=
+.B fw
+.I source
+.I options
+.RB [ to | \-> ]
+.I target
+.I options
+.br
+.I options
::=
.B {
-.IR acl-stmt ...
+.I option-seq
.B }
.br
-.I acl-stmt
+.I option-seq
::=
-.RB ( allow
+.I empty
|
-.BR deny )
-.RB [ from ]
-.I addr
-.RB [ /
-.IR mask ]
+.I option-stmt
.RB [ ; ]
-.ll -20
+.I option-seq
+.
+.SS "Option syntax"
+.I option-stmt
+::=
+.I q-option
+.br
+.I q-option
+::=
+.I option
+.br
+ |
+.I prefix
+.B .\&
+.I q-option
+.br
+ |
+.I prefix
+.B {
+.I option-seq
+.B }
+.br
+.I prefix
+::=
+.I word
+.
+.SS "File source and target"
+.I source
+::=
+.I file
+.br
+.I target
+::=
+.I file
+.br
+.I file
+::=
+.B file
+.RB [ .\& ]
+.I fspec
+.RB [ ,
+.IR fspec ]
+.br
+.I fspec
+::=
+.I fd-spec
+|
+.I name-spec
+|
+.I null-spec
+.br
+.I fd-spec
+::=
+.RB [[ : ] fd [ : ]]
+.IR number \c
+.RB | stdin | stdout
+.br
+.I name-spec
+::=
+.RB [[ : ] file [ : ]]
+.I file-name
+.br
+.I file-name
+::=
+.I path-seq
+|
+.B [
+.I path-seq
+.B ]
+.br
+.I path-seq
+::=
+.I path-elt
+|
+.I path-seq
+.I path-elt
+.br
+.I path-elt
+::=
+.B /
+|
+.I word
+.br
+.I null-spec
+::=
+.RB [ : ] null [ : ]
+.
+.SS "Exec source and target"
+.I source
+::=
+.I exec
+.br
+.I target
+::=
+exec
+.br
+.I exec
+::=
+.BR exec
+.RB [ .\& ]
+.I cmd-spec
+.br
+.I cmd-spec
+::=
+.I shell-cmd
+|
+.RI [ prog-name ]
+.B [
+.I argv0
+.I arg-seq
+.B ]
+.br
+.I arg-seq
+::=
+.I word
+|
+.I arg-seq
+.I word
+.br
+.I shell-cmd
+::=
+.I word
+.br
+.I argv0
+::=
+.I word
+.
+.SS "Socket source and target"
+.ll +8i
+.I source
+::=
+.I socket-source
+.br
+.I target
+::=
+.I socket-target
+.br
+.I socket-source
+::=
+.RB [ socket [ .\& ]]
+.RB [[ : ] \c
+.IR addr-type \c
+.RB [ : ]]
+.I source-addr
+.br
+.I socket-target
+::=
+.RB [ socket [ .\& ]]
+.RB [[ : ] \c
+.IR addr-type \c
+.RB [ : ]]
+.I target-addr
+.ll -8i
.PP
-In the above, a
+.I inet-source-addr
+::=
+.RB [ port ]
.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.
+.br
+.I inet-target-addr
+::=
+.I address
+.RB [ : ]
+.I port
+.br
+.I address
+::=
+.I addr-elt
+|
+.I address
+.I addr-elt
+.br
+.I addr-elt
+::=
+.B .\&
+|
+.I word
+.PP
+.I unix-source-addr
+::=
+.I file-name
+.br
+.I unix-target-addr
+::=
+.I file-name
+.
+.\"--------------------------------------------------------------------------
+.SH "OPTION SUMMARY"
+.
+.SS "File attributes (`fattr')"
+.IB prefix .fattr.mode
+.RB [ = ]
+.I mode
+.br
+.IB prefix .fattr.owner
+.RB [ = ]
+.I user
+.br
+.IB prefix .fattr.group
+.RB [ = ]
+.I group
+.
+.SS "File options"
+.B file.create
+.RB [ = ]
+.BR yes | no
+.br
+.B file.open
+.RB [ = ]
+.BR no | truncate | append
+.br
+.BR file.fattr. *
+.
+.SS "Exec options"
+.B exec.logging
+.RB [ = ]
+.BR yes | no
+.br
+.B exec.dir
+.RB [ = ]
+.I file-name
+.br
+.B exec.root
+.RB [ = ]
+.I file-name
+.br
+.B exec.user
+.RB [ = ]
+.I user
+.br
+.B exec.group
+.RB [ = ]
+.I group
+.br
+.BI exec.rlimit. limit \c
+.RB [ .hard | .soft ]
+.RB [ = ]
+.I value
+.br
+.B exec.env.clear
+.br
+.B exec.env.unset
+.I var
+.br
+.BR exec.env. [ set ]
+.I var
+.RB [ = ]
+.I value
+.
+.SS "Socket options"
+.B socket.conn
+.RB [ = ]
+.IR number | \c
+.BR unlimited | one-shot
+.br
+.B socket.listen
+.RB [ = ]
+.I number
+.br
+.B socket.logging
+.RB [ = ]
+.BR yes | no
+.PP
+.BR socket.inet. [ allow | deny ]
+.RB [ from ]
+.I address
+.RB [ /
+.IR address ]
+.PP
+.BR socket.unix.fattr. *
+.
+.\"--------------------------------------------------------------------------
.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.
+.
+The syntax for IP addresses and filenames is nasty.
+.PP
+IPv6 is not supported yet. Because of
+.BR fw 's
+socket address architecture, it's probably not a major piece of work to
+add.
+.PP
+Please inform me of any security problems you think you've identified in
+this program. I take security very seriously, and I will fix security
+holes as a matter of priority when I find out about them. I will be
+annoyed if I have to read about problems on Bugtraq because they weren't
+mailed to me first.
+.PP
+The program is too complicated, and this manual page is too long.
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@nsict.org>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blobdiff