3 .\" $Id: fw.1,v 1.6 1999/10/10 16:46:29 mdw Exp $
7 .\" (c) 1999 Straylight/Edgeware
10 .\"----- Licensing notice ---------------------------------------------------
12 .\" This file is part of the `fw' port forwarder.
14 .\" `fw' is free software; you can redistribute it and/or modify
15 .\" it under the terms of the GNU General Public License as published by
16 .\" the Free Software Foundation; either version 2 of the License, or
17 .\" (at your option) any later version.
19 .\" `fw' is distributed in the hope that it will be useful,
20 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
21 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
22 .\" GNU General Public License for more details.
24 .\" You should have received a copy of the GNU General Public License
25 .\" along with `fw'; if not, write to the Free Software Foundation,
26 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
28 .\" ---- Revision history ---------------------------------------------------
31 .\" Revision 1.6 1999/10/10 16:46:29 mdw
32 .\" Include grammar and options references at the end of the manual.
34 .\" Revision 1.5 1999/09/26 18:18:05 mdw
35 .\" Remove a fixed bug from the list. Fix some nasty formatting
38 .\" Revision 1.4 1999/08/19 18:32:48 mdw
39 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
40 .\" be quoted any more.
42 .\" Revision 1.3 1999/07/30 06:49:00 mdw
43 .\" Minor tidying and typo correction.
45 .\" Revision 1.2 1999/07/26 23:31:04 mdw
46 .\" Document lots of new features and syntax.
49 .\"----- Various bits of fancy styling --------------------------------------
51 .\" --- Indented paragraphs with right-aligned tags ---
55 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
58 .\" --- Verbatim-oid typesetting ---
72 .\" --- Grammar markup ---
74 .\" This is mainly for the benefit of the automatic scripts which
75 .\" generate the grammar summary.
94 .\" --- Other bits of styling ---
110 .\"--------------------------------------------------------------------------
112 .TH fw 1 "1 July 1999" fw
114 .\"--------------------------------------------------------------------------
119 .\"--------------------------------------------------------------------------
128 .\"--------------------------------------------------------------------------
133 program is a simple port forwarder. It supports a number of features
134 the author hasn't found in similar programs:
136 .I "Connection logging"
137 Each connection attempt to the forwarder is logged, giving the time of
138 the connection, the DNS-resolved hostname (if available), and the user
139 name resulting from an RFC931 lookup. These lookups are done
140 asynchronously to the main forwarder's operation.
143 Each forwarded port may have an access control list attached to it.
144 Only authorized hosts are allowed to connect. Access control checks are
145 performed by quick checks on the client's IP address.
147 .I "Nonblocking single-process design"
148 The internal structure of the server is completely nonblocking. The
149 connections don't block; the reading and writing don't block; the name
150 lookups don't block. This is all done in a single process, with the
151 single exception of the DNS resolver.
153 .I "Support for Unix-domain sockets"
154 Connections from and to Unix-domain sockets can be handled just as
155 easily as more normal Internet sockets. Access control doesn't work on
156 Unix domain sockets, though. (Yet.)
157 .SS "Command line options"
160 program understands a few simple command line options:
163 Displays a screen of help text on standard output and exits
166 .B "\-v, \-\-version"
167 Writes the version number to standard output and exits successfully.
170 Writes a terse usage summary to standard output and exits successfully.
172 .BI "\-f, \-\-file=" file
173 Read configuration information from
178 configuration file statement.
180 .B "\-d, \-\-daemon, \-\-fork"
181 Forks into the background after reading the configuration and
182 initializing properly.
185 Don't output any logging information. This option is not recommended
186 for normal use, although it can make system call traces clearer so I use
189 Any further command line arguments are interpreted as configuration
190 lines to be read. Configuration supplied in command line arguments has
191 precisely the same syntax as configuration in files. If there are no
192 configuration statements on the command line, and no
194 options were supplied, configuration is read from standard input, if
195 stdin is not a terminal.
197 .\"--------------------------------------------------------------------------
198 .SH "CONFIGURATION LANGUAGE"
202 program has a fairly sophisticated configuration language to let you
203 describe which things should be forwarded where and what special
204 features there should be.
205 .SS "Lexical structure"
206 There are four types of characters.
208 .I "word constituent characters"
209 Word constituent characters are gathered together into words.
210 Depending on its surrounding context, a word might act as a keyword or a
211 string. All alphanumerics are word constituents, as is the hyphen
213 Other characters may change their status in future versions.
215 .I "self-delimiting characters"
216 Self-delimiting characters always stand alone. They act as punctuation,
217 shaping the sequence of words into more complex grammatical forms. The
230 are self-delimiting. Note that while some characters, e.g.,
234 require escaping by the shell, they are strictly optional in the grammar
235 and can be omitted in quick hacks at the shell prompt.
237 .I "whitespace characters"
238 Whitespace characters separate words but are otherwise ignored. All
239 `normal' whitespace characters (e.g., space, tab and newline) are
240 considered to be whitespace for these purposes.
242 .I "special characters"
243 There are three special characters. The
245 character, if it appears at the start of a word, introduces a
247 which extends to the end of the current line or command-line argument.
248 Within a word, it behaves like a normal word-constituent character. The
251 escapes the following character causing it to be interpreted as a word
252 constituent regardless of its normal type. The double-quote
254 escapes all characters other than backslashes up to the next
255 double-quote and causes them to be regarded as word constituents. Note
256 that you don't have to quote a whole word. The backslash can escape a
257 quote character allowing you to insert it into a word if really
261 The overall syntax looks a bit like this:
300 If you prefer, the keyword
308 .SS "Sources and targets"
309 Forwarding is set up by attaching
313 Sources are things which are capable of
315 one end of a data flow on their own, while targets are things which are
316 capable of setting up the other end on demand. In the case of a TCP
317 port forwarder, the part which listens for incoming client connections
318 is the source, while the part which sets up outgoing connections to the
319 destination server is the target.
323 does is set up a collection of sources and targets based on your
324 configuration file so that when a source decides to initiate a data
325 flow, it tells its target to set its end up, and then squirts data back
326 and forth between the two until there's no more.
330 they stay around indefinitely setting up multiple attachments to
333 they set up one connection and then disappear. If all the sources
334 defined are transient, then
336 will quit when no more active sources remain and all connections have
341 program is fairly versatile. It allows you to attach any supported type
342 of source to any supported type of target. This will, I hope, be the
343 case in all future versions.
349 depend on the source or target type, and are therefore described in the
350 sections specific to the various types.
352 .SS "Options structure"
353 Most of the objects that
355 knows about (including sources and targets, but also other more specific
356 things such as socket address types) can have their behaviour modified
359 The options available at a particular point in the configuration depend
362 A global option, outside of a
364 has no context unless it is explicitly qualified, and affects global
365 behaviour. Local options, applied to a source or target in a
367 has the context of the type of source or target to which it is applied,
368 and affects only that source or target.
370 Note that it's important to distinguish between an option's context
371 (which is affected by its qualification) and its local or global
372 status. No matter how qualified, a global option will always control
373 default options for objects, and a local option will only affect a
374 specific source or target.
376 The syntax for qualifying options is like this:
401 Thus, you may qualify either an individual option or a sequence of
402 options. The two are equivalent; for example,
411 exec.rlimit.core = 0;
414 For each option, there is a sequence of prefixes which maximally qualify
415 that option. An option prefixed with this sequence is
416 .IR "fully qualified" .
417 In actual use, some or all of those prefixes may be omitted. However,
418 it's possible for the option to become
420 if you do this. For example, the option
425 .BR socket.unix.fattr.owner .
426 In this case, the ambiguity is benign: a local option will have as its
427 context an appropriate source or target, and both global options
428 actually control the same default. However, the option
434 which have separate defaults, and which one you actually get depends on
435 the exact implementation of
437 option parser. (Currently this would resolve to
439 although this may change in a later version.)
441 In this manual, options are usually shown in their fully-qualified form.
443 .SS "File attributes for created files: `fattr'"
448 sources and targets can create new filesystem objects. The
450 options allow control over the attributes of the newly-created objects.
455 use the same set of defaults, so a prefix of
457 is good enough for setting global options, and the implicit context
458 disambiguates local options.
460 The following file attribute options are supported:
461 .OS "File attribute options (`fattr')"
462 .IB prefix .fattr.mode
466 Sets the permissions mode for a new file. The
468 argument may be either an octal number or a
470 string which acts on the default permissions established by the
473 setting. The characters
477 do not have to be quoted within the mode string.
479 .OS "File attribute options (`fattr')"
480 .IB prefix .fattr.owner
484 Sets the owner for newly created files. On non-broken systems you will
485 need to be the superuser to set the owner on a file. The
487 may either be a numeric uid or a username. The default is not to change
488 the owner of the file once it's created. The synonyms
492 are accepted in place of
495 .OS "File attribute options (`fattr')"
496 .IB prefix .fattr.group
500 Sets the group for newly created files. You will usually need to be a
501 member of the group in question order to set the group of a file. The
503 may either be a numeric gid or a group name. The default is not to
504 change the group of the file once it's created. The synonym
506 is accepted in place of
510 .SS "The `file' source and target types"
513 source and target allow data to move to and from objects other
514 than sockets within the Unix filesystem. (Unix-domain sockets are
521 is used as a source, it is set up immediately.
525 sources and targets is like this:
526 .GS "File sources and targets"
559 .RB [[ : ] file [ : ]]
589 specification describes two files, the first to be used as input, the
590 second to be used as output, each described by an
593 If none of the keywords
598 are given, the type of an
600 is deduced from its nature: if it matches one of the strings
604 or begins with a digit, it's considered to be a file descriptor;
605 otherwise it's interpreted as a filename.
609 spec describes a file by its name within the filesystem. It is opened
610 when needed and closed again after use. For output files, the precise
611 behaviour is controlled by options described below.
615 spec attaches the input or output of the source or target to
620 spec uses an existing open file descriptor, given either by number or a
621 symbolic name. The name
623 refers to standard input (file descriptor 0 on normal systems) and
625 refers to standard output (file descriptor 1). The names work in
626 exactly the same way as the equivalent file descriptor numbers.
630 is omitted, the input
632 is used for both input and output. Exception: if the input refers to
633 standard input then the output will refer to standard output instead.
637 options apply equally to sources and targets. The options are as
644 Whether to create the output file if it doesn't exist. If
646 (the default), an error is reported if the file doesn't exist. If
648 the file is created if it doesn't exist.
653 .BR no | truncate | append
655 Controls the behaviour if the output file already exists. If
657 an error is reported. If
659 (the default), the existing file is replaced by the new data. If
661 the new data is appended to the file.
668 source and target also accept
670 options for controlling the attributes of the created file.
673 Under no circumstances will
675 create a file through a `dangling' symbolic link.
677 .SS "The `exec' source and target types"
680 source and target execute programs and allow access to their standard
681 input and output streams. Both source and target have the same syntax,
683 .GS "Exec source and target"
723 If a single word is given, it is a
725 and will be passed to the Bourne shell for execution. If a
726 bracket-enclosed sequence of words is given, it is considered to be a
727 list of arguments to pass to the program: if a
729 is also supplied, it names the file containing the program to execute;
730 otherwise the file named by the first argument
734 The standard input and output of the program are forwarded to the other
735 end of the connection. The standard error stream is caught by
741 source and target both understand the same set of options. The list of
742 options supported is as follows:
748 Whether to log the start and end of executed programs. If
750 (the default), a log message is emitted when the program is started
751 listing its process id, and another is emitted when the program finishes
752 giving its process id and exit status. If
754 these messages are not emitted. However the standard error stream is
757 abbreviation is accepted as a synonym for
765 Sets the current directory from which the the program should be run.
766 The default is not to change directory. The synonyms
771 are accepted in place of
779 Sets the root directory for the program, using the
781 system call. You must be the superuser for this option to work. The
782 default is not to set a root directory. The synonyms
787 are accepted in place of
795 Sets the user (real and effective uid) to run the program as. This will
796 usually require superuser privileges to work. The default is not to
797 change uid. The synonym
799 is accepted in place of
807 Sets the group (real and effective gid) to run the program as. If
808 running with superuser privileges, the supplementary groups list is
809 cleared at the same time. The default is not to change gid (or clear
810 the supplementary groups list). The synonym
812 is accepted in place of
816 .BI exec.rlimit. limit \c
817 .RB [ .hard | .soft ]
821 Set resource limits for the program. The
823 may be one of the resource limit names described in
825 in lower-case and without the
833 is a number, followed optionally by
835 to multiply by 1024 (2\*(ss10\*(se),
837 to multiply by 1048576 (2\*(ss20\*(se), or
839 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
840 versions of these if they want. If
844 was specified, only the hard or soft limit is set; otherwise both are
845 set to the same value. Only the superuser can raise the hard limit.
846 The soft limit cannot be set above the hard limit.
851 Clears the program's environment.
859 from the program's environment. It is not an error if no variable named
864 .BR exec.env. [ set ]
873 in the program's environment, possibly replacing the existing value.
876 may be omitted if the
878 qualifier is present.
881 Note that environment variable modifications are performed in order,
882 global modifications before local ones.
884 .SS "The `socket' source and target types"
887 source and target provide access to network services. Support is
888 currently provided for TCP/IP and Unix-domain sockets, although other
889 address types can be added with reasonable ease.
891 The syntax for socket sources and targets is:
892 .GS "Socket source and target"
919 The syntax of the source and target addresses depend on the address
920 types, which are described below. The default address type, if no
925 Socket sources support options; socket targets do not. The source
926 options provided are:
932 Limits the number of simultaneous connections to this socket to the
934 given. The default is 256.
941 Whether to log incoming connections. If
943 (the default) incoming connections are logged, together with information
944 about the client (where available) and whether the connection was
945 accepted or refused. If
947 log messages are not generated.
950 Address types also provide their own options.
952 .SS "The `inet' socket address type"
955 address type provides access to TCP ports. The
957 source and target addresses have the following syntax:
958 .GS "Socket source and target"
985 may be given as a port number or a service name from the
987 file (or YP map if you do that sort of thing). A
989 may be a textual hostname or a numerical IP address.
993 source address accepts the following options:
995 .BR socket.inet. [ allow | deny ]
1001 Adds an entry to the source's access control list. If only one
1003 is given, the entry applies only to that address; if two are given, the
1004 first is a network address and the second is a netmask either in
1005 dotted-quad format or a simple number of bits (e.g.,
1009 mean the same), and the entry applies to any address which, when masked
1010 by the netmask, is equal to the masked network address.
1013 The access control rules are examined in the order: local entries first,
1014 then global ones, each in the order given in the configuration file.
1015 The first matching entry is used. If no entries match, the behaviour is
1018 of the last entry tried. If there are no entries defined, the default
1019 is to allow all clients.
1021 .SS "The `unix' socket address type"
1024 address type allows access to Unix-domain sockets. The syntax for
1026 source and target addresses is like this:
1027 .GS "Socket source and target"
1036 The following options are supported by the
1038 source address type:
1039 .OS "Socket options"
1040 .BR socket.unix.fattr. *
1044 source address accepts
1046 options to control the attributes of the socket file created.
1049 Sockets are removed if
1051 exits normally (which it will do if it runs out of sources or
1052 connections, or if killed by SIGINT or SIGTERM).
1054 To forward the local port 25 to a main mail server:
1056 from 25 to mailserv:25
1058 To attach a fortune server to a Unix-domain socket:
1060 from unix:/tmp/fortunes
1061 to exec [/usr/games/fortune] { user nobody }
1063 To fetch a fortune from the server:
1065 from file stdin, stdout to unix:/tmp/fortunes
1070 from stdin, null to null, stdout
1073 .\"--------------------------------------------------------------------------
1074 .SH "GRAMMAR SUMMARY"
1138 .SS "File source and target"
1165 .RB [[ : ] fd [ : ]]
1167 .RB | stdin | stdout
1171 .RB [[ : ] file [ : ]]
1197 .RB [ : ] null [ : ]
1199 .SS "Exec source and target"
1239 .SS "Socket source and target"
1298 .\"--------------------------------------------------------------------------
1299 .SH "OPTION SUMMARY"
1301 .SS "File attributes (`fattr')"
1302 .IB prefix .fattr.mode
1306 .IB prefix .fattr.owner
1310 .IB prefix .fattr.group
1321 .BR no | truncate | append
1346 .BI exec.rlimit. limit \c
1347 .RB [ .hard | .soft ]
1356 .BR exec.env. [ set ]
1361 .SS "Socket options"
1370 .BR socket.inet. [ allow | deny ]
1376 .BR socket.unix.fattr. *
1378 .\"--------------------------------------------------------------------------
1381 The syntax for IP addresses and filenames is nasty.
1383 IPv6 is not supported yet. It's probably not a major piece of work to
1386 Please inform me of any security problems you think you've identified in
1387 this program. I take security very seriously, and I will fix security
1388 holes as a matter of priority when I find out about them. I will be
1389 annoyed if I have to read about problems on Bugtraq because they weren't
1392 .\"--------------------------------------------------------------------------
1395 Mark Wooding, <mdw@nsict.org>
1397 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob