--- /dev/null
+.\" -*-nroff-*-
+.\"
+.\" Manual page for fwd
+.\"
+.\" (c) 1999 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the `fwd' port forwarder.
+.\"
+.\" `fwd' 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.
+.\"
+.\" `fwd' 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 `fwd'; 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 GL
+..
+.
+.de OS
+.PP
+..
+.de OD
+.RS
+..
+.de OE
+.RE
+..
+.de OL
+..
+.
+.\" --- 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 fwd 1 "1 July 1999" "Straylight/Edgeware" "fwd port forwarder"
+.
+.\"--------------------------------------------------------------------------
+.SH NAME
+.
+fwd \- port forwarder
+.
+.\"--------------------------------------------------------------------------
+.SH SYNOPSIS
+.
+.B fwd
+.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 fwd
+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 fwd
+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 fwd '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 fwd
+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 fwd-stmt
+.br
+.I fwd-stmt
+::=
+.B fwd
+.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 ` fwd '
+may be spelt
+.RB ` fwd ',
+.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 fwd
+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 fwd
+will quit when no more active sources remain and all connections have
+terminated.
+.PP
+The
+.B fwd
+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 fwd
+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 fwd-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 fwd-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 fwd '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 attributes (`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 attributes (`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 attributes (`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 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 [ : ]
+.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 fwd
+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
+::=
+.I 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 fwd
+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
+.OS "Exec options"
+.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"
+.GL "Socket source and target"
+.OL "Socket options"
+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 [ = ]
+.BR 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 [ = ]
+.BR 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 fwd
+was started with root privileges. However, it still works if
+.B fwd
+has
+.I dropped
+privileges after initialization (the
+.B \-s
+option). Before dropping privileges,
+.B fwd
+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 fwd
+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 fwd
+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"
+.GL "Socket source and target"
+.OL "Socket options"
+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 fwd
+exits normally (which it will do if it runs out of sources or
+connections, or if
+.B fwd
+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 fwd
+program responds to various signals when it's running. If it receives
+.B SIGTERM
+or
+.BR SIGINT ,
+.B fwd
+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 fwd
+does not re-enable the signal. You'll have to send
+.B SIGTERM
+in that case.) If
+.B fwd
+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 fwd
+on its command line using the
+.B \-f
+option, a
+.B SIGHUP
+signal may be sent to instruct
+.B fwd
+to reload its configuration. Any existing connections are allowed to
+run their course. If no such configuration files are available,
+.B fwd
+just logs a message about the signal and continues.
+.
+.\"--------------------------------------------------------------------------
+.SH "GRAMMAR SUMMARY"
+.
+@@@ grammar
+.\"--------------------------------------------------------------------------
+.SH "OPTION SUMMARY"
+.
+@@@ option
+.\"--------------------------------------------------------------------------
+.SH "BUGS"
+.
+The syntax for IP addresses and filenames is nasty.
+.PP
+IPv6 is not supported yet. Because of
+.BR fwd '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@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blobdiff