.\" -*-nroff-*-
-.ie t .ds o \(bu
-.el .ds o o
+.\"
+.\" $Id: fw.1,v 1.4 1999/08/19 18:32:48 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.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
..
+.
+.\" --- 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 sockets. 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
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:
+.
+.\"--------------------------------------------------------------------------
+.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 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. The characters
+.RB ` = '
+and
+.RB ` , '
+do not have to be quoted within the mode string.
+.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
+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.
+.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