blast: Upper-case metasyntactic variables in the usage message.

[fwd] / fw.1

.\" -*-nroff-*-
.\"
.\" $Id$
.\"
.\" 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.
.
.\"----- 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
..
.
.\" --- 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 [ \-dlq ]
.RB [ \-p
.IR file ]
.RB [ \-f
.IR file ]
.RB [ \-s
.IR user ]
.RB [ \-g
.IR group ]
.IR config-stmt ...
.
.\"--------------------------------------------------------------------------
.SH "DESCRIPTION"
.
The
.B fw
program is a simple port forwarder.  It supports a number of features
the author hasn't found in similar programs:
.TP
.I "Connection logging"
Each connection attempt to the forwarder is logged, giving the time of
the connection, the DNS-resolved hostname (if available), and the user
name resulting from an RFC931 lookup.  These lookups are done
asynchronously to the main forwarder's operation.
.TP
.I "Access control"
Each forwarded port may have an access control list attached to it.
Only authorized hosts are allowed to connect.  Access control checks are
performed by quick checks on the client's IP address.
.TP
.I "Nonblocking single-process design"
The internal structure of the server is completely nonblocking.  The
connections don't block; the reading and writing don't block; the name
lookups don't block.  This is all done in a single process, with the
single exception of the DNS resolver.
.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
program understands a few simple command line options:
.TP
.B "\-h, \-\-help"
Displays a screen of help text on standard output and exits
successfully.
.TP
.B "\-v, \-\-version"
Writes the version number to standard output and exits successfully.
.TP
.B "\-u, \-\-usage"
Writes a terse usage summary to standard output and exits successfully.
.TP
.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, \-\-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
.BI "\-p, \-\-pidfile=" file
Write
.BR fw 's
process-id to
.I file
during start-up.  If
.B \-d
is given too, then the process-id is written after forking (obviously).
.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
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.
.
.\"--------------------------------------------------------------------------
.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
::=
.I empty
|
.I file
.I stmt
.RB [ ; ]
.br
.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 {
.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 [[ : ] name [ : ]]
.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
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
::=
.RB [ port ]
.I port
.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
.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"
.B socket.inet.source.addr
.RB [ = ]
.RR any | \c
.I addr
.OD
Specify the IP address on which to listen for incoming connections.  The
default is
.BR any ,
which means to listen on all addresses, though it may be useful to
specify this explicitly, if the global setting is different.
.OE
.OS "Socket options"
.BR socket.inet.source. [ allow | deny ]
.RB [ host ]
.I addr
.RB [ /
.IR addr ]
.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
.OS "Socket options"
.BR socket.inet.source. [ allow | deny ]
.B priv-port
.OD
Accept or reject connections from low-numbered `privileged' ports, in
the range 0--1023.
.OE
.OS "Socket options"
.B socket.inet.dest.addr
.RB [ = ]
.RR any | \c
.I addr
.OD
Specify the IP address to bind the local socket to when making an
outbound connection.  The default is
.BR any ,
which means to use whichever address the kernel thinks is most
convenient.  This option is useful if the destination is doing
host-based access control and your server is multi-homed.
.OE
.OS "Socket options"
.B socket.inet.dest.priv-port
.RB [=]
.BR yes | no
.OD
Make a privileged connection (i.e., from a low-numbered port) to the
target.  This only works if
.B fw
was started with root privileges.  However, it still works if
.B fw
has
.I dropped
privileges after initialization (the
.B \-s
option).  Before dropping privileges, 
.B fw
forks off a separate process which continues to run with root
privileges, and on demand passes sockets bound to privileged ports and
connected to the appropriate peer back to the main program.  The
privileged child only passes back sockets connected to peer addresses
named in the configuration; even if the
.B fw
process is compromised, it can't make privileged connections to other
addresses.  Note that because of this privilege separation, it's also
not possible to reconfigure
.B fw
to make privileged connections to different peer addresses later by
changing configuration files and sending the daemon a
.BR SIGHUP .
.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
.sp -1 \" undo final space
.
.\"--------------------------------------------------------------------------
.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.
.
.\"--------------------------------------------------------------------------
.SH "GRAMMAR SUMMARY"
.
.SS "Basic syntax"
.I file
::=
.I empty
|
.I file
.I stmt
.RB [ ; ]
.br
.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 {
.I option-seq
.B }
.br
.I option-seq
::=
.I empty
|
.I option-stmt
.RB [ ; ]
.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 [[ : ] name [ : ]]
.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
.I inet-source-addr
::=
.RB [ port ]
.I port
.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.source. [ allow | deny ]
.RB [ host ]
.I addr
.RB [ /
.IR addr ]
.br
.BR socket.inet.source. [ allow | deny ]
.B priv-port
.br
.B socket.inet.source.addr
.RB [ = ]
.BR any | \c
.I addr
.br
.B socket.inet.dest.addr
.RB [ = ]
.BR any | \c
.I addr
.br
.B socket.inet.dest.priv-port
.RB [=]
.BR yes | no
.PP
.BR socket.unix.fattr. *
.
.\"--------------------------------------------------------------------------
.SH "BUGS"
.
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 --------------------------------------------------