Add option to change the listen(2) parameter.

[fwd] / fw.1

diff --git a/fw.1 b/fw.1
index df52079..3376b60 100644 (file)
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
-.\" $Id: fw.1,v 1.9 2000/03/23 00:37:33 mdw Exp $
+.\" $Id: fw.1,v 1.13 2002/02/22 23:45:01 mdw Exp $
 .\"
 .\" Manual page for fw
 .\"
@@ -28,6 +28,18 @@
 .\" ---- 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.
@@ -119,7 +131,7 @@
 .
 .\"--------------------------------------------------------------------------
 .
-.TH fw 1 "1 July 1999" fw
+.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
 .
 .\"--------------------------------------------------------------------------
 .SH NAME
@@ -270,8 +282,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
@@ -401,8 +413,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
@@ -445,7 +457,7 @@ exec.rlimit {
   cpu = 60;
 }
 .VE
-is equivalent to
+means the same as
 .VS
 exec.rlimit.core = 0;
 exec.rlimit.cpu = 0;
@@ -818,13 +830,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
@@ -985,6 +994,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
@@ -1100,7 +1119,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
@@ -1122,6 +1143,49 @@ from stdin, null to 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"
@@ -1415,6 +1479,10 @@ exec
 .IR number | \c
 .BR unlimited | one-shot
 .br
+.B socket.listen
+.RB [ = ]
+.I number
+.br
 .B socket.logging
 .RB [ = ]
 .BR yes | no
@@ -1442,6 +1510,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"