X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/blobdiff_plain/370e3c1436b0c4732f47ae4303010368d4690ec8..1c2054c7558f523dec9d7c1f243a2ceddd81c781:/fw.1

diff --git a/fw.1 b/fw.1
index 2d23b0d..251aa5a 100644
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: fw.1,v 1.8 1999/12/22 15:44:43 mdw Exp $
+.\" $Id: fw.1,v 1.16 2003/11/25 14:46:50 mdw Exp $
 .\"
 .\" Manual page for fw
 .\"
@@ -28,6 +28,31 @@
 .\" ---- 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.
 .\"
@@ -115,7 +140,7 @@
 .
 .\"--------------------------------------------------------------------------
 .
-.TH fw 1 "1 July 1999" fw
+.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
 .
 .\"--------------------------------------------------------------------------
 .SH NAME
@@ -129,6 +154,10 @@ fw \- port forwarder
 .RB [ \-dlq ]
 .RB [ \-f
 .IR file ]
+.RB [ \-s
+.IR user ]
+.RB [ \-g
+.IR group ]
 .IR config-stmt ...
 .
 .\"--------------------------------------------------------------------------
@@ -175,6 +204,14 @@ Writes the version number to standard output and exits successfully.
 .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 .
@@ -190,10 +227,24 @@ initializing properly.
 .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
@@ -240,8 +291,8 @@ are self-delimiting.  Note that while some characters, e.g.,
 .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
@@ -371,8 +422,8 @@ on the
 A global option, outside of a
 .I fw-stmt
 has no context unless it is explicitly qualified, and affects global
-behaviour.  Local options, applied to a source or target in a
-.I fw-stmt
+behaviour.  A local option, applied to a source or target in a
+.IR fw-stmt ,
 has the context of the type of source or target to which it is applied,
 and affects only that source or target.
 .PP
@@ -394,7 +445,7 @@ The syntax for qualifying options is like this:
 .br
 	|
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
 	|
@@ -415,7 +466,7 @@ exec.rlimit {
   cpu = 60;
 }
 .VE
-is equivalent to
+means the same as
 .VS
 exec.rlimit.core = 0;
 exec.rlimit.cpu = 0;
@@ -544,7 +595,7 @@ sources and targets is like this:
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -701,7 +752,7 @@ exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
@@ -740,6 +791,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
@@ -788,13 +848,10 @@ are accepted in place of
 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
@@ -910,7 +967,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -918,7 +975,7 @@ The syntax for socket sources and targets is:
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -955,6 +1012,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
@@ -997,7 +1064,7 @@ source and target addresses have the following syntax:
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .GE
@@ -1013,11 +1080,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
@@ -1030,6 +1109,26 @@ 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
 .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.
@@ -1070,7 +1169,9 @@ options to control the attributes of the socket file created.
 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
@@ -1088,10 +1189,53 @@ 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
 .
 .\"--------------------------------------------------------------------------
+.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"
@@ -1143,7 +1287,7 @@ from stdin, null to null, stdout
 .br
 	|
 .I prefix
-.B .
+.B .\&
 .I q-option
 .br
 	|
@@ -1168,7 +1312,7 @@ from stdin, null to null, stdout
 .I file
 ::=
 .B file
-.RB  [ . ]
+.RB  [ .\& ]
 .I fspec
 .RB [ ,
 .IR fspec ]
@@ -1229,7 +1373,7 @@ exec
 .I exec
 ::=
 .BR exec
-.RB [ . ]
+.RB [ .\& ]
 .I cmd-spec
 .br
 .I cmd-spec
@@ -1269,7 +1413,7 @@ exec
 .br
 .I socket-source
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1277,7 +1421,7 @@ exec
 .br
 .I socket-target
 ::=
-.RB [ socket [ . ]]
+.RB [ socket [ .\& ]]
 .RB [[ : ] \c
 .IR addr-type \c
 .RB [ : ]]
@@ -1304,7 +1448,7 @@ exec
 .br
 .I addr-elt
 ::=
-.B .
+.B .\&
 |
 .I word
 .PP
@@ -1385,15 +1529,32 @@ 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
 .PP
 .BR socket.unix.fattr. *
 .
@@ -1412,6 +1573,8 @@ this program.  I take security very seriously, and I will fix security
 holes as a matter of priority when I find out about them.  I will be
 annoyed if I have to read about problems on Bugtraq because they weren't
 mailed to me first.
+.PP
+The program is too complicated, and this manual page is too long.
 .
 .\"--------------------------------------------------------------------------
 .SH "AUTHOR"