+.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
+|
+.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 [ : ]
+.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
+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.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