10a454ad |
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> |