3 .\" $Id: fw.1,v 1.13 2002/02/22 23:45:01 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.13 2002/02/22 23:45:01 mdw
32 .\" Add option to change the listen(2) parameter.
34 .\" Revision 1.12 2001/02/23 09:11:29 mdw
35 .\" Update manual style.
37 .\" Revision 1.11 2001/02/05 19:47:11 mdw
38 .\" Minor fixings to wording.
40 .\" Revision 1.10 2001/02/03 20:30:03 mdw
41 .\" Support re-reading config files on SIGHUP.
43 .\" Revision 1.9 2000/03/23 00:37:33 mdw
44 .\" Add option to change user and group after initialization. Naughtily
45 .\" reassign short equivalents of --grammar and --options.
47 .\" Revision 1.8 1999/12/22 15:44:43 mdw
48 .\" Fix some errors, and document new option.
50 .\" Revision 1.7 1999/10/22 22:45:15 mdw
51 .\" Describe new socket connection options.
53 .\" Revision 1.6 1999/10/10 16:46:29 mdw
54 .\" Include grammar and options references at the end of the manual.
56 .\" Revision 1.5 1999/09/26 18:18:05 mdw
57 .\" Remove a fixed bug from the list. Fix some nasty formatting
60 .\" Revision 1.4 1999/08/19 18:32:48 mdw
61 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
62 .\" be quoted any more.
64 .\" Revision 1.3 1999/07/30 06:49:00 mdw
65 .\" Minor tidying and typo correction.
67 .\" Revision 1.2 1999/07/26 23:31:04 mdw
68 .\" Document lots of new features and syntax.
71 .\"----- Various bits of fancy styling --------------------------------------
73 .\" --- Indented paragraphs with right-aligned tags ---
77 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
80 .\" --- Verbatim-oid typesetting ---
94 .\" --- Grammar markup ---
96 .\" This is mainly for the benefit of the automatic scripts which
97 .\" generate the grammar summary.
116 .\" --- Other bits of styling ---
132 .\"--------------------------------------------------------------------------
134 .TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
136 .\"--------------------------------------------------------------------------
141 .\"--------------------------------------------------------------------------
154 .\"--------------------------------------------------------------------------
159 program is a simple port forwarder. It supports a number of features
160 the author hasn't found in similar programs:
162 .I "Connection logging"
163 Each connection attempt to the forwarder is logged, giving the time of
164 the connection, the DNS-resolved hostname (if available), and the user
165 name resulting from an RFC931 lookup. These lookups are done
166 asynchronously to the main forwarder's operation.
169 Each forwarded port may have an access control list attached to it.
170 Only authorized hosts are allowed to connect. Access control checks are
171 performed by quick checks on the client's IP address.
173 .I "Nonblocking single-process design"
174 The internal structure of the server is completely nonblocking. The
175 connections don't block; the reading and writing don't block; the name
176 lookups don't block. This is all done in a single process, with the
177 single exception of the DNS resolver.
179 .I "Support for Unix-domain sockets"
180 Connections from and to Unix-domain sockets can be handled just as
181 easily as more normal Internet sockets. Access control doesn't work on
182 Unix domain sockets, though. (Yet.)
183 .SS "Command line options"
186 program understands a few simple command line options:
189 Displays a screen of help text on standard output and exits
192 .B "\-v, \-\-version"
193 Writes the version number to standard output and exits successfully.
196 Writes a terse usage summary to standard output and exits successfully.
198 .B "\-G, \-\-grammar"
199 Writes a summary of the configuration file grammar to standard output
200 and exits successfully.
202 .B "\-O, \-\-options"
203 Writes a summary of the source and target options to standard output and
206 .BI "\-f, \-\-file=" file
207 Read configuration information from
212 configuration file statement.
214 .B "\-d, \-\-daemon, \-\-fork"
215 Forks into the background after reading the configuration and
216 initializing properly.
218 .B "\-l, \-\-syslog, \-\-log"
219 Emit logging information to the system log, rather than standard error.
222 Don't output any logging information. This option is not recommended
223 for normal use, although it can make system call traces clearer so I use
226 .BI "\-s, \-\-setuid=" user
227 Change uid to that of
229 which may be either a user name or uid number, after initializing all
230 the sources. This will usually require elevated privileges.
232 .BI "\-g, \-\-setgid=" group
233 Change gid to that of
235 which may be either a group name or gid number, after initializing all
236 the sources. If the operating system understands supplementary groups
237 then the supplementary groups list is altered to include only
240 Any further command line arguments are interpreted as configuration
241 lines to be read. Configuration supplied in command line arguments has
242 precisely the same syntax as configuration in files. If there are no
243 configuration statements on the command line, and no
245 options were supplied, configuration is read from standard input, if
246 stdin is not a terminal.
248 .\"--------------------------------------------------------------------------
249 .SH "CONFIGURATION LANGUAGE"
253 program has a fairly sophisticated configuration language to let you
254 describe which things should be forwarded where and what special
255 features there should be.
256 .SS "Lexical structure"
257 There are four types of characters.
259 .I "word constituent characters"
260 Word constituent characters are gathered together into words.
261 Depending on its surrounding context, a word might act as a keyword or a
262 string. All alphanumerics are word constituents, as is the hyphen
264 Other characters may change their status in future versions.
266 .I "self-delimiting characters"
267 Self-delimiting characters always stand alone. They act as punctuation,
268 shaping the sequence of words into more complex grammatical forms. The
281 are self-delimiting. Note that while some characters, e.g.,
285 require escaping by the shell, they are mostly optional in the grammar
286 and can tend to be omitted in quick hacks at the shell prompt.
288 .I "whitespace characters"
289 Whitespace characters separate words but are otherwise ignored. All
290 `normal' whitespace characters (e.g., space, tab and newline) are
291 considered to be whitespace for these purposes.
293 .I "special characters"
294 There are three special characters. The
296 character, if it appears at the start of a word, introduces a
298 which extends to the end of the current line or command-line argument.
299 Within a word, it behaves like a normal word-constituent character. The
302 escapes the following character causing it to be interpreted as a word
303 constituent regardless of its normal type. The double-quote
305 escapes all characters other than backslashes up to the next
306 double-quote and causes them to be regarded as word constituents. Note
307 that you don't have to quote a whole word. The backslash can escape a
308 quote character allowing you to insert it into a word if really
312 The overall syntax looks a bit like this:
351 If you prefer, the keyword
359 .SS "Sources and targets"
360 Forwarding is set up by attaching
364 Sources are things which are capable of
366 one end of a data flow on their own, while targets are things which are
367 capable of setting up the other end on demand. In the case of a TCP
368 port forwarder, the part which listens for incoming client connections
369 is the source, while the part which sets up outgoing connections to the
370 destination server is the target.
374 does is set up a collection of sources and targets based on your
375 configuration file so that when a source decides to initiate a data
376 flow, it tells its target to set its end up, and then squirts data back
377 and forth between the two until there's no more.
381 they stay around indefinitely setting up multiple attachments to
384 they set up one connection and then disappear. If all the sources
385 defined are transient, then
387 will quit when no more active sources remain and all connections have
392 program is fairly versatile. It allows you to attach any supported type
393 of source to any supported type of target. This will, I hope, be the
394 case in all future versions.
400 depend on the source or target type, and are therefore described in the
401 sections specific to the various types.
403 .SS "Options structure"
404 Most of the objects that
406 knows about (including sources and targets, but also other more specific
407 things such as socket address types) can have their behaviour modified
410 The options available at a particular point in the configuration depend
413 A global option, outside of a
415 has no context unless it is explicitly qualified, and affects global
416 behaviour. A local option, applied to a source or target in a
418 has the context of the type of source or target to which it is applied,
419 and affects only that source or target.
421 Note that it's important to distinguish between an option's context
422 (which is affected by its qualification) and its local or global
423 status. No matter how qualified, a global option will always control
424 default options for objects, and a local option will only affect a
425 specific source or target.
427 The syntax for qualifying options is like this:
452 Thus, you may qualify either an individual option or a sequence of
453 options. The two are equivalent; for example,
462 exec.rlimit.core = 0;
465 For each option, there is a sequence of prefixes which maximally qualify
466 that option. An option prefixed with this sequence is
467 .IR "fully qualified" .
468 In actual use, some or all of those prefixes may be omitted. However,
469 it's possible for the option to become
471 if you do this. For example, the option
476 .BR socket.unix.fattr.owner .
477 In this case, the ambiguity is benign: a local option will have as its
478 context an appropriate source or target, and both global options
479 actually control the same default. However, the option
485 which have separate defaults, and which one you actually get depends on
486 the exact implementation of
488 option parser. (Currently this would resolve to
490 although this may change in a later version.)
492 In this manual, options are usually shown in their fully-qualified form.
494 .SS "File attributes for created files: `fattr'"
499 sources and targets can create new filesystem objects. The
501 options allow control over the attributes of the newly-created objects.
506 use the same set of defaults, so a prefix of
508 is good enough for setting global options, and the implicit context
509 disambiguates local options.
511 The following file attribute options are supported:
512 .OS "File attribute options (`fattr')"
513 .IB prefix .fattr.mode
517 Sets the permissions mode for a new file. The
519 argument may be either an octal number or a
521 string which acts on the default permissions established by the
524 setting. The characters
528 do not have to be quoted within the mode string.
530 .OS "File attribute options (`fattr')"
531 .IB prefix .fattr.owner
535 Sets the owner for newly created files. On non-broken systems you will
536 need to be the superuser to set the owner on a file. The
538 may either be a numeric uid or a username. The default is not to change
539 the owner of the file once it's created. The synonyms
543 are accepted in place of
546 .OS "File attribute options (`fattr')"
547 .IB prefix .fattr.group
551 Sets the group for newly created files. You will usually need to be a
552 member of the group in question order to set the group of a file. The
554 may either be a numeric gid or a group name. The default is not to
555 change the group of the file once it's created. The synonym
557 is accepted in place of
561 .SS "The `file' source and target types"
564 source and target allow data to move to and from objects other
565 than sockets within the Unix filesystem. (Unix-domain sockets are
572 is used as a source, it is set up immediately.
576 sources and targets is like this:
577 .GS "File sources and targets"
610 .RB [[ : ] file [ : ]]
640 specification describes two files, the first to be used as input, the
641 second to be used as output, each described by an
644 If none of the keywords
649 are given, the type of an
651 is deduced from its nature: if it matches one of the strings
655 or begins with a digit, it's considered to be a file descriptor;
656 otherwise it's interpreted as a filename.
660 spec describes a file by its name within the filesystem. It is opened
661 when needed and closed again after use. For output files, the precise
662 behaviour is controlled by options described below.
666 spec attaches the input or output of the source or target to
671 spec uses an existing open file descriptor, given either by number or a
672 symbolic name. The name
674 refers to standard input (file descriptor 0 on normal systems) and
676 refers to standard output (file descriptor 1). The names work in
677 exactly the same way as the equivalent file descriptor numbers.
681 is omitted, the input
683 is used for both input and output. Exception: if the input refers to
684 standard input then the output will refer to standard output instead.
688 options apply equally to sources and targets. The options are as
695 Whether to create the output file if it doesn't exist. If
697 (the default), an error is reported if the file doesn't exist. If
699 the file is created if it doesn't exist.
704 .BR no | truncate | append
706 Controls the behaviour if the output file already exists. If
708 an error is reported. If
710 (the default), the existing file is replaced by the new data. If
712 the new data is appended to the file.
719 source and target also accept
721 options for controlling the attributes of the created file.
724 Under no circumstances will
726 create a file through a `dangling' symbolic link.
728 .SS "The `exec' source and target types"
731 source and target execute programs and allow access to their standard
732 input and output streams. Both source and target have the same syntax,
734 .GS "Exec source and target"
774 If a single word is given, it is a
776 and will be passed to the Bourne shell for execution. If a
777 bracket-enclosed sequence of words is given, it is considered to be a
778 list of arguments to pass to the program: if a
780 is also supplied, it names the file containing the program to execute;
781 otherwise the file named by the first argument
785 The standard input and output of the program are forwarded to the other
786 end of the connection. The standard error stream is caught by
792 source and target both understand the same set of options. The list of
793 options supported is as follows:
799 Whether to log the start and end of executed programs. If
801 (the default), a log message is emitted when the program is started
802 listing its process id, and another is emitted when the program finishes
803 giving its process id and exit status. If
805 these messages are not emitted. However the standard error stream is
808 abbreviation is accepted as a synonym for
816 Sets the current directory from which the the program should be run.
817 The default is not to change directory. The synonyms
822 are accepted in place of
830 Sets the root directory for the program, using the
832 system call. You must be the superuser for this option to work. The
833 default is not to set a root directory. The synonym
835 is accepted in place of
843 Sets the user (real and effective uid) to run the program as. This will
844 usually require superuser privileges to work. The default is not to
845 change uid. The synonym
847 is accepted in place of
855 Sets the group (real and effective gid) to run the program as. If
856 running with superuser privileges, the supplementary groups list is
857 cleared at the same time. The default is not to change gid (or clear
858 the supplementary groups list). The synonym
860 is accepted in place of
864 .BI exec.rlimit. limit \c
865 .RB [ .hard | .soft ]
869 Set resource limits for the program. The
871 may be one of the resource limit names described in
873 in lower-case and without the
881 is a number, followed optionally by
883 to multiply by 1024 (2\*(ss10\*(se),
885 to multiply by 1048576 (2\*(ss20\*(se), or
887 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
888 versions of these if they want. If
892 was specified, only the hard or soft limit is set; otherwise both are
893 set to the same value. Only the superuser can raise the hard limit.
894 The soft limit cannot be set above the hard limit.
899 Clears the program's environment.
907 from the program's environment. It is not an error if no variable named
912 .BR exec.env. [ set ]
921 in the program's environment, possibly replacing the existing value.
924 may be omitted if the
926 qualifier is present.
929 Note that environment variable modifications are performed in order,
930 global modifications before local ones.
932 .SS "The `socket' source and target types"
935 source and target provide access to network services. Support is
936 currently provided for TCP/IP and Unix-domain sockets, although other
937 address types can be added with reasonable ease.
939 The syntax for socket sources and targets is:
940 .GS "Socket source and target"
967 The syntax of the source and target addresses depend on the address
968 types, which are described below. The default address type, if no
973 Socket sources support options; socket targets do not. The source
974 options provided are:
979 .BR unlimited | one-shot
981 Controls the behaviour of the source when it receives connections. A
983 limits the number of simultaneous connections. The value
987 removes any limit on the number of connections possible. The value
989 will remove the socket source after a single successful connection.
990 (Connections refused by access control systems don't count here.)
991 The default is to apply a limit of 256 concurrent connections. Use of
994 option is not recommended.
1001 Sets the maximum of the kernel incoming connection queue for this socket
1002 source. This is the number given to the
1004 system call. The default is 5.
1006 .OS "Socket options"
1011 Whether to log incoming connections. If
1013 (the default) incoming connections are logged, together with information
1014 about the client (where available) and whether the connection was
1015 accepted or refused. If
1017 log messages are not generated.
1020 Address types also provide their own options.
1022 .SS "The `inet' socket address type"
1025 address type provides access to TCP ports. The
1027 source and target addresses have the following syntax:
1028 .GS "Socket source and target"
1055 may be given as a port number or a service name from the
1057 file (or YP map if you do that sort of thing). A
1059 may be a textual hostname or a numerical IP address.
1063 source address accepts the following options:
1064 .OS "Socket options"
1065 .BR socket.inet. [ allow | deny ]
1071 Adds an entry to the source's access control list. If only one
1073 is given, the entry applies only to that address; if two are given, the
1074 first is a network address and the second is a netmask either in
1075 dotted-quad format or a simple number of bits (e.g.,
1079 mean the same), and the entry applies to any address which, when masked
1080 by the netmask, is equal to the masked network address.
1083 The access control rules are examined in the order: local entries first,
1084 then global ones, each in the order given in the configuration file.
1085 The first matching entry is used. If no entries match, the behaviour is
1088 of the last entry tried. If there are no entries defined, the default
1089 is to allow all clients.
1091 .SS "The `unix' socket address type"
1094 address type allows access to Unix-domain sockets. The syntax for
1096 source and target addresses is like this:
1097 .GS "Socket source and target"
1106 The following options are supported by the
1108 source address type:
1109 .OS "Socket options"
1110 .BR socket.unix.fattr. *
1114 source address accepts
1116 options to control the attributes of the socket file created.
1119 Sockets are removed if
1121 exits normally (which it will do if it runs out of sources or
1124 shuts down in a clean way).
1126 To forward the local port 25 to a main mail server:
1128 from 25 to mailserv:25
1130 To attach a fortune server to a Unix-domain socket:
1132 from unix:/tmp/fortunes
1133 to exec [/usr/games/fortune] { user nobody }
1135 To fetch a fortune from the server:
1137 from file stdin, stdout to unix:/tmp/fortunes
1142 from stdin, null to null, stdout
1145 .\"--------------------------------------------------------------------------
1146 .SH "SIGNAL HANDLING"
1150 program responds to various signals when it's running. If it receives
1157 shutdown: it removes all of its sources, and will exit when no more
1158 connections are running. (Note that if the disposition
1162 does not re-enable the signal. You'll have to send
1170 shutdown: it removes all sources and extant connections and closes down
1171 more-or-less immediately.
1173 Finally, if any configuration files (other than standard input) were
1176 on its command line using the
1180 signal may be sent to instruct
1182 to reload its configuration. Any existing connections are allowed to
1183 run their course. If no such configuration files are available,
1185 just logs a message about the signal and continues.
1188 .\"--------------------------------------------------------------------------
1189 .SH "GRAMMAR SUMMARY"
1253 .SS "File source and target"
1280 .RB [[ : ] fd [ : ]]
1282 .RB | stdin | stdout
1286 .RB [[ : ] file [ : ]]
1312 .RB [ : ] null [ : ]
1314 .SS "Exec source and target"
1354 .SS "Socket source and target"
1413 .\"--------------------------------------------------------------------------
1414 .SH "OPTION SUMMARY"
1416 .SS "File attributes (`fattr')"
1417 .IB prefix .fattr.mode
1421 .IB prefix .fattr.owner
1425 .IB prefix .fattr.group
1436 .BR no | truncate | append
1461 .BI exec.rlimit. limit \c
1462 .RB [ .hard | .soft ]
1471 .BR exec.env. [ set ]
1476 .SS "Socket options"
1480 .BR unlimited | one-shot
1490 .BR socket.inet. [ allow | deny ]
1496 .BR socket.unix.fattr. *
1498 .\"--------------------------------------------------------------------------
1501 The syntax for IP addresses and filenames is nasty.
1503 IPv6 is not supported yet. Because of
1505 socket address architecture, it's probably not a major piece of work to
1508 Please inform me of any security problems you think you've identified in
1509 this program. I take security very seriously, and I will fix security
1510 holes as a matter of priority when I find out about them. I will be
1511 annoyed if I have to read about problems on Bugtraq because they weren't
1514 The program is too complicated, and this manual page is too long.
1516 .\"--------------------------------------------------------------------------
1519 Mark Wooding, <mdw@nsict.org>
1521 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob