6 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
8 .TH fw 1 "1 July 1999" fw
20 program is a simple port forwarder. It supports a number of features
21 the author hasn't found in similar programs:
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.
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.
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"
42 program understands a few simple command line options:
45 Displays a screen of help text on standard output and exits
49 Writes the version number to standard output and exits successfully.
52 Writes a terse usage summary to standard output and exits successfully.
54 .BI "\-f, \-\-file=" file
55 Read configuration information from
59 Writes a dump of the final configuration to standard output and exits
62 .B "\-b, \-\-background, \-\-fork"
63 Forks into the background after reading the configuration and
64 initializing properly.
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
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:
120 may be a port number or service name defined in
124 may be a hostname or an IP address in dotted-quad notation; a
126 may be either a netmask in dotted-quad notation or the integer number of
127 set bits in the netmask (e.g.,
133 A forwarding statement makes
135 listen on the first-named port and open connections to the given address
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
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.
149 Comments may be included in a configuration file. They are introduced
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
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
163 If the server is run in the foreground (i.e., the
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
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
180 It's unlikely that the resolver's use of processes will become a problem
181 even for fairly heavily loaded servers.
183 I don't know of any bugs at all in
185 If there are any, please let me know so I can fix them. Provide the
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
191 did wrong at that point.
193 I'm particularly concerned about security-related bugs. If you find
194 any, please let me know
196 quickly. I've taken some care to avoid security holes in
198 but if there are any I've missed, I want to zap them as quickly as I
201 Things which would be nice, but that I haven't done yet, are:
203 Optionally notice connections from privileged ports and bind the
204 forwarding socket to a local privileged port.
206 Mark Wooding, <mdw@nsict.org>
~mdw / fwd / blob