Little formatting fixes.

[fwd] / fw.1

diff --git a/fw.1 b/fw.1
index 885d5b97242b58f7c0434351a99e9284dce44b03..d1f42cd5b18db373d21a95669b4913b2be493aab 100644 (file)
--- a/fw.1
+++ b/fw.1
@@ -1,6 +1,6 @@
 .\" -*-nroff-*-
 .\"
 .\" -*-nroff-*-
 .\"

-.\" $Id: fw.1,v 1.6 1999/10/10 16:46:29 mdw Exp $
+.\" $Id: fw.1,v 1.18 2003/11/29 23:03:19 mdw Exp $

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


@@ -28,6 +28,43 @@
 .\" ---- Revision history ---------------------------------------------------
 .\" 
 .\" $Log: fw.1,v $
 .\" ---- 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.
+.\"
+.\" 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.6  1999/10/10 16:46:29  mdw
 .\" Include grammar and options references at the end of the manual.
 .\"


@@ -109,7 +146,7 @@
 .
 .\"--------------------------------------------------------------------------
 .
 .
 .\"--------------------------------------------------------------------------
 .

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

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


@@ -120,9 +157,13 @@ fw \- port forwarder
 .SH SYNOPSIS
 .
 .B fw
 .SH SYNOPSIS
 .
 .B fw

-.RB [ \-dq ]
+.RB [ \-dlq ]

 .RB [ \-f
 .IR file ]
 .RB [ \-f
 .IR file ]

+.RB [ \-s
+.IR user ]
+.RB [ \-g
+.IR group ]

 .IR config-stmt ...
 .
 .\"--------------------------------------------------------------------------
 .IR config-stmt ...
 .
 .\"--------------------------------------------------------------------------


@@ -169,6 +210,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 "\-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 .
 .BI "\-f, \-\-file=" file
 Read configuration information from
 .IR file .


@@ -181,10 +230,27 @@ configuration file statement.
 Forks into the background after reading the configuration and
 initializing properly.
 .TP
 Forks into the background after reading the configuration and
 initializing properly.
 .TP

-.B "-q, \-\-quiet"
+.B "\-l, \-\-syslog, \-\-log"
+Emit logging information to the system log, rather than standard error.
+.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
 it when debugging.
 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
 .PP
 Any further command line arguments are interpreted as configuration
 lines to be read.  Configuration supplied in command line arguments has


@@ -231,8 +297,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


@@ -362,8 +428,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


@@ -385,7 +451,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
        |


@@ -406,7 +472,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;


@@ -535,7 +601,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 ]


@@ -692,7 +758,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


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


@@ -779,13 +854,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


@@ -901,7 +973,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 [ : ]]


@@ -909,7 +981,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 [ : ]]


@@ -927,11 +999,33 @@ options provided are:
 .OS "Socket options"
 .B socket.conn
 .RB [ = ]
 .OS "Socket options"
 .B socket.conn
 .RB [ = ]

-.I number
+.IR number | \c
+.BR unlimited | one-shot

 .OD
 .OD

-Limits the number of simultaneous connections to this socket to the
+Controls the behaviour of the source when it receives connections.  A
+.I number
+limits the number of simultaneous connections.  The value
+.B unlimited
+(or
+.BR infinite )
+removes any limit on the number of connections possible.  The value
+.B one-shot
+will remove the socket source after a single successful connection.
+(Connections refused by access control systems don't count here.)
+The default is to apply a limit of 256 concurrent connections.  Use of
+the
+.B unlimited
+option is not recommended.
+.OE
+.OS "Socket options"
+.B socket.listen
+.RB [ = ]

 .I number
 .I number

-given.  The default is 256.
+.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
 .OE
 .OS "Socket options"
 .B socket.logging


@@ -976,7 +1070,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


@@ -992,11 +1086,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


@@ -1009,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
 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.


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


@@ -1067,8 +1225,51 @@ 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"
+.
+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.

 .
 .\"--------------------------------------------------------------------------
 .SH "GRAMMAR SUMMARY"
 .
 .\"--------------------------------------------------------------------------
 .SH "GRAMMAR SUMMARY"


@@ -1122,7 +1323,7 @@ from stdin, null to null, stdout
 .br
        |
 .I prefix
 .br
        |
 .I prefix

-.B .
+.B .\&

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


@@ -1147,7 +1348,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 ]


@@ -1208,7 +1409,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


@@ -1248,7 +1449,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 [ : ]]


@@ -1256,7 +1457,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 [ : ]]


@@ -1283,7 +1484,7 @@ exec
 .br
 .I addr-elt
 ::=
 .br
 .I addr-elt
 ::=

-.B .
+.B .\&

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


@@ -1361,17 +1562,39 @@ exec
 .SS "Socket options"
 .B socket.conn
 .RB [ = ]
 .SS "Socket options"
 .B socket.conn
 .RB [ = ]

+.IR number | \c
+.BR unlimited | one-shot
+.br
+.B socket.listen
+.RB [ = ]

 .I number
 .br
 .B socket.logging
 .RB [ = ]
 .BR yes | no
 .PP
 .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 [ /
 .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. *
 .


@@ -1380,7 +1603,9 @@ exec
 .
 The syntax for IP addresses and filenames is nasty.
 .PP
 .
 The syntax for IP addresses and filenames is nasty.
 .PP

-IPv6 is not supported yet.  It's probably not a major piece of work to
+IPv6 is not supported yet.  Because of
+.BR fw 's
+socket address architecture, it's probably not a major piece of work to

 add.
 .PP
 Please inform me of any security problems you think you've identified in
 add.
 .PP
 Please inform me of any security problems you think you've identified in


@@ -1388,6 +1613,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"