.\" -*-nroff-*-
.\"
-.\" $Id: fw.1,v 1.16 2003/11/25 14:46:50 mdw Exp $
+.\" $Id$
.\"
.\" Manual page for fw
.\"
.\" along with `fw'; if not, write to the Free Software Foundation,
.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
.
-.\" ---- Revision history ---------------------------------------------------
-.\"
-.\" $Log: fw.1,v $
-.\" Revision 1.16 2003/11/25 14:46:50 mdw
-.\" Update docco for new options.
-.\"
-.\" Revision 1.15 2003/01/24 20:13:04 mdw
-.\" Fix bogus examples. Explain quoting rules for `exec' endpoints.
-.\"
-.\" 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.
-.\"
-.\" 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.
-.\"
-.\" Revision 1.5 1999/09/26 18:18:05 mdw
-.\" Remove a fixed bug from the list. Fix some nasty formatting
-.\" misfeatures.
-.\"
-.\" Revision 1.4 1999/08/19 18:32:48 mdw
-.\" Improve lexical analysis. In particular, `chmod' patterns don't have to
-.\" be quoted any more.
-.\"
-.\" Revision 1.3 1999/07/30 06:49:00 mdw
-.\" Minor tidying and typo correction.
-.\"
-.\" Revision 1.2 1999/07/26 23:31:04 mdw
-.\" Document lots of new features and syntax.
-.\"
-.
.\"----- Various bits of fancy styling --------------------------------------
.
.\" --- Indented paragraphs with right-aligned tags ---
.SH SYNOPSIS
.
.B fw
-.RB [ \-dlq ]
+.RB [ \-dlpq ]
.RB [ \-f
.IR file ]
.RB [ \-s
.B "\-l, \-\-syslog, \-\-log"
Emit logging information to the system log, rather than standard error.
.TP
+.B "\-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
.br
.I name-spec
::=
-.RB [[ : ] file [ : ]]
+.RB [[ : ] name [ : ]]
.I file-name
.br
.I file-name
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.
.VS
from file stdin, null to file null, stdout
.VE
+.sp -1 \" undo final space
.
.\"--------------------------------------------------------------------------
.SH "SIGNAL HANDLING"
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"
.br
.I name-spec
::=
-.RB [[ : ] file [ : ]]
+.RB [[ : ] name [ : ]]
.I file-name
.br
.I file-name
.RB [ = ]
.BR any | \c
.I addr
+.br
+.B socket.inet.dest.priv-port
+.RB [=]
+.BR yes | no
.PP
.BR socket.unix.fattr. *
.