X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/blobdiff_plain/d1c182e7ea23547f2da0f621248fae25b8080af9..ad7fbf45c5bba1502237bd4665b0296ce0150734:/fw.1

diff --git a/fw.1 b/fw.1
index c36a6f1..d1f42cd 100644
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: fw.1,v 1.12 2001/02/23 09:11:29 mdw Exp $
+.\" $Id: fw.1,v 1.18 2003/11/29 23:03:19 mdw Exp $
 .\"
 .\" Manual page for fw
 .\"
@@ -28,6 +28,24 @@
 .\" ---- Revision history ---------------------------------------------------
 .\" 
 .\" $Log: fw.1,v $
+.\" Revision 1.18  2003/11/29 23:03:19  mdw
+.\" Little formatting fixes.
+.\"
+.\" Revision 1.17  2003/11/29 20:36:07  mdw
+.\" Privileged outgoing connections.
+.\"
+.\" 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.
 .\"
@@ -433,7 +451,7 @@ The syntax for qualifying options is like this:
 .br
 	|
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
 	|
@@ -583,7 +601,7 @@ sources and targets is like this:
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -740,7 +758,7 @@ exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
@@ -779,6 +797,15 @@ otherwise the file named by the first argument
 .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
@@ -946,7 +973,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -954,7 +981,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -991,6 +1018,16 @@ the
 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
@@ -1033,7 +1070,7 @@ source and target addresses have the following syntax:
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .GE
@@ -1049,11 +1086,23 @@ The
 .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 [ /
-.IR address ]
+.IR addr ]
 .OD
 Adds an entry to the source's access control list.  If only one
 .I address
@@ -1066,6 +1115,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
+.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.
@@ -1126,8 +1225,9 @@ from file stdin, stdout to unix:/tmp/fortunes
 To emulate
 .BR cat (1):
 .VS
-from stdin, null to null, stdout
+from file stdin, null to file null, stdout
 .VE
+.sp -1 \" undo final space
 .
 .\"--------------------------------------------------------------------------
 .SH "SIGNAL HANDLING"
@@ -1170,7 +1270,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.
-.PP
 .
 .\"--------------------------------------------------------------------------
 .SH "GRAMMAR SUMMARY"
@@ -1224,7 +1323,7 @@ just logs a message about the signal and continues.
 .br
 	|
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
 	|
@@ -1249,7 +1348,7 @@ just logs a message about the signal and continues.
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -1310,7 +1409,7 @@ exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
@@ -1350,7 +1449,7 @@ exec
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1358,7 +1457,7 @@ exec
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1385,7 +1484,7 @@ exec
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .PP
@@ -1466,15 +1565,36 @@ exec
 .IR number | \c
 .BR unlimited | one-shot
 .br
+.B socket.listen
+.RB [ = ]
+.I number
+.br
 .B socket.logging
 .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 [ /
-.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. *
 .