3 .\" $Id: fw.1,v 1.10 2001/02/03 20:30:03 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.10 2001/02/03 20:30:03 mdw
32 .\" Support re-reading config files on SIGHUP.
34 .\" Revision 1.9 2000/03/23 00:37:33 mdw
35 .\" Add option to change user and group after initialization. Naughtily
36 .\" reassign short equivalents of --grammar and --options.
38 .\" Revision 1.8 1999/12/22 15:44:43 mdw
39 .\" Fix some errors, and document new option.
41 .\" Revision 1.7 1999/10/22 22:45:15 mdw
42 .\" Describe new socket connection options.
44 .\" Revision 1.6 1999/10/10 16:46:29 mdw
45 .\" Include grammar and options references at the end of the manual.
47 .\" Revision 1.5 1999/09/26 18:18:05 mdw
48 .\" Remove a fixed bug from the list. Fix some nasty formatting
51 .\" Revision 1.4 1999/08/19 18:32:48 mdw
52 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
53 .\" be quoted any more.
55 .\" Revision 1.3 1999/07/30 06:49:00 mdw
56 .\" Minor tidying and typo correction.
58 .\" Revision 1.2 1999/07/26 23:31:04 mdw
59 .\" Document lots of new features and syntax.
62 .\"----- Various bits of fancy styling --------------------------------------
64 .\" --- Indented paragraphs with right-aligned tags ---
68 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
71 .\" --- Verbatim-oid typesetting ---
85 .\" --- Grammar markup ---
87 .\" This is mainly for the benefit of the automatic scripts which
88 .\" generate the grammar summary.
107 .\" --- Other bits of styling ---
123 .\"--------------------------------------------------------------------------
125 .TH fw 1 "1 July 1999" fw
127 .\"--------------------------------------------------------------------------
132 .\"--------------------------------------------------------------------------
145 .\"--------------------------------------------------------------------------
150 program is a simple port forwarder. It supports a number of features
151 the author hasn't found in similar programs:
153 .I "Connection logging"
154 Each connection attempt to the forwarder is logged, giving the time of
155 the connection, the DNS-resolved hostname (if available), and the user
156 name resulting from an RFC931 lookup. These lookups are done
157 asynchronously to the main forwarder's operation.
160 Each forwarded port may have an access control list attached to it.
161 Only authorized hosts are allowed to connect. Access control checks are
162 performed by quick checks on the client's IP address.
164 .I "Nonblocking single-process design"
165 The internal structure of the server is completely nonblocking. The
166 connections don't block; the reading and writing don't block; the name
167 lookups don't block. This is all done in a single process, with the
168 single exception of the DNS resolver.
170 .I "Support for Unix-domain sockets"
171 Connections from and to Unix-domain sockets can be handled just as
172 easily as more normal Internet sockets. Access control doesn't work on
173 Unix domain sockets, though. (Yet.)
174 .SS "Command line options"
177 program understands a few simple command line options:
180 Displays a screen of help text on standard output and exits
183 .B "\-v, \-\-version"
184 Writes the version number to standard output and exits successfully.
187 Writes a terse usage summary to standard output and exits successfully.
189 .B "\-G, \-\-grammar"
190 Writes a summary of the configuration file grammar to standard output
191 and exits successfully.
193 .B "\-O, \-\-options"
194 Writes a summary of the source and target options to standard output and
197 .BI "\-f, \-\-file=" file
198 Read configuration information from
203 configuration file statement.
205 .B "\-d, \-\-daemon, \-\-fork"
206 Forks into the background after reading the configuration and
207 initializing properly.
209 .B "\-l, \-\-syslog, \-\-log"
210 Emit logging information to the system log, rather than standard error.
213 Don't output any logging information. This option is not recommended
214 for normal use, although it can make system call traces clearer so I use
217 .BI "\-s, \-\-setuid=" user
218 Change uid to that of
220 which may be either a user name or uid number, after initializing all
221 the sources. This will usually require elevated privileges.
223 .BI "\-g, \-\-setgid=" group
224 Change gid to that of
226 which may be either a group name or gid number, after initializing all
227 the sources. If the operating system understands supplementary groups
228 then the supplementary groups list is altered to include only
231 Any further command line arguments are interpreted as configuration
232 lines to be read. Configuration supplied in command line arguments has
233 precisely the same syntax as configuration in files. If there are no
234 configuration statements on the command line, and no
236 options were supplied, configuration is read from standard input, if
237 stdin is not a terminal.
239 .\"--------------------------------------------------------------------------
240 .SH "CONFIGURATION LANGUAGE"
244 program has a fairly sophisticated configuration language to let you
245 describe which things should be forwarded where and what special
246 features there should be.
247 .SS "Lexical structure"
248 There are four types of characters.
250 .I "word constituent characters"
251 Word constituent characters are gathered together into words.
252 Depending on its surrounding context, a word might act as a keyword or a
253 string. All alphanumerics are word constituents, as is the hyphen
255 Other characters may change their status in future versions.
257 .I "self-delimiting characters"
258 Self-delimiting characters always stand alone. They act as punctuation,
259 shaping the sequence of words into more complex grammatical forms. The
272 are self-delimiting. Note that while some characters, e.g.,
276 require escaping by the shell, they are mostly optional in the grammar
277 and can tend to be omitted in quick hacks at the shell prompt.
279 .I "whitespace characters"
280 Whitespace characters separate words but are otherwise ignored. All
281 `normal' whitespace characters (e.g., space, tab and newline) are
282 considered to be whitespace for these purposes.
284 .I "special characters"
285 There are three special characters. The
287 character, if it appears at the start of a word, introduces a
289 which extends to the end of the current line or command-line argument.
290 Within a word, it behaves like a normal word-constituent character. The
293 escapes the following character causing it to be interpreted as a word
294 constituent regardless of its normal type. The double-quote
296 escapes all characters other than backslashes up to the next
297 double-quote and causes them to be regarded as word constituents. Note
298 that you don't have to quote a whole word. The backslash can escape a
299 quote character allowing you to insert it into a word if really
303 The overall syntax looks a bit like this:
342 If you prefer, the keyword
350 .SS "Sources and targets"
351 Forwarding is set up by attaching
355 Sources are things which are capable of
357 one end of a data flow on their own, while targets are things which are
358 capable of setting up the other end on demand. In the case of a TCP
359 port forwarder, the part which listens for incoming client connections
360 is the source, while the part which sets up outgoing connections to the
361 destination server is the target.
365 does is set up a collection of sources and targets based on your
366 configuration file so that when a source decides to initiate a data
367 flow, it tells its target to set its end up, and then squirts data back
368 and forth between the two until there's no more.
372 they stay around indefinitely setting up multiple attachments to
375 they set up one connection and then disappear. If all the sources
376 defined are transient, then
378 will quit when no more active sources remain and all connections have
383 program is fairly versatile. It allows you to attach any supported type
384 of source to any supported type of target. This will, I hope, be the
385 case in all future versions.
391 depend on the source or target type, and are therefore described in the
392 sections specific to the various types.
394 .SS "Options structure"
395 Most of the objects that
397 knows about (including sources and targets, but also other more specific
398 things such as socket address types) can have their behaviour modified
401 The options available at a particular point in the configuration depend
404 A global option, outside of a
406 has no context unless it is explicitly qualified, and affects global
407 behaviour. Local options, applied to a source or target in a
409 has the context of the type of source or target to which it is applied,
410 and affects only that source or target.
412 Note that it's important to distinguish between an option's context
413 (which is affected by its qualification) and its local or global
414 status. No matter how qualified, a global option will always control
415 default options for objects, and a local option will only affect a
416 specific source or target.
418 The syntax for qualifying options is like this:
443 Thus, you may qualify either an individual option or a sequence of
444 options. The two are equivalent; for example,
453 exec.rlimit.core = 0;
456 For each option, there is a sequence of prefixes which maximally qualify
457 that option. An option prefixed with this sequence is
458 .IR "fully qualified" .
459 In actual use, some or all of those prefixes may be omitted. However,
460 it's possible for the option to become
462 if you do this. For example, the option
467 .BR socket.unix.fattr.owner .
468 In this case, the ambiguity is benign: a local option will have as its
469 context an appropriate source or target, and both global options
470 actually control the same default. However, the option
476 which have separate defaults, and which one you actually get depends on
477 the exact implementation of
479 option parser. (Currently this would resolve to
481 although this may change in a later version.)
483 In this manual, options are usually shown in their fully-qualified form.
485 .SS "File attributes for created files: `fattr'"
490 sources and targets can create new filesystem objects. The
492 options allow control over the attributes of the newly-created objects.
497 use the same set of defaults, so a prefix of
499 is good enough for setting global options, and the implicit context
500 disambiguates local options.
502 The following file attribute options are supported:
503 .OS "File attribute options (`fattr')"
504 .IB prefix .fattr.mode
508 Sets the permissions mode for a new file. The
510 argument may be either an octal number or a
512 string which acts on the default permissions established by the
515 setting. The characters
519 do not have to be quoted within the mode string.
521 .OS "File attribute options (`fattr')"
522 .IB prefix .fattr.owner
526 Sets the owner for newly created files. On non-broken systems you will
527 need to be the superuser to set the owner on a file. The
529 may either be a numeric uid or a username. The default is not to change
530 the owner of the file once it's created. The synonyms
534 are accepted in place of
537 .OS "File attribute options (`fattr')"
538 .IB prefix .fattr.group
542 Sets the group for newly created files. You will usually need to be a
543 member of the group in question order to set the group of a file. The
545 may either be a numeric gid or a group name. The default is not to
546 change the group of the file once it's created. The synonym
548 is accepted in place of
552 .SS "The `file' source and target types"
555 source and target allow data to move to and from objects other
556 than sockets within the Unix filesystem. (Unix-domain sockets are
563 is used as a source, it is set up immediately.
567 sources and targets is like this:
568 .GS "File sources and targets"
601 .RB [[ : ] file [ : ]]
631 specification describes two files, the first to be used as input, the
632 second to be used as output, each described by an
635 If none of the keywords
640 are given, the type of an
642 is deduced from its nature: if it matches one of the strings
646 or begins with a digit, it's considered to be a file descriptor;
647 otherwise it's interpreted as a filename.
651 spec describes a file by its name within the filesystem. It is opened
652 when needed and closed again after use. For output files, the precise
653 behaviour is controlled by options described below.
657 spec attaches the input or output of the source or target to
662 spec uses an existing open file descriptor, given either by number or a
663 symbolic name. The name
665 refers to standard input (file descriptor 0 on normal systems) and
667 refers to standard output (file descriptor 1). The names work in
668 exactly the same way as the equivalent file descriptor numbers.
672 is omitted, the input
674 is used for both input and output. Exception: if the input refers to
675 standard input then the output will refer to standard output instead.
679 options apply equally to sources and targets. The options are as
686 Whether to create the output file if it doesn't exist. If
688 (the default), an error is reported if the file doesn't exist. If
690 the file is created if it doesn't exist.
695 .BR no | truncate | append
697 Controls the behaviour if the output file already exists. If
699 an error is reported. If
701 (the default), the existing file is replaced by the new data. If
703 the new data is appended to the file.
710 source and target also accept
712 options for controlling the attributes of the created file.
715 Under no circumstances will
717 create a file through a `dangling' symbolic link.
719 .SS "The `exec' source and target types"
722 source and target execute programs and allow access to their standard
723 input and output streams. Both source and target have the same syntax,
725 .GS "Exec source and target"
765 If a single word is given, it is a
767 and will be passed to the Bourne shell for execution. If a
768 bracket-enclosed sequence of words is given, it is considered to be a
769 list of arguments to pass to the program: if a
771 is also supplied, it names the file containing the program to execute;
772 otherwise the file named by the first argument
776 The standard input and output of the program are forwarded to the other
777 end of the connection. The standard error stream is caught by
783 source and target both understand the same set of options. The list of
784 options supported is as follows:
790 Whether to log the start and end of executed programs. If
792 (the default), a log message is emitted when the program is started
793 listing its process id, and another is emitted when the program finishes
794 giving its process id and exit status. If
796 these messages are not emitted. However the standard error stream is
799 abbreviation is accepted as a synonym for
807 Sets the current directory from which the the program should be run.
808 The default is not to change directory. The synonyms
813 are accepted in place of
821 Sets the root directory for the program, using the
823 system call. You must be the superuser for this option to work. The
824 default is not to set a root directory. The synonym
826 is accepted in place of
834 Sets the user (real and effective uid) to run the program as. This will
835 usually require superuser privileges to work. The default is not to
836 change uid. The synonym
838 is accepted in place of
846 Sets the group (real and effective gid) to run the program as. If
847 running with superuser privileges, the supplementary groups list is
848 cleared at the same time. The default is not to change gid (or clear
849 the supplementary groups list). The synonym
851 is accepted in place of
855 .BI exec.rlimit. limit \c
856 .RB [ .hard | .soft ]
860 Set resource limits for the program. The
862 may be one of the resource limit names described in
864 in lower-case and without the
872 is a number, followed optionally by
874 to multiply by 1024 (2\*(ss10\*(se),
876 to multiply by 1048576 (2\*(ss20\*(se), or
878 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
879 versions of these if they want. If
883 was specified, only the hard or soft limit is set; otherwise both are
884 set to the same value. Only the superuser can raise the hard limit.
885 The soft limit cannot be set above the hard limit.
890 Clears the program's environment.
898 from the program's environment. It is not an error if no variable named
903 .BR exec.env. [ set ]
912 in the program's environment, possibly replacing the existing value.
915 may be omitted if the
917 qualifier is present.
920 Note that environment variable modifications are performed in order,
921 global modifications before local ones.
923 .SS "The `socket' source and target types"
926 source and target provide access to network services. Support is
927 currently provided for TCP/IP and Unix-domain sockets, although other
928 address types can be added with reasonable ease.
930 The syntax for socket sources and targets is:
931 .GS "Socket source and target"
958 The syntax of the source and target addresses depend on the address
959 types, which are described below. The default address type, if no
964 Socket sources support options; socket targets do not. The source
965 options provided are:
970 .BR unlimited | one-shot
972 Controls the behaviour of the source when it receives connections. A
974 limits the number of simultaneous connections. The value
978 removes any limit on the number of connections possible. The value
980 will remove the socket source after a single successful connection.
981 (Connections refused by access control systems don't count here.)
982 The default is to apply a limit of 256 concurrent connections. Use of
985 option is not recommended.
992 Whether to log incoming connections. If
994 (the default) incoming connections are logged, together with information
995 about the client (where available) and whether the connection was
996 accepted or refused. If
998 log messages are not generated.
1001 Address types also provide their own options.
1003 .SS "The `inet' socket address type"
1006 address type provides access to TCP ports. The
1008 source and target addresses have the following syntax:
1009 .GS "Socket source and target"
1036 may be given as a port number or a service name from the
1038 file (or YP map if you do that sort of thing). A
1040 may be a textual hostname or a numerical IP address.
1044 source address accepts the following options:
1045 .OS "Socket options"
1046 .BR socket.inet. [ allow | deny ]
1052 Adds an entry to the source's access control list. If only one
1054 is given, the entry applies only to that address; if two are given, the
1055 first is a network address and the second is a netmask either in
1056 dotted-quad format or a simple number of bits (e.g.,
1060 mean the same), and the entry applies to any address which, when masked
1061 by the netmask, is equal to the masked network address.
1064 The access control rules are examined in the order: local entries first,
1065 then global ones, each in the order given in the configuration file.
1066 The first matching entry is used. If no entries match, the behaviour is
1069 of the last entry tried. If there are no entries defined, the default
1070 is to allow all clients.
1072 .SS "The `unix' socket address type"
1075 address type allows access to Unix-domain sockets. The syntax for
1077 source and target addresses is like this:
1078 .GS "Socket source and target"
1087 The following options are supported by the
1089 source address type:
1090 .OS "Socket options"
1091 .BR socket.unix.fattr. *
1095 source address accepts
1097 options to control the attributes of the socket file created.
1100 Sockets are removed if
1102 exits normally (which it will do if it runs out of sources or
1105 shuts down in a clean way).
1107 To forward the local port 25 to a main mail server:
1109 from 25 to mailserv:25
1111 To attach a fortune server to a Unix-domain socket:
1113 from unix:/tmp/fortunes
1114 to exec [/usr/games/fortune] { user nobody }
1116 To fetch a fortune from the server:
1118 from file stdin, stdout to unix:/tmp/fortunes
1123 from stdin, null to null, stdout
1126 .\"--------------------------------------------------------------------------
1127 .SH "SIGNAL HANDLING"
1131 program responds to various signals when it's running. If it receives
1138 shutdown: it removes all of its sources, and will exit when no more
1139 connections are running. (Note that if the disposition
1143 does not re-enable the signal. You'll have to send
1151 shutdown: it removes all sources and extant connections and closes down
1152 more-or-less immediately.
1154 Finally, if any configuration files (other than standard input) were
1157 on its command line using the
1161 signal may be sent to instruct
1163 to reload its configuration. Any existing connections are allowed to
1164 run their course. If no such configuration files are available,
1166 just logs a message about the signal and continues.
1169 .\"--------------------------------------------------------------------------
1170 .SH "GRAMMAR SUMMARY"
1234 .SS "File source and target"
1261 .RB [[ : ] fd [ : ]]
1263 .RB | stdin | stdout
1267 .RB [[ : ] file [ : ]]
1293 .RB [ : ] null [ : ]
1295 .SS "Exec source and target"
1335 .SS "Socket source and target"
1394 .\"--------------------------------------------------------------------------
1395 .SH "OPTION SUMMARY"
1397 .SS "File attributes (`fattr')"
1398 .IB prefix .fattr.mode
1402 .IB prefix .fattr.owner
1406 .IB prefix .fattr.group
1417 .BR no | truncate | append
1442 .BI exec.rlimit. limit \c
1443 .RB [ .hard | .soft ]
1452 .BR exec.env. [ set ]
1457 .SS "Socket options"
1461 .BR unlimited | one-shot
1467 .BR socket.inet. [ allow | deny ]
1473 .BR socket.unix.fattr. *
1475 .\"--------------------------------------------------------------------------
1478 The syntax for IP addresses and filenames is nasty.
1480 IPv6 is not supported yet. Because of
1482 socket address architecture, it's probably not a major piece of work to
1485 Please inform me of any security problems you think you've identified in
1486 this program. I take security very seriously, and I will fix security
1487 holes as a matter of priority when I find out about them. I will be
1488 annoyed if I have to read about problems on Bugtraq because they weren't
1491 .\"--------------------------------------------------------------------------
1494 Mark Wooding, <mdw@nsict.org>
1496 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob