+++ /dev/null
-.\" -*-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@distorted.org.uk>
-.
-.\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blobdiff