Fix up the help message.
[fwd] / fw.1
diff --git a/fw.1 b/fw.1
index 3376b60..ebb1b66 100644 (file)
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
 .\" -*-nroff-*-
 .\"
-.\" $Id: fw.1,v 1.13 2002/02/22 23:45:01 mdw Exp $
+.\" $Id$
 .\"
 .\" Manual page for fw
 .\"
 .\"
 .\" 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.
 .
 .\" 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.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 ---
 .\"----- Various bits of fancy styling --------------------------------------
 .
 .\" --- Indented paragraphs with right-aligned tags ---
@@ -142,7 +99,7 @@ fw \- port forwarder
 .SH SYNOPSIS
 .
 .B fw
 .SH SYNOPSIS
 .
 .B fw
-.RB [ \-dlq ]
+.RB [ \-dlpq ]
 .RB [ \-f
 .IR file ]
 .RB [ \-s
 .RB [ \-f
 .IR file ]
 .RB [ \-s
@@ -218,6 +175,15 @@ initializing properly.
 .B "\-l, \-\-syslog, \-\-log"
 Emit logging information to the system log, rather than standard error.
 .TP
 .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
 .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
@@ -436,7 +402,7 @@ The syntax for qualifying options is like this:
 .br
        |
 .I prefix
 .br
        |
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
        |
 .I q-option
 .br
        |
@@ -586,7 +552,7 @@ sources and targets is like this:
 .I file
 ::=
 .B file
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -607,7 +573,7 @@ sources and targets is like this:
 .br
 .I name-spec
 ::=
 .br
 .I name-spec
 ::=
-.RB [[ : ] file [ : ]]
+.RB [[ : ] name [ : ]]
 .I file-name
 .br
 .I file-name
 .I file-name
 .br
 .I file-name
@@ -743,7 +709,7 @@ exec
 .I exec
 ::=
 .BR exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
 .I cmd-spec
 .br
 .I cmd-spec
@@ -782,6 +748,15 @@ otherwise the file named by the first argument
 .RI ( argv0 )
 is used.
 .PP
 .RI ( argv0 )
 is used.
 .PP
+Note that the shell command or program name string must, if present,
+have any delimiter characters (including
+.RB ` / '
+and 
+.RB ` . ')
+quoted; this is not required in the
+.RB ` [ '-enclosed
+argument list.
+.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
 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
@@ -949,7 +924,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-source
 ::=
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -957,7 +932,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-target
 ::=
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1046,7 +1021,7 @@ source and target addresses have the following syntax:
 .br
 .I addr-elt
 ::=
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .GE
 |
 .I word
 .GE
@@ -1062,11 +1037,23 @@ The
 .B inet
 source address accepts the following options:
 .OS "Socket options"
 .B inet
 source address accepts the following options:
 .OS "Socket options"
-.BR socket.inet. [ allow | deny ]
-.RB [ from ]
-.I address
+.B socket.inet.source.addr
+.RB [ = ]
+.RR any | \c
+.I addr
+.OD
+Specify the IP address on which to listen for incoming connections.  The
+default is
+.BR any ,
+which means to listen on all addresses, though it may be useful to
+specify this explicitly, if the global setting is different.
+.OE
+.OS "Socket options"
+.BR socket.inet.source. [ allow | deny ]
+.RB [ host ]
+.I addr
 .RB [ /
 .RB [ /
-.IR address ]
+.IR addr ]
 .OD
 Adds an entry to the source's access control list.  If only one
 .I address
 .OD
 Adds an entry to the source's access control list.  If only one
 .I address
@@ -1079,6 +1066,56 @@ and
 mean the same), and the entry applies to any address which, when masked
 by the netmask, is equal to the masked network address.
 .OE
 mean the same), and the entry applies to any address which, when masked
 by the netmask, is equal to the masked network address.
 .OE
+.OS "Socket options"
+.BR socket.inet.source. [ allow | deny ]
+.B priv-port
+.OD
+Accept or reject connections from low-numbered `privileged' ports, in
+the range 0--1023.
+.OE
+.OS "Socket options"
+.B socket.inet.dest.addr
+.RB [ = ]
+.RR any | \c
+.I addr
+.OD
+Specify the IP address to bind the local socket to when making an
+outbound connection.  The default is
+.BR any ,
+which means to use whichever address the kernel thinks is most
+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.
 .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.
@@ -1139,8 +1176,9 @@ from file stdin, stdout to unix:/tmp/fortunes
 To emulate
 .BR cat (1):
 .VS
 To emulate
 .BR cat (1):
 .VS
-from stdin, null to null, stdout
+from file stdin, null to file null, stdout
 .VE
 .VE
+.sp -1 \" undo final space
 .
 .\"--------------------------------------------------------------------------
 .SH "SIGNAL HANDLING"
 .
 .\"--------------------------------------------------------------------------
 .SH "SIGNAL HANDLING"
@@ -1183,7 +1221,6 @@ 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.
 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"
 .
 .\"--------------------------------------------------------------------------
 .SH "GRAMMAR SUMMARY"
@@ -1237,7 +1274,7 @@ just logs a message about the signal and continues.
 .br
        |
 .I prefix
 .br
        |
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
        |
 .I q-option
 .br
        |
@@ -1262,7 +1299,7 @@ just logs a message about the signal and continues.
 .I file
 ::=
 .B file
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -1283,7 +1320,7 @@ just logs a message about the signal and continues.
 .br
 .I name-spec
 ::=
 .br
 .I name-spec
 ::=
-.RB [[ : ] file [ : ]]
+.RB [[ : ] name [ : ]]
 .I file-name
 .br
 .I file-name
 .I file-name
 .br
 .I file-name
@@ -1323,7 +1360,7 @@ exec
 .I exec
 ::=
 .BR exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
 .I cmd-spec
 .br
 .I cmd-spec
@@ -1363,7 +1400,7 @@ exec
 .br
 .I socket-source
 ::=
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1371,7 +1408,7 @@ exec
 .br
 .I socket-target
 ::=
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1398,7 +1435,7 @@ exec
 .br
 .I addr-elt
 ::=
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .PP
 |
 .I word
 .PP
@@ -1487,11 +1524,28 @@ exec
 .RB [ = ]
 .BR yes | no
 .PP
 .RB [ = ]
 .BR yes | no
 .PP
-.BR socket.inet. [ allow | deny ]
-.RB [ from ]
-.I address
+.BR socket.inet.source. [ allow | deny ]
+.RB [ host ]
+.I addr
 .RB [ /
 .RB [ /
-.IR address ]
+.IR addr ]
+.br
+.BR socket.inet.source. [ allow | deny ]
+.B priv-port
+.br
+.B socket.inet.source.addr
+.RB [ = ]
+.BR any | \c
+.I addr
+.br
+.B socket.inet.dest.addr
+.RB [ = ]
+.BR any | \c
+.I addr
+.br
+.B socket.inet.dest.priv-port
+.RB [=]
+.BR yes | no
 .PP
 .BR socket.unix.fattr. *
 .
 .PP
 .BR socket.unix.fattr. *
 .