Correctly cast uid and gid sentinel values.

[fwd] / fw.1

diff --git a/fw.1 b/fw.1
index df52079..140f0f5 100644 (file)
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
 .\" -*-nroff-*-
 .\"

-.\" $Id: fw.1,v 1.9 2000/03/23 00:37:33 mdw Exp $
+.\" $Id: fw.1,v 1.14 2002/02/23 00:05:12 mdw Exp $

 .\"
 .\" Manual page for fw
 .\"
 .\"
 .\" Manual page for fw
 .\"


@@ -28,6 +28,21 @@
 .\" ---- Revision history ---------------------------------------------------
 .\" 
 .\" $Log: fw.1,v $
 .\" ---- Revision history ---------------------------------------------------
 .\" 
 .\" $Log: fw.1,v $

+.\" 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.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 +134,7 @@
 .
 .\"--------------------------------------------------------------------------
 .
 .
 .\"--------------------------------------------------------------------------
 .

-.TH fw 1 "1 July 1999" fw
+.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"

 .
 .\"--------------------------------------------------------------------------
 .SH NAME
 .
 .\"--------------------------------------------------------------------------
 .SH NAME


@@ -270,8 +285,8 @@ are self-delimiting.  Note that while some characters, e.g.,
 .RB ` [ '
 and
 .RB ` ; ',
 .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
 .TP
 .I "whitespace characters"
 Whitespace characters separate words but are otherwise ignored.  All


@@ -401,8 +416,8 @@ on the
 A global option, outside of a
 .I fw-stmt
 has no context unless it is explicitly qualified, and affects global
 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
 has the context of the type of source or target to which it is applied,
 and affects only that source or target.
 .PP


@@ -424,7 +439,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
        |


@@ -445,7 +460,7 @@ exec.rlimit {
   cpu = 60;
 }
 .VE
   cpu = 60;
 }
 .VE

-is equivalent to
+means the same as

 .VS
 exec.rlimit.core = 0;
 exec.rlimit.cpu = 0;
 .VS
 exec.rlimit.core = 0;
 exec.rlimit.cpu = 0;


@@ -574,7 +589,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 ]


@@ -731,7 +746,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


@@ -818,13 +833,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
 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
 .OE
 .OS "Exec options"
 .B exec.user


@@ -940,7 +952,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 [ : ]]


@@ -948,7 +960,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 [ : ]]


@@ -985,6 +997,16 @@ the
 option is not recommended.
 .OE
 .OS "Socket options"
 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
 .B socket.logging
 .RB [ = ]
 .BR yes | no


@@ -1027,7 +1049,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


@@ -1100,7 +1122,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
 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
 .SH "EXAMPLES"
 To forward the local port 25 to a main mail server:
 .VS


@@ -1122,6 +1146,49 @@ from stdin, null to null, stdout
 .VE
 .
 .\"--------------------------------------------------------------------------
 .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"
 .SH "GRAMMAR SUMMARY"
 .
 .SS "Basic syntax"


@@ -1173,7 +1240,7 @@ from stdin, null to null, stdout
 .br
        |
 .I prefix
 .br
        |
 .I prefix

-.B .
+.B .\&

 .I q-option
 .br
        |
 .I q-option
 .br
        |


@@ -1198,7 +1265,7 @@ from stdin, null to null, stdout
 .I file
 ::=
 .B file
 .I file
 ::=
 .B file

-.RB  [ . ]
+.RB  [ .\& ]

 .I fspec
 .RB [ ,
 .IR fspec ]
 .I fspec
 .RB [ ,
 .IR fspec ]


@@ -1259,7 +1326,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


@@ -1299,7 +1366,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 [ : ]]


@@ -1307,7 +1374,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 [ : ]]


@@ -1334,7 +1401,7 @@ exec
 .br
 .I addr-elt
 ::=
 .br
 .I addr-elt
 ::=

-.B .
+.B .\&

 |
 .I word
 .PP
 |
 .I word
 .PP


@@ -1415,6 +1482,10 @@ exec
 .IR number | \c
 .BR unlimited | one-shot
 .br
 .IR number | \c
 .BR unlimited | one-shot
 .br

+.B socket.listen
+.RB [ = ]
+.I number
+.br

 .B socket.logging
 .RB [ = ]
 .BR yes | no
 .B socket.logging
 .RB [ = ]
 .BR yes | no


@@ -1442,6 +1513,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.
 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"
 .
 .\"--------------------------------------------------------------------------
 .SH "AUTHOR"