| 1 | .\" -*-nroff-*- |
| 2 | .ie t .ds o \(bu |
| 3 | .el .ds o o |
| 4 | .de hP |
| 5 | .IP |
| 6 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c |
| 7 | .. |
| 8 | .TH fw 1 "1 July 1999" fw |
| 9 | .SH NAME |
| 10 | fw \- port forwarder |
| 11 | .SH SYNOPSIS |
| 12 | .B fw |
| 13 | .RB [ \-db ] |
| 14 | .RB [ \-f |
| 15 | .IR file ] |
| 16 | .IR config-stmt ... |
| 17 | .SH DESCRIPTION |
| 18 | The |
| 19 | .B fw |
| 20 | program is a simple port forwarder. It supports a number of features |
| 21 | the author hasn't found in similar programs: |
| 22 | .TP |
| 23 | .I "Connection logging" |
| 24 | Each connection attempt to the forwarder is logged, giving the time of |
| 25 | the connection, the DNS-resolved hostname (if available), and the user |
| 26 | name resulting from an RFC931 lookup. These lookups are done |
| 27 | asynchronously to the main forwarder's operation. |
| 28 | .TP |
| 29 | .I "Access control" |
| 30 | Each forwarded port may have an access control list attached to it. |
| 31 | Only authorized hosts are allowed to connect. Access control checks are |
| 32 | performed by quick checks on the client's IP address. |
| 33 | .TP |
| 34 | .I "Nonblocking single-process design" |
| 35 | The internal structure of the server is completely nonblocking. The |
| 36 | connections don't block; the reading and writing don't block; the name |
| 37 | lookups don't block. This is all done in a single process, with the |
| 38 | single exception of the DNS resolver. |
| 39 | .SS "Command line options" |
| 40 | The |
| 41 | .B fw |
| 42 | program understands a few simple command line options: |
| 43 | .TP |
| 44 | .B "\-h, \-\-help" |
| 45 | Displays a screen of help text on standard output and exits |
| 46 | successfully. |
| 47 | .TP |
| 48 | .B "\-v, \-\-version" |
| 49 | Writes the version number to standard output and exits successfully. |
| 50 | .TP |
| 51 | .B "\-u, \-\-usage" |
| 52 | Writes a terse usage summary to standard output and exits successfully. |
| 53 | .TP |
| 54 | .BI "\-f, \-\-file=" file |
| 55 | Read configuration information from |
| 56 | .IR file . |
| 57 | .TP |
| 58 | .B "\-d, \-\-dump" |
| 59 | Writes a dump of the final configuration to standard output and exits |
| 60 | successfully. |
| 61 | .TP |
| 62 | .B "\-b, \-\-background, \-\-fork" |
| 63 | Forks into the background after reading the configuration and |
| 64 | initializing properly. |
| 65 | .PP |
| 66 | Any further command line arguments are interpreted as configuration |
| 67 | lines to be read. Configuration supplied in command line arguments has |
| 68 | precisely the same syntax as configuration in files. If there are no |
| 69 | configurmation statements on the command line, and no |
| 70 | .B \-f |
| 71 | options were supplied, configuration is read from standard input, if |
| 72 | stdin is not a terminal. |
| 73 | .SS "Configuration language" |
| 74 | The forwarder understands a simple free-form configuration language, |
| 75 | described by the following BNF-like grammar: |
| 76 | .PP |
| 77 | .ll +20 |
| 78 | .I config |
| 79 | ::= |
| 80 | .IR stmt ... |
| 81 | .br |
| 82 | .I stmt |
| 83 | ::= |
| 84 | .I fwd-stmt |
| 85 | | |
| 86 | .I acl-stmt |
| 87 | .br |
| 88 | .I fwd-stmt |
| 89 | ::= |
| 90 | .B forward |
| 91 | .RB [ port ] |
| 92 | .I port |
| 93 | .RB [ to ] |
| 94 | .I addr |
| 95 | .RB [ : ] |
| 96 | .I port |
| 97 | .RI [ fwd-attr ] |
| 98 | .RB [ ; ] |
| 99 | .br |
| 100 | .I fwd-attr |
| 101 | ::= |
| 102 | .B { |
| 103 | .IR acl-stmt ... |
| 104 | .B } |
| 105 | .br |
| 106 | .I acl-stmt |
| 107 | ::= |
| 108 | .RB ( allow |
| 109 | | |
| 110 | .BR deny ) |
| 111 | .RB [ from ] |
| 112 | .I addr |
| 113 | .RB [ / |
| 114 | .IR mask ] |
| 115 | .RB [ ; ] |
| 116 | .ll -20 |
| 117 | .PP |
| 118 | In the above, a |
| 119 | .I port |
| 120 | may be a port number or service name defined in |
| 121 | .BR /etc/services ; |
| 122 | an |
| 123 | .I addr |
| 124 | may be a hostname or an IP address in dotted-quad notation; a |
| 125 | .I mask |
| 126 | may be either a netmask in dotted-quad notation or the integer number of |
| 127 | set bits in the netmask (e.g., |
| 128 | .B /24 |
| 129 | means the same as |
| 130 | .B /255.255.255.0 |
| 131 | as a netmask). |
| 132 | .PP |
| 133 | A forwarding statement makes |
| 134 | .B fw |
| 135 | listen on the first-named port and open connections to the given address |
| 136 | and port when it |
| 137 | .PP |
| 138 | ACL statements within a brace enclosed attribute list attached to a |
| 139 | forwarding statement apply only to that particular port; ACL statements |
| 140 | outside the scope of a forwarding statement contribute to a |
| 141 | .IR "global ACL" . |
| 142 | When an incoming connection is detected, it is first matched against |
| 143 | each rule in the port's local ACL in turn. If there's no match there, |
| 144 | it's then looked up in the global ACL. If that doesn't match either, |
| 145 | the connection is either refused or accepted, whichever is the opposite |
| 146 | of the last rule tried. If there are no rules, all connections are |
| 147 | allowed since this is more useful than denying all connections. |
| 148 | .PP |
| 149 | Comments may be included in a configuration file. They are introduced |
| 150 | by a |
| 151 | .RB ` # ' |
| 152 | character, and continue until the end of the line. When reading |
| 153 | configuration from the command line, each argument is considered to be a |
| 154 | separate line. |
| 155 | .SS "Logging" |
| 156 | The |
| 157 | .B fw |
| 158 | program logs each incoming connection. Since the log entry is made |
| 159 | after the connection is established (since it needs to perform DNS and |
| 160 | RFC931 lookups), it includes the actual time of the connection in the |
| 161 | message body. |
| 162 | .PP |
| 163 | If the server is run in the foreground (i.e., the |
| 164 | .B \-b |
| 165 | flag isn't specified) log messages are sent to standard error. If the |
| 166 | server is in the background, log messages are sent to the system log |
| 167 | service (see |
| 168 | .BR syslogd (8)) |
| 169 | with facility |
| 170 | .B LOG_DAEMON |
| 171 | and level |
| 172 | .BR LOG_NOTICE . |
| 173 | .SS "The DNS resolver" |
| 174 | The background resolver works by creating child resolver processes. |
| 175 | There's a fixed limit of 10 concurrent resolvers: resolution jobs are |
| 176 | queued until a resolver becomes free. Resolver processes persist for |
| 177 | multiple resolution jobs, although they are killed if they're idle for |
| 178 | more than a minute. |
| 179 | .PP |
| 180 | It's unlikely that the resolver's use of processes will become a problem |
| 181 | even for fairly heavily loaded servers. |
| 182 | .SH "BUGS" |
| 183 | I don't know of any bugs at all in |
| 184 | .BR fw . |
| 185 | If there are any, please let me know so I can fix them. Provide the |
| 186 | version number from |
| 187 | .BR "fw \-\-version" , |
| 188 | your operating system name and version, and complete descriptions of |
| 189 | what you did to cause the bug and what |
| 190 | .B fw |
| 191 | did wrong at that point. |
| 192 | .PP |
| 193 | I'm particularly concerned about security-related bugs. If you find |
| 194 | any, please let me know |
| 195 | .I really |
| 196 | quickly. I've taken some care to avoid security holes in |
| 197 | .B fw |
| 198 | but if there are any I've missed, I want to zap them as quickly as I |
| 199 | can. |
| 200 | .PP |
| 201 | Things which would be nice, but that I haven't done yet, are: |
| 202 | .hP \*o |
| 203 | Optionally notice connections from privileged ports and bind the |
| 204 | forwarding socket to a local privileged port. |
| 205 | .SH "AUTHOR" |
| 206 | Mark Wooding, <mdw@nsict.org> |