.\" -*-nroff-*-
.\"
-.\" $Id: fw.1,v 1.8 1999/12/22 15:44:43 mdw Exp $
+.\" $Id: fw.1,v 1.14 2002/02/23 00:05:12 mdw Exp $
.\"
.\" Manual page for fw
.\"
.\" ---- Revision history ---------------------------------------------------
.\"
.\" $Log: fw.1,v $
+.\" Revision 1.14 2002/02/23 00:05:12 mdw
+.\" Fix spacing around full stops (at last!).
+.\"
+.\" Revision 1.13 2002/02/22 23:45:01 mdw
+.\" Add option to change the listen(2) parameter.
+.\"
+.\" Revision 1.12 2001/02/23 09:11:29 mdw
+.\" Update manual style.
+.\"
+.\" Revision 1.11 2001/02/05 19:47:11 mdw
+.\" Minor fixings to wording.
+.\"
+.\" Revision 1.10 2001/02/03 20:30:03 mdw
+.\" Support re-reading config files on SIGHUP.
+.\"
+.\" Revision 1.9 2000/03/23 00:37:33 mdw
+.\" Add option to change user and group after initialization. Naughtily
+.\" reassign short equivalents of --grammar and --options.
+.\"
.\" Revision 1.8 1999/12/22 15:44:43 mdw
.\" Fix some errors, and document new option.
.\"
.
.\"--------------------------------------------------------------------------
.
-.TH fw 1 "1 July 1999" fw
+.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
.
.\"--------------------------------------------------------------------------
.SH NAME
.RB [ \-dlq ]
.RB [ \-f
.IR file ]
+.RB [ \-s
+.IR user ]
+.RB [ \-g
+.IR group ]
.IR config-stmt ...
.
.\"--------------------------------------------------------------------------
.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 .
.B "\-l, \-\-syslog, \-\-log"
Emit logging information to the system log, rather than standard error.
.TP
-.B "-q, \-\-quiet"
+.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
.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.
+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
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
+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
.br
|
.I prefix
-.B .
+.B .\&
.I q-option
.br
|
cpu = 60;
}
.VE
-is equivalent to
+means the same as
.VS
exec.rlimit.core = 0;
exec.rlimit.cpu = 0;
.I file
::=
.B file
-.RB [ . ]
+.RB [ .\& ]
.I fspec
.RB [ ,
.IR fspec ]
.I exec
::=
.BR exec
-.RB [ . ]
+.RB [ .\& ]
.I cmd-spec
.br
.I cmd-spec
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 .
+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
.br
.I socket-source
::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
.RB [[ : ] \c
.IR addr-type \c
.RB [ : ]]
.br
.I socket-target
::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
.RB [[ : ] \c
.IR addr-type \c
.RB [ : ]]
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
.br
.I addr-elt
::=
-.B .
+.B .\&
|
.I word
.GE
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).
+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
.VE
.
.\"--------------------------------------------------------------------------
+.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.
+.PP
+.
+.\"--------------------------------------------------------------------------
.SH "GRAMMAR SUMMARY"
.
.SS "Basic syntax"
.br
|
.I prefix
-.B .
+.B .\&
.I q-option
.br
|
.I file
::=
.B file
-.RB [ . ]
+.RB [ .\& ]
.I fspec
.RB [ ,
.IR fspec ]
.I exec
::=
.BR exec
-.RB [ . ]
+.RB [ .\& ]
.I cmd-spec
.br
.I cmd-spec
.br
.I socket-source
::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
.RB [[ : ] \c
.IR addr-type \c
.RB [ : ]]
.br
.I socket-target
::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
.RB [[ : ] \c
.IR addr-type \c
.RB [ : ]]
.br
.I addr-elt
::=
-.B .
+.B .\&
|
.I word
.PP
.IR number | \c
.BR unlimited | one-shot
.br
+.B socket.listen
+.RB [ = ]
+.I number
+.br
.B socket.logging
.RB [ = ]
.BR yes | no
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"
~mdw / fwd / blobdiff