.\" -*-nroff-*-
.\"
-.\" $Id: fw.1,v 1.8 1999/12/22 15:44:43 mdw Exp $
+.\" $Id: fw.1,v 1.10 2001/02/03 20:30:03 mdw Exp $
.\"
.\" Manual page for fw
.\"
.\" ---- Revision history ---------------------------------------------------
.\"
.\" $Log: fw.1,v $
+.\" 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.
.\"
.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
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
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"