X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/blobdiff_plain/723210e69817a256f32170e2bd28012c6bccca34..f65809f707319adc063bc77a68547bc82af3b0e2:/fw.1 diff --git a/fw.1 b/fw.1 index 7d8de68..51dc460 100644 --- a/fw.1 +++ b/fw.1 @@ -1,6 +1,6 @@ .\" -*-nroff-*- .\" -.\" $Id: fw.1,v 1.11 2001/02/05 19:47:11 mdw Exp $ +.\" $Id$ .\" .\" Manual page for fw .\" @@ -25,43 +25,6 @@ .\" along with `fw'; if not, write to the Free Software Foundation, .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. . -.\" ---- Revision history --------------------------------------------------- -.\" -.\" $Log: fw.1,v $ -.\" 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.5 1999/09/26 18:18:05 mdw -.\" Remove a fixed bug from the list. Fix some nasty formatting -.\" misfeatures. -.\" -.\" Revision 1.4 1999/08/19 18:32:48 mdw -.\" Improve lexical analysis. In particular, `chmod' patterns don't have to -.\" be quoted any more. -.\" -.\" Revision 1.3 1999/07/30 06:49:00 mdw -.\" Minor tidying and typo correction. -.\" -.\" Revision 1.2 1999/07/26 23:31:04 mdw -.\" Document lots of new features and syntax. -.\" -. .\"----- Various bits of fancy styling -------------------------------------- . .\" --- Indented paragraphs with right-aligned tags --- @@ -125,7 +88,7 @@ . .\"-------------------------------------------------------------------------- . -.TH fw 1 "1 July 1999" fw +.TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder" . .\"-------------------------------------------------------------------------- .SH NAME @@ -137,6 +100,8 @@ fw \- port forwarder . .B fw .RB [ \-dlq ] +.RB [ \-p +.IR file ] .RB [ \-f .IR file ] .RB [ \-s @@ -212,6 +177,15 @@ initializing properly. .B "\-l, \-\-syslog, \-\-log" Emit logging information to the system log, rather than standard error. .TP +.BI "\-p, \-\-pidfile=" file +Write +.BR fw 's +process-id to +.I file +during start-up. If +.B \-d +is given too, then the process-id is written after forking (obviously). +.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 @@ -430,7 +404,7 @@ The syntax for qualifying options is like this: .br | .I prefix -.B . +.B .\& .I q-option .br | @@ -580,7 +554,7 @@ sources and targets is like this: .I file ::= .B file -.RB [ . ] +.RB [ .\& ] .I fspec .RB [ , .IR fspec ] @@ -601,7 +575,7 @@ sources and targets is like this: .br .I name-spec ::= -.RB [[ : ] file [ : ]] +.RB [[ : ] name [ : ]] .I file-name .br .I file-name @@ -737,7 +711,7 @@ exec .I exec ::= .BR exec -.RB [ . ] +.RB [ .\& ] .I cmd-spec .br .I cmd-spec @@ -776,6 +750,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 @@ -943,7 +926,7 @@ The syntax for socket sources and targets is: .br .I socket-source ::= -.RB [ socket [ . ]] +.RB [ socket [ .\& ]] .RB [[ : ] \c .IR addr-type \c .RB [ : ]] @@ -951,7 +934,7 @@ The syntax for socket sources and targets is: .br .I socket-target ::= -.RB [ socket [ . ]] +.RB [ socket [ .\& ]] .RB [[ : ] \c .IR addr-type \c .RB [ : ]] @@ -988,6 +971,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 @@ -1030,7 +1023,7 @@ source and target addresses have the following syntax: .br .I addr-elt ::= -.B . +.B .\& | .I word .GE @@ -1046,11 +1039,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 @@ -1063,6 +1068,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. @@ -1123,8 +1178,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" @@ -1167,7 +1223,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" @@ -1221,7 +1276,7 @@ just logs a message about the signal and continues. .br | .I prefix -.B . +.B .\& .I q-option .br | @@ -1246,7 +1301,7 @@ just logs a message about the signal and continues. .I file ::= .B file -.RB [ . ] +.RB [ .\& ] .I fspec .RB [ , .IR fspec ] @@ -1267,7 +1322,7 @@ just logs a message about the signal and continues. .br .I name-spec ::= -.RB [[ : ] file [ : ]] +.RB [[ : ] name [ : ]] .I file-name .br .I file-name @@ -1307,7 +1362,7 @@ exec .I exec ::= .BR exec -.RB [ . ] +.RB [ .\& ] .I cmd-spec .br .I cmd-spec @@ -1347,7 +1402,7 @@ exec .br .I socket-source ::= -.RB [ socket [ . ]] +.RB [ socket [ .\& ]] .RB [[ : ] \c .IR addr-type \c .RB [ : ]] @@ -1355,7 +1410,7 @@ exec .br .I socket-target ::= -.RB [ socket [ . ]] +.RB [ socket [ .\& ]] .RB [[ : ] \c .IR addr-type \c .RB [ : ]] @@ -1382,7 +1437,7 @@ exec .br .I addr-elt ::= -.B . +.B .\& | .I word .PP @@ -1463,15 +1518,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. * . @@ -1496,6 +1572,6 @@ The program is too complicated, and this manual page is too long. .\"-------------------------------------------------------------------------- .SH "AUTHOR" . -Mark Wooding, +Mark Wooding, . .\"----- That's all, folks --------------------------------------------------