.\" -*-nroff-*-
.\"
-.\" Manual page for fw
+.\" Manual page for fwd
.\"
.\" (c) 1999 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
-.\" This file is part of the `fw' port forwarder.
+.\" This file is part of the `fwd' port forwarder.
.\"
-.\" `fw' is free software; you can redistribute it and/or modify
+.\" `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.
.\"
-.\" `fw' is distributed in the hope that it will be useful,
+.\" `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 `fw'; if not, write to the Free Software Foundation,
+.\" 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 --------------------------------------
.
.\"--------------------------------------------------------------------------
.
-.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
+.TH fwd 1 "1 July 1999" "Straylight/Edgeware" "fwd port forwarder"
.
.\"--------------------------------------------------------------------------
.SH NAME
.
-fw \- port forwarder
+fwd \- port forwarder
.
.\"--------------------------------------------------------------------------
.SH SYNOPSIS
.
-.B fw
+.B fwd
.RB [ \-dlq ]
.RB [ \-p
.IR file ]
.SH "DESCRIPTION"
.
The
-.B fw
+.B fwd
program is a simple port forwarder. It supports a number of features
the author hasn't found in similar programs:
.TP
Unix domain sockets, though. (Yet.)
.SS "Command line options"
The
-.B fw
+.B fwd
program understands a few simple command line options:
.TP
.B "\-h, \-\-help"
.TP
.BI "\-p, \-\-pidfile=" file
Write
-.BR fw 's
+.BR fwd 's
process-id to
.I file
during start-up. If
.SH "CONFIGURATION LANGUAGE"
.
The
-.B fw
+.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.
::=
.I option-stmt
|
-.I fw-stmt
+.I fwd-stmt
.br
-.I fw-stmt
+.I fwd-stmt
::=
-.B fw
+.B fwd
.I source
.I options
.RB [ to | \-> ]
.I option-seq
.GE
If you prefer, the keyword
-.RB ` fw '
+.RB ` fwd '
may be spelt
-.RB ` forward '
+.RB ` fwd ',
+.RB ` forward ',
or
.RB ` from '.
All are equivalent.
destination server is the target.
.PP
Essentially, all
-.B fw
+.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
.IR transient :
they set up one connection and then disappear. If all the sources
defined are transient, then
-.B fw
+.B fwd
will quit when no more active sources remain and all connections have
terminated.
.PP
The
-.B fw
+.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.
.
.SS "Options structure"
Most of the objects that
-.B fw
+.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
on the
.IR context .
A global option, outside of a
-.I fw-stmt
+.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 fw-stmt ,
+.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
.BR exec.logging ,
which have separate defaults, and which one you actually get depends on
the exact implementation of
-.BR fw 's
+.BR fwd 's
option parser. (Currently this would resolve to
.BR exec.logging ,
although this may change in a later version.)
.OE
.PP
Under no circumstances will
-.B fw
+.B fwd
create a file through a `dangling' symbolic link.
.
.SS "The `exec' source and target types"
.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
+.B fwd
and logged.
.PP
The
.OD
Make a privileged connection (i.e., from a low-numbered port) to the
target. This only works if
-.B fw
+.B fwd
was started with root privileges. However, it still works if
-.B fw
+.B fwd
has
.I dropped
privileges after initialization (the
.B \-s
option). Before dropping privileges,
-.B fw
+.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 fw
+.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 fw
+.B fwd
to make privileged connections to different peer addresses later by
changing configuration files and sending the daemon a
.BR SIGHUP .
.OE
.PP
Sockets are removed if
-.B fw
+.B fwd
exits normally (which it will do if it runs out of sources or
connections, or if
-.B fw
+.B fwd
shuts down in a clean way).
.SH "EXAMPLES"
To forward the local port 25 to a main mail server:
.SH "SIGNAL HANDLING"
.
The
-.B fw
+.B fwd
program responds to various signals when it's running. If it receives
.B SIGTERM
or
.BR SIGINT ,
-.B fw
+.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 fw
+.B fwd
does not re-enable the signal. You'll have to send
.B SIGTERM
in that case.) If
-.B fw
+.B fwd
receives
.BR SIGQUIT ,
it performs an
.PP
Finally, if any configuration files (other than standard input) were
provided to
-.B fw
+.B fwd
on its command line using the
.B \-f
option, a
.B SIGHUP
signal may be sent to instruct
-.B fw
+.B fwd
to reload its configuration. Any existing connections are allowed to
run their course. If no such configuration files are available,
-.B fw
+.B fwd
just logs a message about the signal and continues.
.
.\"--------------------------------------------------------------------------
The syntax for IP addresses and filenames is nasty.
.PP
IPv6 is not supported yet. Because of
-.BR fw 's
+.BR fwd 's
socket address architecture, it's probably not a major piece of work to
add.
.PP
~mdw / fwd / blobdiff