.\" -*-nroff-*-
-.ie t .ds o \(bu
-.el .ds o o
+.\"
+.\" $Id: fw.1,v 1.2 1999/07/26 23:31: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.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
..
+.
+.\" --- Verbatim-oid typesetting ---
+.de VS
+.sp 1
+.RS
+.nf
+.ft B
+..
+.de VE
+.ft R
+.fi
+.RE
+.sp 1
+..
+.
+.\" --- 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" fw
+.
+.\"--------------------------------------------------------------------------
.SH NAME
+.
fw \- port forwarder
+.
+.\"--------------------------------------------------------------------------
.SH SYNOPSIS
+.
.B fw
-.RB [ \-db ]
+.RB [ \-dq ]
.RB [ \-f
.IR file ]
.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 sckets. Access control doesn't work on
+Unix domain sockets, though. (Yet.)
.SS "Command line options"
The
.B fw
.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 "-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.
.PP
Any further command line arguments are interpreted as configuration
lines to be read. Configuration supplied in command line arguments has
.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:
+.
+.\"--------------------------------------------------------------------------
+.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 consistituent 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 strictly optional in the grammar
+and can 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:
.PP
-.ll +20
-.I config
+.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
+.PP
+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. Local options, applied to a source or target in a
+.I 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:
+.PP
+.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
+.PP
+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
+is equivalent to
+.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 "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:
+.PP
+.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 [ : ]]
+.PP
+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:
+.PP
+.B file.create
+.RB [ = ]
+.BR yes | no
+.RS
+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.
+.RE
+.PP
+.B file.open
+.RB [ = ]
+.BR no | truncate | append
+.RS
+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.
+.RE
+.PP
+Under no circumstances will
+.B fw
+create a file through a `dangling' symbolic link.
+.PP
+The
+.B file
+source and target also accept
+.B fattr
+options for controlling the attributes of the created file. The prefix
+for setting file attributes is
+.BR file.fattr .
+.
+.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:
+.PP
+.IB prefix .fattr.mode
+.RB [ = ]
+.I mode
+.RS
+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. Note that
+.BR chmod -style
+strings may contain
+.RB ` = '
+and
+.RB ` , '
+characters that will need to be escaped or quoted.
+.RE
+.PP
+.IB prefix .fattr.owner
+.RB [ = ]
+.I user
+.RS
+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 .
+.RE
+.PP
+.IB prefix .fattr.group
+.RB [ = ]
+.I group
+.RS
+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 .
+.RE
+.
+.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:
+.PP
+.I source
+::=
+.I exec
+.br
+.I target
+::=
+exec
+.br
+.I exec
+::=
+.BR exec
+.RB [ . ]
+.I cmd-spec
+.br
+.I cmd-spec
+::=
+.I shell-cmd
|
-.I acl-stmt
+.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
+.PP
+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:
+.PP
+.B exec.logging
+.RB [ = ]
+.BR yes | no
+.RS
+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 .
+.RE
+.PP
+.B exec.dir
+.RB [ = ]
+.I file-name
+.RS
+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 .
+.RE
+.PP
+.B exec.root
+.RB [ = ]
+.I file-name
+.RS
+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 synonyms
+.BR cd ,
+.B chdir
+and
+.B cwd
+are accepted in place of
+.B dir .
+.RE
+.PP
+.B exec.user
+.RB [ = ]
+.I user
+.RS
+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 .
+.RE
+.PP
+.B exec.group
+.RB [ = ]
+.I group
+.RS
+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 .
+.RE
+.PP
+.BI exec.rlimit. limit \c
+.RB [ .hard | .soft ]
+.RB [ = ]
+.I value
+.RS
+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.
+.RE
+.PP
+.B exec.env.clear
+.RS
+Clears the program's environment.
+.RE
+.PP
+.B exec.env.unset
+.I var
+.RS
+Removes
+.I var
+from the program's environment. It is not an error if no variable named
+.I var
+exists.
+.RE
+.PP
+.BR exec.env. [ set ]
+.I var
+.RB [ = ]
+.I value
+.RS
+Assignes 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.
+.RE
+.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:
+.PP
+.ll +8i
+.I source
+::=
+.I socket-source
.br
-.I fwd-stmt
+.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
+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:
+.PP
+.B socket.conn
+.RB [ = ]
+.I number
+.RS
+Limits the number of simultaneous connections to this socket to the
+.I number
+given. The default is 256.
+.RE
+.PP
+.B socket.logging
+.RB [ = ]
+.BR yes | no
+.RS
+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.
+.RE
+.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:
+.PP
+.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 ]
-.RB [ ; ]
.br
-.I fwd-attr
+.I address
::=
-.B {
-.IR acl-stmt ...
-.B }
+.I addr-elt
+|
+.I address
+.I addr-elt
.br
-.I acl-stmt
+.I addr-elt
::=
-.RB ( allow
+.B .
|
-.BR deny )
+.I word
+.PP
+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:
+.PP
+.BR socket.inet. [ allow | deny ]
.RB [ from ]
-.I addr
+.I address
.RB [ /
-.IR mask ]
-.RB [ ; ]
-.ll -20
+.IR address ]
+.RS
+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.
.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 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.
+.RE
+.
+.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:
+.PP
+.I source-addr
+::=
+.I unix-addr
+.br
+.I target-addr
+::=
+.I unix-addr
+.br
+.I unix-addr
+::=
+.I file-name
+.PP
+The
+.B unix
+source address accepts
+.B fattr
+options to control the attributes of the socket file created. Sockets
+are removed if
.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.
+exits normally (which it will do if it runs out of sources or
+connections, or if killed by SIGINT or SIGTERM).
+.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 stdin, null to null, stdout
+.VE
+.
+.\"--------------------------------------------------------------------------
.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.
+.
+The syntax for IP addresses and filenames is nasty. The requirement
+that textual permissions strings be quoted is probably nastier.
.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.
+IPv6 is not supported yet. It's probably not a major piece of work to
+add.
.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.
+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.
+.
+.\"--------------------------------------------------------------------------
.SH "AUTHOR"
+.
Mark Wooding, <mdw@nsict.org>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blobdiff