3 .\" $Id: fw.1,v 1.14 2002/02/23 00:05:12 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.14 2002/02/23 00:05:12 mdw
32 .\" Fix spacing around full stops (at last!).
34 .\" Revision 1.13 2002/02/22 23:45:01 mdw
35 .\" Add option to change the listen(2) parameter.
37 .\" Revision 1.12 2001/02/23 09:11:29 mdw
38 .\" Update manual style.
40 .\" Revision 1.11 2001/02/05 19:47:11 mdw
41 .\" Minor fixings to wording.
43 .\" Revision 1.10 2001/02/03 20:30:03 mdw
44 .\" Support re-reading config files on SIGHUP.
46 .\" Revision 1.9 2000/03/23 00:37:33 mdw
47 .\" Add option to change user and group after initialization. Naughtily
48 .\" reassign short equivalents of --grammar and --options.
50 .\" Revision 1.8 1999/12/22 15:44:43 mdw
51 .\" Fix some errors, and document new option.
53 .\" Revision 1.7 1999/10/22 22:45:15 mdw
54 .\" Describe new socket connection options.
56 .\" Revision 1.6 1999/10/10 16:46:29 mdw
57 .\" Include grammar and options references at the end of the manual.
59 .\" Revision 1.5 1999/09/26 18:18:05 mdw
60 .\" Remove a fixed bug from the list. Fix some nasty formatting
63 .\" Revision 1.4 1999/08/19 18:32:48 mdw
64 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
65 .\" be quoted any more.
67 .\" Revision 1.3 1999/07/30 06:49:00 mdw
68 .\" Minor tidying and typo correction.
70 .\" Revision 1.2 1999/07/26 23:31:04 mdw
71 .\" Document lots of new features and syntax.
74 .\"----- Various bits of fancy styling --------------------------------------
76 .\" --- Indented paragraphs with right-aligned tags ---
80 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
83 .\" --- Verbatim-oid typesetting ---
97 .\" --- Grammar markup ---
99 .\" This is mainly for the benefit of the automatic scripts which
100 .\" generate the grammar summary.
119 .\" --- Other bits of styling ---
135 .\"--------------------------------------------------------------------------
137 .TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
139 .\"--------------------------------------------------------------------------
144 .\"--------------------------------------------------------------------------
157 .\"--------------------------------------------------------------------------
162 program is a simple port forwarder. It supports a number of features
163 the author hasn't found in similar programs:
165 .I "Connection logging"
166 Each connection attempt to the forwarder is logged, giving the time of
167 the connection, the DNS-resolved hostname (if available), and the user
168 name resulting from an RFC931 lookup. These lookups are done
169 asynchronously to the main forwarder's operation.
172 Each forwarded port may have an access control list attached to it.
173 Only authorized hosts are allowed to connect. Access control checks are
174 performed by quick checks on the client's IP address.
176 .I "Nonblocking single-process design"
177 The internal structure of the server is completely nonblocking. The
178 connections don't block; the reading and writing don't block; the name
179 lookups don't block. This is all done in a single process, with the
180 single exception of the DNS resolver.
182 .I "Support for Unix-domain sockets"
183 Connections from and to Unix-domain sockets can be handled just as
184 easily as more normal Internet sockets. Access control doesn't work on
185 Unix domain sockets, though. (Yet.)
186 .SS "Command line options"
189 program understands a few simple command line options:
192 Displays a screen of help text on standard output and exits
195 .B "\-v, \-\-version"
196 Writes the version number to standard output and exits successfully.
199 Writes a terse usage summary to standard output and exits successfully.
201 .B "\-G, \-\-grammar"
202 Writes a summary of the configuration file grammar to standard output
203 and exits successfully.
205 .B "\-O, \-\-options"
206 Writes a summary of the source and target options to standard output and
209 .BI "\-f, \-\-file=" file
210 Read configuration information from
215 configuration file statement.
217 .B "\-d, \-\-daemon, \-\-fork"
218 Forks into the background after reading the configuration and
219 initializing properly.
221 .B "\-l, \-\-syslog, \-\-log"
222 Emit logging information to the system log, rather than standard error.
225 Don't output any logging information. This option is not recommended
226 for normal use, although it can make system call traces clearer so I use
229 .BI "\-s, \-\-setuid=" user
230 Change uid to that of
232 which may be either a user name or uid number, after initializing all
233 the sources. This will usually require elevated privileges.
235 .BI "\-g, \-\-setgid=" group
236 Change gid to that of
238 which may be either a group name or gid number, after initializing all
239 the sources. If the operating system understands supplementary groups
240 then the supplementary groups list is altered to include only
243 Any further command line arguments are interpreted as configuration
244 lines to be read. Configuration supplied in command line arguments has
245 precisely the same syntax as configuration in files. If there are no
246 configuration statements on the command line, and no
248 options were supplied, configuration is read from standard input, if
249 stdin is not a terminal.
251 .\"--------------------------------------------------------------------------
252 .SH "CONFIGURATION LANGUAGE"
256 program has a fairly sophisticated configuration language to let you
257 describe which things should be forwarded where and what special
258 features there should be.
259 .SS "Lexical structure"
260 There are four types of characters.
262 .I "word constituent characters"
263 Word constituent characters are gathered together into words.
264 Depending on its surrounding context, a word might act as a keyword or a
265 string. All alphanumerics are word constituents, as is the hyphen
267 Other characters may change their status in future versions.
269 .I "self-delimiting characters"
270 Self-delimiting characters always stand alone. They act as punctuation,
271 shaping the sequence of words into more complex grammatical forms. The
284 are self-delimiting. Note that while some characters, e.g.,
288 require escaping by the shell, they are mostly optional in the grammar
289 and can tend to be omitted in quick hacks at the shell prompt.
291 .I "whitespace characters"
292 Whitespace characters separate words but are otherwise ignored. All
293 `normal' whitespace characters (e.g., space, tab and newline) are
294 considered to be whitespace for these purposes.
296 .I "special characters"
297 There are three special characters. The
299 character, if it appears at the start of a word, introduces a
301 which extends to the end of the current line or command-line argument.
302 Within a word, it behaves like a normal word-constituent character. The
305 escapes the following character causing it to be interpreted as a word
306 constituent regardless of its normal type. The double-quote
308 escapes all characters other than backslashes up to the next
309 double-quote and causes them to be regarded as word constituents. Note
310 that you don't have to quote a whole word. The backslash can escape a
311 quote character allowing you to insert it into a word if really
315 The overall syntax looks a bit like this:
354 If you prefer, the keyword
362 .SS "Sources and targets"
363 Forwarding is set up by attaching
367 Sources are things which are capable of
369 one end of a data flow on their own, while targets are things which are
370 capable of setting up the other end on demand. In the case of a TCP
371 port forwarder, the part which listens for incoming client connections
372 is the source, while the part which sets up outgoing connections to the
373 destination server is the target.
377 does is set up a collection of sources and targets based on your
378 configuration file so that when a source decides to initiate a data
379 flow, it tells its target to set its end up, and then squirts data back
380 and forth between the two until there's no more.
384 they stay around indefinitely setting up multiple attachments to
387 they set up one connection and then disappear. If all the sources
388 defined are transient, then
390 will quit when no more active sources remain and all connections have
395 program is fairly versatile. It allows you to attach any supported type
396 of source to any supported type of target. This will, I hope, be the
397 case in all future versions.
403 depend on the source or target type, and are therefore described in the
404 sections specific to the various types.
406 .SS "Options structure"
407 Most of the objects that
409 knows about (including sources and targets, but also other more specific
410 things such as socket address types) can have their behaviour modified
413 The options available at a particular point in the configuration depend
416 A global option, outside of a
418 has no context unless it is explicitly qualified, and affects global
419 behaviour. A local option, applied to a source or target in a
421 has the context of the type of source or target to which it is applied,
422 and affects only that source or target.
424 Note that it's important to distinguish between an option's context
425 (which is affected by its qualification) and its local or global
426 status. No matter how qualified, a global option will always control
427 default options for objects, and a local option will only affect a
428 specific source or target.
430 The syntax for qualifying options is like this:
455 Thus, you may qualify either an individual option or a sequence of
456 options. The two are equivalent; for example,
465 exec.rlimit.core = 0;
468 For each option, there is a sequence of prefixes which maximally qualify
469 that option. An option prefixed with this sequence is
470 .IR "fully qualified" .
471 In actual use, some or all of those prefixes may be omitted. However,
472 it's possible for the option to become
474 if you do this. For example, the option
479 .BR socket.unix.fattr.owner .
480 In this case, the ambiguity is benign: a local option will have as its
481 context an appropriate source or target, and both global options
482 actually control the same default. However, the option
488 which have separate defaults, and which one you actually get depends on
489 the exact implementation of
491 option parser. (Currently this would resolve to
493 although this may change in a later version.)
495 In this manual, options are usually shown in their fully-qualified form.
497 .SS "File attributes for created files: `fattr'"
502 sources and targets can create new filesystem objects. The
504 options allow control over the attributes of the newly-created objects.
509 use the same set of defaults, so a prefix of
511 is good enough for setting global options, and the implicit context
512 disambiguates local options.
514 The following file attribute options are supported:
515 .OS "File attribute options (`fattr')"
516 .IB prefix .fattr.mode
520 Sets the permissions mode for a new file. The
522 argument may be either an octal number or a
524 string which acts on the default permissions established by the
527 setting. The characters
531 do not have to be quoted within the mode string.
533 .OS "File attribute options (`fattr')"
534 .IB prefix .fattr.owner
538 Sets the owner for newly created files. On non-broken systems you will
539 need to be the superuser to set the owner on a file. The
541 may either be a numeric uid or a username. The default is not to change
542 the owner of the file once it's created. The synonyms
546 are accepted in place of
549 .OS "File attribute options (`fattr')"
550 .IB prefix .fattr.group
554 Sets the group for newly created files. You will usually need to be a
555 member of the group in question order to set the group of a file. The
557 may either be a numeric gid or a group name. The default is not to
558 change the group of the file once it's created. The synonym
560 is accepted in place of
564 .SS "The `file' source and target types"
567 source and target allow data to move to and from objects other
568 than sockets within the Unix filesystem. (Unix-domain sockets are
575 is used as a source, it is set up immediately.
579 sources and targets is like this:
580 .GS "File sources and targets"
613 .RB [[ : ] file [ : ]]
643 specification describes two files, the first to be used as input, the
644 second to be used as output, each described by an
647 If none of the keywords
652 are given, the type of an
654 is deduced from its nature: if it matches one of the strings
658 or begins with a digit, it's considered to be a file descriptor;
659 otherwise it's interpreted as a filename.
663 spec describes a file by its name within the filesystem. It is opened
664 when needed and closed again after use. For output files, the precise
665 behaviour is controlled by options described below.
669 spec attaches the input or output of the source or target to
674 spec uses an existing open file descriptor, given either by number or a
675 symbolic name. The name
677 refers to standard input (file descriptor 0 on normal systems) and
679 refers to standard output (file descriptor 1). The names work in
680 exactly the same way as the equivalent file descriptor numbers.
684 is omitted, the input
686 is used for both input and output. Exception: if the input refers to
687 standard input then the output will refer to standard output instead.
691 options apply equally to sources and targets. The options are as
698 Whether to create the output file if it doesn't exist. If
700 (the default), an error is reported if the file doesn't exist. If
702 the file is created if it doesn't exist.
707 .BR no | truncate | append
709 Controls the behaviour if the output file already exists. If
711 an error is reported. If
713 (the default), the existing file is replaced by the new data. If
715 the new data is appended to the file.
722 source and target also accept
724 options for controlling the attributes of the created file.
727 Under no circumstances will
729 create a file through a `dangling' symbolic link.
731 .SS "The `exec' source and target types"
734 source and target execute programs and allow access to their standard
735 input and output streams. Both source and target have the same syntax,
737 .GS "Exec source and target"
777 If a single word is given, it is a
779 and will be passed to the Bourne shell for execution. If a
780 bracket-enclosed sequence of words is given, it is considered to be a
781 list of arguments to pass to the program: if a
783 is also supplied, it names the file containing the program to execute;
784 otherwise the file named by the first argument
788 The standard input and output of the program are forwarded to the other
789 end of the connection. The standard error stream is caught by
795 source and target both understand the same set of options. The list of
796 options supported is as follows:
802 Whether to log the start and end of executed programs. If
804 (the default), a log message is emitted when the program is started
805 listing its process id, and another is emitted when the program finishes
806 giving its process id and exit status. If
808 these messages are not emitted. However the standard error stream is
811 abbreviation is accepted as a synonym for
819 Sets the current directory from which the the program should be run.
820 The default is not to change directory. The synonyms
825 are accepted in place of
833 Sets the root directory for the program, using the
835 system call. You must be the superuser for this option to work. The
836 default is not to set a root directory. The synonym
838 is accepted in place of
846 Sets the user (real and effective uid) to run the program as. This will
847 usually require superuser privileges to work. The default is not to
848 change uid. The synonym
850 is accepted in place of
858 Sets the group (real and effective gid) to run the program as. If
859 running with superuser privileges, the supplementary groups list is
860 cleared at the same time. The default is not to change gid (or clear
861 the supplementary groups list). The synonym
863 is accepted in place of
867 .BI exec.rlimit. limit \c
868 .RB [ .hard | .soft ]
872 Set resource limits for the program. The
874 may be one of the resource limit names described in
876 in lower-case and without the
884 is a number, followed optionally by
886 to multiply by 1024 (2\*(ss10\*(se),
888 to multiply by 1048576 (2\*(ss20\*(se), or
890 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
891 versions of these if they want. If
895 was specified, only the hard or soft limit is set; otherwise both are
896 set to the same value. Only the superuser can raise the hard limit.
897 The soft limit cannot be set above the hard limit.
902 Clears the program's environment.
910 from the program's environment. It is not an error if no variable named
915 .BR exec.env. [ set ]
924 in the program's environment, possibly replacing the existing value.
927 may be omitted if the
929 qualifier is present.
932 Note that environment variable modifications are performed in order,
933 global modifications before local ones.
935 .SS "The `socket' source and target types"
938 source and target provide access to network services. Support is
939 currently provided for TCP/IP and Unix-domain sockets, although other
940 address types can be added with reasonable ease.
942 The syntax for socket sources and targets is:
943 .GS "Socket source and target"
955 .RB [ socket [ .\& ]]
963 .RB [ socket [ .\& ]]
970 The syntax of the source and target addresses depend on the address
971 types, which are described below. The default address type, if no
976 Socket sources support options; socket targets do not. The source
977 options provided are:
982 .BR unlimited | one-shot
984 Controls the behaviour of the source when it receives connections. A
986 limits the number of simultaneous connections. The value
990 removes any limit on the number of connections possible. The value
992 will remove the socket source after a single successful connection.
993 (Connections refused by access control systems don't count here.)
994 The default is to apply a limit of 256 concurrent connections. Use of
997 option is not recommended.
1004 Sets the maximum of the kernel incoming connection queue for this socket
1005 source. This is the number given to the
1007 system call. The default is 5.
1009 .OS "Socket options"
1014 Whether to log incoming connections. If
1016 (the default) incoming connections are logged, together with information
1017 about the client (where available) and whether the connection was
1018 accepted or refused. If
1020 log messages are not generated.
1023 Address types also provide their own options.
1025 .SS "The `inet' socket address type"
1028 address type provides access to TCP ports. The
1030 source and target addresses have the following syntax:
1031 .GS "Socket source and target"
1058 may be given as a port number or a service name from the
1060 file (or YP map if you do that sort of thing). A
1062 may be a textual hostname or a numerical IP address.
1066 source address accepts the following options:
1067 .OS "Socket options"
1068 .BR socket.inet. [ allow | deny ]
1074 Adds an entry to the source's access control list. If only one
1076 is given, the entry applies only to that address; if two are given, the
1077 first is a network address and the second is a netmask either in
1078 dotted-quad format or a simple number of bits (e.g.,
1082 mean the same), and the entry applies to any address which, when masked
1083 by the netmask, is equal to the masked network address.
1086 The access control rules are examined in the order: local entries first,
1087 then global ones, each in the order given in the configuration file.
1088 The first matching entry is used. If no entries match, the behaviour is
1091 of the last entry tried. If there are no entries defined, the default
1092 is to allow all clients.
1094 .SS "The `unix' socket address type"
1097 address type allows access to Unix-domain sockets. The syntax for
1099 source and target addresses is like this:
1100 .GS "Socket source and target"
1109 The following options are supported by the
1111 source address type:
1112 .OS "Socket options"
1113 .BR socket.unix.fattr. *
1117 source address accepts
1119 options to control the attributes of the socket file created.
1122 Sockets are removed if
1124 exits normally (which it will do if it runs out of sources or
1127 shuts down in a clean way).
1129 To forward the local port 25 to a main mail server:
1131 from 25 to mailserv:25
1133 To attach a fortune server to a Unix-domain socket:
1135 from unix:/tmp/fortunes
1136 to exec [/usr/games/fortune] { user nobody }
1138 To fetch a fortune from the server:
1140 from file stdin, stdout to unix:/tmp/fortunes
1145 from stdin, null to null, stdout
1148 .\"--------------------------------------------------------------------------
1149 .SH "SIGNAL HANDLING"
1153 program responds to various signals when it's running. If it receives
1160 shutdown: it removes all of its sources, and will exit when no more
1161 connections are running. (Note that if the disposition
1165 does not re-enable the signal. You'll have to send
1173 shutdown: it removes all sources and extant connections and closes down
1174 more-or-less immediately.
1176 Finally, if any configuration files (other than standard input) were
1179 on its command line using the
1183 signal may be sent to instruct
1185 to reload its configuration. Any existing connections are allowed to
1186 run their course. If no such configuration files are available,
1188 just logs a message about the signal and continues.
1191 .\"--------------------------------------------------------------------------
1192 .SH "GRAMMAR SUMMARY"
1256 .SS "File source and target"
1283 .RB [[ : ] fd [ : ]]
1285 .RB | stdin | stdout
1289 .RB [[ : ] file [ : ]]
1315 .RB [ : ] null [ : ]
1317 .SS "Exec source and target"
1357 .SS "Socket source and target"
1369 .RB [ socket [ .\& ]]
1377 .RB [ socket [ .\& ]]
1416 .\"--------------------------------------------------------------------------
1417 .SH "OPTION SUMMARY"
1419 .SS "File attributes (`fattr')"
1420 .IB prefix .fattr.mode
1424 .IB prefix .fattr.owner
1428 .IB prefix .fattr.group
1439 .BR no | truncate | append
1464 .BI exec.rlimit. limit \c
1465 .RB [ .hard | .soft ]
1474 .BR exec.env. [ set ]
1479 .SS "Socket options"
1483 .BR unlimited | one-shot
1493 .BR socket.inet. [ allow | deny ]
1499 .BR socket.unix.fattr. *
1501 .\"--------------------------------------------------------------------------
1504 The syntax for IP addresses and filenames is nasty.
1506 IPv6 is not supported yet. Because of
1508 socket address architecture, it's probably not a major piece of work to
1511 Please inform me of any security problems you think you've identified in
1512 this program. I take security very seriously, and I will fix security
1513 holes as a matter of priority when I find out about them. I will be
1514 annoyed if I have to read about problems on Bugtraq because they weren't
1517 The program is too complicated, and this manual page is too long.
1519 .\"--------------------------------------------------------------------------
1522 Mark Wooding, <mdw@nsict.org>
1524 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob