.\" -*-nroff-*-
.\"
-.\" $Id: fw.1,v 1.6 1999/10/10 16:46:29 mdw Exp $
+.\" $Id: fw.1,v 1.9 2000/03/23 00:37:33 mdw Exp $
.\"
.\" Manual page for fw
.\"
.\" ---- Revision history ---------------------------------------------------
.\"
.\" $Log: fw.1,v $
+.\" 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.
+.\"
+.\" Revision 1.7 1999/10/22 22:45:15 mdw
+.\" Describe new socket connection options.
+.\"
.\" Revision 1.6 1999/10/10 16:46:29 mdw
.\" Include grammar and options references at the end of the manual.
.\"
.SH SYNOPSIS
.
.B fw
-.RB [ \-dq ]
+.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 .
Forks into the background after reading the configuration and
initializing properly.
.TP
-.B "-q, \-\-quiet"
+.B "\-l, \-\-syslog, \-\-log"
+Emit logging information to the system log, rather than standard error.
+.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
.OS "Socket options"
.B socket.conn
.RB [ = ]
-.I number
+.IR number | \c
+.BR unlimited | one-shot
.OD
-Limits the number of simultaneous connections to this socket to the
+Controls the behaviour of the source when it receives connections. A
.I number
-given. The default is 256.
+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.logging
.SS "Socket options"
.B socket.conn
.RB [ = ]
-.I number
+.IR number | \c
+.BR unlimited | one-shot
.br
.B socket.logging
.RB [ = ]
.
The syntax for IP addresses and filenames is nasty.
.PP
-IPv6 is not supported yet. It's probably not a major piece of work to
+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