From 10a454ad0105c6aa60204a9cf34c4b4e1fb6dd0f Mon Sep 17 00:00:00 2001 From: mdw Date: Sat, 3 Jul 1999 13:52:54 +0000 Subject: [PATCH] New manual page. --- fw.1 | 206 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 206 insertions(+) create mode 100644 fw.1 diff --git a/fw.1 b/fw.1 new file mode 100644 index 0000000..6dcb226 --- /dev/null +++ b/fw.1 @@ -0,0 +1,206 @@ +.\" -*-nroff-*- +.ie t .ds o \(bu +.el .ds o o +.de hP +.IP +\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c +.. +.TH fw 1 "1 July 1999" fw +.SH NAME +fw \- port forwarder +.SH SYNOPSIS +.B fw +.RB [ \-db ] +.RB [ \-f +.IR file ] +.IR config-stmt ... +.SH DESCRIPTION +The +.B fw +program is a simple port forwarder. It supports a number of features +the author hasn't found in similar programs: +.TP +.I "Connection logging" +Each connection attempt to the forwarder is logged, giving the time of +the connection, the DNS-resolved hostname (if available), and the user +name resulting from an RFC931 lookup. These lookups are done +asynchronously to the main forwarder's operation. +.TP +.I "Access control" +Each forwarded port may have an access control list attached to it. +Only authorized hosts are allowed to connect. Access control checks are +performed by quick checks on the client's IP address. +.TP +.I "Nonblocking single-process design" +The internal structure of the server is completely nonblocking. The +connections don't block; the reading and writing don't block; the name +lookups don't block. This is all done in a single process, with the +single exception of the DNS resolver. +.SS "Command line options" +The +.B fw +program understands a few simple command line options: +.TP +.B "\-h, \-\-help" +Displays a screen of help text on standard output and exits +successfully. +.TP +.B "\-v, \-\-version" +Writes the version number to standard output and exits successfully. +.TP +.B "\-u, \-\-usage" +Writes a terse usage summary to standard output and exits successfully. +.TP +.BI "\-f, \-\-file=" file +Read configuration information from +.IR file . +.TP +.B "\-d, \-\-dump" +Writes a dump of the final configuration to standard output and exits +successfully. +.TP +.B "\-b, \-\-background, \-\-fork" +Forks into the background after reading the configuration and +initializing properly. +.PP +Any further command line arguments are interpreted as configuration +lines to be read. Configuration supplied in command line arguments has +precisely the same syntax as configuration in files. If there are no +configurmation statements on the command line, and no +.B \-f +options were supplied, configuration is read from standard input, if +stdin is not a terminal. +.SS "Configuration language" +The forwarder understands a simple free-form configuration language, +described by the following BNF-like grammar: +.PP +.ll +20 +.I config +::= +.IR stmt ... +.br +.I stmt +::= +.I fwd-stmt +| +.I acl-stmt +.br +.I fwd-stmt +::= +.B forward +.RB [ port ] +.I port +.RB [ to ] +.I addr +.RB [ : ] +.I port +.RI [ fwd-attr ] +.RB [ ; ] +.br +.I fwd-attr +::= +.B { +.IR acl-stmt ... +.B } +.br +.I acl-stmt +::= +.RB ( allow +| +.BR deny ) +.RB [ from ] +.I addr +.RB [ / +.IR mask ] +.RB [ ; ] +.ll -20 +.PP +In the above, a +.I port +may be a port number or service name defined in +.BR /etc/services ; +an +.I addr +may be a hostname or an IP address in dotted-quad notation; a +.I mask +may be either a netmask in dotted-quad notation or the integer number of +set bits in the netmask (e.g., +.B /24 +means the same as +.B /255.255.255.0 +as a netmask). +.PP +A forwarding statement makes +.B fw +listen on the first-named port and open connections to the given address +and port when it +.PP +ACL statements within a brace enclosed attribute list attached to a +forwarding statement apply only to that particular port; ACL statements +outside the scope of a forwarding statement contribute to a +.IR "global ACL" . +When an incoming connection is detected, it is first matched against +each rule in the port's local ACL in turn. If there's no match there, +it's then looked up in the global ACL. If that doesn't match either, +the connection is either refused or accepted, whichever is the opposite +of the last rule tried. If there are no rules, all connections are +allowed since this is more useful than denying all connections. +.PP +Comments may be included in a configuration file. They are introduced +by a +.RB ` # ' +character, and continue until the end of the line. When reading +configuration from the command line, each argument is considered to be a +separate line. +.SS "Logging" +The +.B fw +program logs each incoming connection. Since the log entry is made +after the connection is established (since it needs to perform DNS and +RFC931 lookups), it includes the actual time of the connection in the +message body. +.PP +If the server is run in the foreground (i.e., the +.B \-b +flag isn't specified) log messages are sent to standard error. If the +server is in the background, log messages are sent to the system log +service (see +.BR syslogd (8)) +with facility +.B LOG_DAEMON +and level +.BR LOG_NOTICE . +.SS "The DNS resolver" +The background resolver works by creating child resolver processes. +There's a fixed limit of 10 concurrent resolvers: resolution jobs are +queued until a resolver becomes free. Resolver processes persist for +multiple resolution jobs, although they are killed if they're idle for +more than a minute. +.PP +It's unlikely that the resolver's use of processes will become a problem +even for fairly heavily loaded servers. +.SH "BUGS" +I don't know of any bugs at all in +.BR fw . +If there are any, please let me know so I can fix them. Provide the +version number from +.BR "fw \-\-version" , +your operating system name and version, and complete descriptions of +what you did to cause the bug and what +.B fw +did wrong at that point. +.PP +I'm particularly concerned about security-related bugs. If you find +any, please let me know +.I really +quickly. I've taken some care to avoid security holes in +.B fw +but if there are any I've missed, I want to zap them as quickly as I +can. +.PP +Things which would be nice, but that I haven't done yet, are: +.hP \*o +Optionally notice connections from privileged ports and bind the +forwarding socket to a local privileged port. +.SH "AUTHOR" +Mark Wooding, -- 2.11.0