Document lots of new features and syntax.

[fwd] / fw.1

.\" -*-nroff-*-
.\"
.\" $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 [ \-dq ]
.RB [ \-f
.IR file ]
.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 sckets.  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
.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 "-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
.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 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
.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
.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
|
.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 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
::=
.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
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 address
.RB [ /
.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
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
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"
.
The syntax for IP addresses and filenames is nasty.  The requirement
that textual permissions strings be quoted is probably nastier.
.PP
IPv6 is not supported yet.  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.
.
.\"--------------------------------------------------------------------------
.SH "AUTHOR"
.
Mark Wooding, <mdw@nsict.org>
.
.\"----- That's all, folks --------------------------------------------------