3 .\" $Id: fw.1,v 1.16 2003/11/25 14:46:50 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.16 2003/11/25 14:46:50 mdw
32 .\" Update docco for new options.
34 .\" Revision 1.15 2003/01/24 20:13:04 mdw
35 .\" Fix bogus examples. Explain quoting rules for `exec' endpoints.
37 .\" Revision 1.14 2002/02/23 00:05:12 mdw
38 .\" Fix spacing around full stops (at last!).
40 .\" Revision 1.13 2002/02/22 23:45:01 mdw
41 .\" Add option to change the listen(2) parameter.
43 .\" Revision 1.12 2001/02/23 09:11:29 mdw
44 .\" Update manual style.
46 .\" Revision 1.11 2001/02/05 19:47:11 mdw
47 .\" Minor fixings to wording.
49 .\" Revision 1.10 2001/02/03 20:30:03 mdw
50 .\" Support re-reading config files on SIGHUP.
52 .\" Revision 1.9 2000/03/23 00:37:33 mdw
53 .\" Add option to change user and group after initialization. Naughtily
54 .\" reassign short equivalents of --grammar and --options.
56 .\" Revision 1.8 1999/12/22 15:44:43 mdw
57 .\" Fix some errors, and document new option.
59 .\" Revision 1.7 1999/10/22 22:45:15 mdw
60 .\" Describe new socket connection options.
62 .\" Revision 1.6 1999/10/10 16:46:29 mdw
63 .\" Include grammar and options references at the end of the manual.
65 .\" Revision 1.5 1999/09/26 18:18:05 mdw
66 .\" Remove a fixed bug from the list. Fix some nasty formatting
69 .\" Revision 1.4 1999/08/19 18:32:48 mdw
70 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
71 .\" be quoted any more.
73 .\" Revision 1.3 1999/07/30 06:49:00 mdw
74 .\" Minor tidying and typo correction.
76 .\" Revision 1.2 1999/07/26 23:31:04 mdw
77 .\" Document lots of new features and syntax.
80 .\"----- Various bits of fancy styling --------------------------------------
82 .\" --- Indented paragraphs with right-aligned tags ---
86 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
89 .\" --- Verbatim-oid typesetting ---
103 .\" --- Grammar markup ---
105 .\" This is mainly for the benefit of the automatic scripts which
106 .\" generate the grammar summary.
125 .\" --- Other bits of styling ---
141 .\"--------------------------------------------------------------------------
143 .TH fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder"
145 .\"--------------------------------------------------------------------------
150 .\"--------------------------------------------------------------------------
163 .\"--------------------------------------------------------------------------
168 program is a simple port forwarder. It supports a number of features
169 the author hasn't found in similar programs:
171 .I "Connection logging"
172 Each connection attempt to the forwarder is logged, giving the time of
173 the connection, the DNS-resolved hostname (if available), and the user
174 name resulting from an RFC931 lookup. These lookups are done
175 asynchronously to the main forwarder's operation.
178 Each forwarded port may have an access control list attached to it.
179 Only authorized hosts are allowed to connect. Access control checks are
180 performed by quick checks on the client's IP address.
182 .I "Nonblocking single-process design"
183 The internal structure of the server is completely nonblocking. The
184 connections don't block; the reading and writing don't block; the name
185 lookups don't block. This is all done in a single process, with the
186 single exception of the DNS resolver.
188 .I "Support for Unix-domain sockets"
189 Connections from and to Unix-domain sockets can be handled just as
190 easily as more normal Internet sockets. Access control doesn't work on
191 Unix domain sockets, though. (Yet.)
192 .SS "Command line options"
195 program understands a few simple command line options:
198 Displays a screen of help text on standard output and exits
201 .B "\-v, \-\-version"
202 Writes the version number to standard output and exits successfully.
205 Writes a terse usage summary to standard output and exits successfully.
207 .B "\-G, \-\-grammar"
208 Writes a summary of the configuration file grammar to standard output
209 and exits successfully.
211 .B "\-O, \-\-options"
212 Writes a summary of the source and target options to standard output and
215 .BI "\-f, \-\-file=" file
216 Read configuration information from
221 configuration file statement.
223 .B "\-d, \-\-daemon, \-\-fork"
224 Forks into the background after reading the configuration and
225 initializing properly.
227 .B "\-l, \-\-syslog, \-\-log"
228 Emit logging information to the system log, rather than standard error.
231 Don't output any logging information. This option is not recommended
232 for normal use, although it can make system call traces clearer so I use
235 .BI "\-s, \-\-setuid=" user
236 Change uid to that of
238 which may be either a user name or uid number, after initializing all
239 the sources. This will usually require elevated privileges.
241 .BI "\-g, \-\-setgid=" group
242 Change gid to that of
244 which may be either a group name or gid number, after initializing all
245 the sources. If the operating system understands supplementary groups
246 then the supplementary groups list is altered to include only
249 Any further command line arguments are interpreted as configuration
250 lines to be read. Configuration supplied in command line arguments has
251 precisely the same syntax as configuration in files. If there are no
252 configuration statements on the command line, and no
254 options were supplied, configuration is read from standard input, if
255 stdin is not a terminal.
257 .\"--------------------------------------------------------------------------
258 .SH "CONFIGURATION LANGUAGE"
262 program has a fairly sophisticated configuration language to let you
263 describe which things should be forwarded where and what special
264 features there should be.
265 .SS "Lexical structure"
266 There are four types of characters.
268 .I "word constituent characters"
269 Word constituent characters are gathered together into words.
270 Depending on its surrounding context, a word might act as a keyword or a
271 string. All alphanumerics are word constituents, as is the hyphen
273 Other characters may change their status in future versions.
275 .I "self-delimiting characters"
276 Self-delimiting characters always stand alone. They act as punctuation,
277 shaping the sequence of words into more complex grammatical forms. The
290 are self-delimiting. Note that while some characters, e.g.,
294 require escaping by the shell, they are mostly optional in the grammar
295 and can tend to be omitted in quick hacks at the shell prompt.
297 .I "whitespace characters"
298 Whitespace characters separate words but are otherwise ignored. All
299 `normal' whitespace characters (e.g., space, tab and newline) are
300 considered to be whitespace for these purposes.
302 .I "special characters"
303 There are three special characters. The
305 character, if it appears at the start of a word, introduces a
307 which extends to the end of the current line or command-line argument.
308 Within a word, it behaves like a normal word-constituent character. The
311 escapes the following character causing it to be interpreted as a word
312 constituent regardless of its normal type. The double-quote
314 escapes all characters other than backslashes up to the next
315 double-quote and causes them to be regarded as word constituents. Note
316 that you don't have to quote a whole word. The backslash can escape a
317 quote character allowing you to insert it into a word if really
321 The overall syntax looks a bit like this:
360 If you prefer, the keyword
368 .SS "Sources and targets"
369 Forwarding is set up by attaching
373 Sources are things which are capable of
375 one end of a data flow on their own, while targets are things which are
376 capable of setting up the other end on demand. In the case of a TCP
377 port forwarder, the part which listens for incoming client connections
378 is the source, while the part which sets up outgoing connections to the
379 destination server is the target.
383 does is set up a collection of sources and targets based on your
384 configuration file so that when a source decides to initiate a data
385 flow, it tells its target to set its end up, and then squirts data back
386 and forth between the two until there's no more.
390 they stay around indefinitely setting up multiple attachments to
393 they set up one connection and then disappear. If all the sources
394 defined are transient, then
396 will quit when no more active sources remain and all connections have
401 program is fairly versatile. It allows you to attach any supported type
402 of source to any supported type of target. This will, I hope, be the
403 case in all future versions.
409 depend on the source or target type, and are therefore described in the
410 sections specific to the various types.
412 .SS "Options structure"
413 Most of the objects that
415 knows about (including sources and targets, but also other more specific
416 things such as socket address types) can have their behaviour modified
419 The options available at a particular point in the configuration depend
422 A global option, outside of a
424 has no context unless it is explicitly qualified, and affects global
425 behaviour. A local option, applied to a source or target in a
427 has the context of the type of source or target to which it is applied,
428 and affects only that source or target.
430 Note that it's important to distinguish between an option's context
431 (which is affected by its qualification) and its local or global
432 status. No matter how qualified, a global option will always control
433 default options for objects, and a local option will only affect a
434 specific source or target.
436 The syntax for qualifying options is like this:
461 Thus, you may qualify either an individual option or a sequence of
462 options. The two are equivalent; for example,
471 exec.rlimit.core = 0;
474 For each option, there is a sequence of prefixes which maximally qualify
475 that option. An option prefixed with this sequence is
476 .IR "fully qualified" .
477 In actual use, some or all of those prefixes may be omitted. However,
478 it's possible for the option to become
480 if you do this. For example, the option
485 .BR socket.unix.fattr.owner .
486 In this case, the ambiguity is benign: a local option will have as its
487 context an appropriate source or target, and both global options
488 actually control the same default. However, the option
494 which have separate defaults, and which one you actually get depends on
495 the exact implementation of
497 option parser. (Currently this would resolve to
499 although this may change in a later version.)
501 In this manual, options are usually shown in their fully-qualified form.
503 .SS "File attributes for created files: `fattr'"
508 sources and targets can create new filesystem objects. The
510 options allow control over the attributes of the newly-created objects.
515 use the same set of defaults, so a prefix of
517 is good enough for setting global options, and the implicit context
518 disambiguates local options.
520 The following file attribute options are supported:
521 .OS "File attribute options (`fattr')"
522 .IB prefix .fattr.mode
526 Sets the permissions mode for a new file. The
528 argument may be either an octal number or a
530 string which acts on the default permissions established by the
533 setting. The characters
537 do not have to be quoted within the mode string.
539 .OS "File attribute options (`fattr')"
540 .IB prefix .fattr.owner
544 Sets the owner for newly created files. On non-broken systems you will
545 need to be the superuser to set the owner on a file. The
547 may either be a numeric uid or a username. The default is not to change
548 the owner of the file once it's created. The synonyms
552 are accepted in place of
555 .OS "File attribute options (`fattr')"
556 .IB prefix .fattr.group
560 Sets the group for newly created files. You will usually need to be a
561 member of the group in question order to set the group of a file. The
563 may either be a numeric gid or a group name. The default is not to
564 change the group of the file once it's created. The synonym
566 is accepted in place of
570 .SS "The `file' source and target types"
573 source and target allow data to move to and from objects other
574 than sockets within the Unix filesystem. (Unix-domain sockets are
581 is used as a source, it is set up immediately.
585 sources and targets is like this:
586 .GS "File sources and targets"
619 .RB [[ : ] file [ : ]]
649 specification describes two files, the first to be used as input, the
650 second to be used as output, each described by an
653 If none of the keywords
658 are given, the type of an
660 is deduced from its nature: if it matches one of the strings
664 or begins with a digit, it's considered to be a file descriptor;
665 otherwise it's interpreted as a filename.
669 spec describes a file by its name within the filesystem. It is opened
670 when needed and closed again after use. For output files, the precise
671 behaviour is controlled by options described below.
675 spec attaches the input or output of the source or target to
680 spec uses an existing open file descriptor, given either by number or a
681 symbolic name. The name
683 refers to standard input (file descriptor 0 on normal systems) and
685 refers to standard output (file descriptor 1). The names work in
686 exactly the same way as the equivalent file descriptor numbers.
690 is omitted, the input
692 is used for both input and output. Exception: if the input refers to
693 standard input then the output will refer to standard output instead.
697 options apply equally to sources and targets. The options are as
704 Whether to create the output file if it doesn't exist. If
706 (the default), an error is reported if the file doesn't exist. If
708 the file is created if it doesn't exist.
713 .BR no | truncate | append
715 Controls the behaviour if the output file already exists. If
717 an error is reported. If
719 (the default), the existing file is replaced by the new data. If
721 the new data is appended to the file.
728 source and target also accept
730 options for controlling the attributes of the created file.
733 Under no circumstances will
735 create a file through a `dangling' symbolic link.
737 .SS "The `exec' source and target types"
740 source and target execute programs and allow access to their standard
741 input and output streams. Both source and target have the same syntax,
743 .GS "Exec source and target"
783 If a single word is given, it is a
785 and will be passed to the Bourne shell for execution. If a
786 bracket-enclosed sequence of words is given, it is considered to be a
787 list of arguments to pass to the program: if a
789 is also supplied, it names the file containing the program to execute;
790 otherwise the file named by the first argument
794 Note that the shell command or program name string must, if present,
795 have any delimiter characters (including
799 quoted; this is not required in the
803 The standard input and output of the program are forwarded to the other
804 end of the connection. The standard error stream is caught by
810 source and target both understand the same set of options. The list of
811 options supported is as follows:
817 Whether to log the start and end of executed programs. If
819 (the default), a log message is emitted when the program is started
820 listing its process id, and another is emitted when the program finishes
821 giving its process id and exit status. If
823 these messages are not emitted. However the standard error stream is
826 abbreviation is accepted as a synonym for
834 Sets the current directory from which the the program should be run.
835 The default is not to change directory. The synonyms
840 are accepted in place of
848 Sets the root directory for the program, using the
850 system call. You must be the superuser for this option to work. The
851 default is not to set a root directory. The synonym
853 is accepted in place of
861 Sets the user (real and effective uid) to run the program as. This will
862 usually require superuser privileges to work. The default is not to
863 change uid. The synonym
865 is accepted in place of
873 Sets the group (real and effective gid) to run the program as. If
874 running with superuser privileges, the supplementary groups list is
875 cleared at the same time. The default is not to change gid (or clear
876 the supplementary groups list). The synonym
878 is accepted in place of
882 .BI exec.rlimit. limit \c
883 .RB [ .hard | .soft ]
887 Set resource limits for the program. The
889 may be one of the resource limit names described in
891 in lower-case and without the
899 is a number, followed optionally by
901 to multiply by 1024 (2\*(ss10\*(se),
903 to multiply by 1048576 (2\*(ss20\*(se), or
905 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
906 versions of these if they want. If
910 was specified, only the hard or soft limit is set; otherwise both are
911 set to the same value. Only the superuser can raise the hard limit.
912 The soft limit cannot be set above the hard limit.
917 Clears the program's environment.
925 from the program's environment. It is not an error if no variable named
930 .BR exec.env. [ set ]
939 in the program's environment, possibly replacing the existing value.
942 may be omitted if the
944 qualifier is present.
947 Note that environment variable modifications are performed in order,
948 global modifications before local ones.
950 .SS "The `socket' source and target types"
953 source and target provide access to network services. Support is
954 currently provided for TCP/IP and Unix-domain sockets, although other
955 address types can be added with reasonable ease.
957 The syntax for socket sources and targets is:
958 .GS "Socket source and target"
970 .RB [ socket [ .\& ]]
978 .RB [ socket [ .\& ]]
985 The syntax of the source and target addresses depend on the address
986 types, which are described below. The default address type, if no
991 Socket sources support options; socket targets do not. The source
992 options provided are:
997 .BR unlimited | one-shot
999 Controls the behaviour of the source when it receives connections. A
1001 limits the number of simultaneous connections. The value
1005 removes any limit on the number of connections possible. The value
1007 will remove the socket source after a single successful connection.
1008 (Connections refused by access control systems don't count here.)
1009 The default is to apply a limit of 256 concurrent connections. Use of
1012 option is not recommended.
1014 .OS "Socket options"
1019 Sets the maximum of the kernel incoming connection queue for this socket
1020 source. This is the number given to the
1022 system call. The default is 5.
1024 .OS "Socket options"
1029 Whether to log incoming connections. If
1031 (the default) incoming connections are logged, together with information
1032 about the client (where available) and whether the connection was
1033 accepted or refused. If
1035 log messages are not generated.
1038 Address types also provide their own options.
1040 .SS "The `inet' socket address type"
1043 address type provides access to TCP ports. The
1045 source and target addresses have the following syntax:
1046 .GS "Socket source and target"
1073 may be given as a port number or a service name from the
1075 file (or YP map if you do that sort of thing). A
1077 may be a textual hostname or a numerical IP address.
1081 source address accepts the following options:
1082 .OS "Socket options"
1083 .B socket.inet.source.addr
1088 Specify the IP address on which to listen for incoming connections. The
1091 which means to listen on all addresses, though it may be useful to
1092 specify this explicitly, if the global setting is different.
1094 .OS "Socket options"
1095 .BR socket.inet.source. [ allow | deny ]
1101 Adds an entry to the source's access control list. If only one
1103 is given, the entry applies only to that address; if two are given, the
1104 first is a network address and the second is a netmask either in
1105 dotted-quad format or a simple number of bits (e.g.,
1109 mean the same), and the entry applies to any address which, when masked
1110 by the netmask, is equal to the masked network address.
1112 .OS "Socket options"
1113 .BR socket.inet.source. [ allow | deny ]
1116 Accept or reject connections from low-numbered `privileged' ports, in
1119 .OS "Socket options"
1120 .B socket.inet.dest.addr
1125 Specify the IP address to bind the local socket to when making an
1126 outbound connection. The default is
1128 which means to use whichever address the kernel thinks is most
1129 convenient. This option is useful if the destination is doing
1130 host-based access control and your server is multi-homed.
1133 The access control rules are examined in the order: local entries first,
1134 then global ones, each in the order given in the configuration file.
1135 The first matching entry is used. If no entries match, the behaviour is
1138 of the last entry tried. If there are no entries defined, the default
1139 is to allow all clients.
1141 .SS "The `unix' socket address type"
1144 address type allows access to Unix-domain sockets. The syntax for
1146 source and target addresses is like this:
1147 .GS "Socket source and target"
1156 The following options are supported by the
1158 source address type:
1159 .OS "Socket options"
1160 .BR socket.unix.fattr. *
1164 source address accepts
1166 options to control the attributes of the socket file created.
1169 Sockets are removed if
1171 exits normally (which it will do if it runs out of sources or
1174 shuts down in a clean way).
1176 To forward the local port 25 to a main mail server:
1178 from 25 to mailserv:25
1180 To attach a fortune server to a Unix-domain socket:
1182 from unix:/tmp/fortunes
1183 to exec [/usr/games/fortune] { user nobody }
1185 To fetch a fortune from the server:
1187 from file stdin, stdout to unix:/tmp/fortunes
1192 from file stdin, null to file null, stdout
1195 .\"--------------------------------------------------------------------------
1196 .SH "SIGNAL HANDLING"
1200 program responds to various signals when it's running. If it receives
1207 shutdown: it removes all of its sources, and will exit when no more
1208 connections are running. (Note that if the disposition
1212 does not re-enable the signal. You'll have to send
1220 shutdown: it removes all sources and extant connections and closes down
1221 more-or-less immediately.
1223 Finally, if any configuration files (other than standard input) were
1226 on its command line using the
1230 signal may be sent to instruct
1232 to reload its configuration. Any existing connections are allowed to
1233 run their course. If no such configuration files are available,
1235 just logs a message about the signal and continues.
1238 .\"--------------------------------------------------------------------------
1239 .SH "GRAMMAR SUMMARY"
1303 .SS "File source and target"
1330 .RB [[ : ] fd [ : ]]
1332 .RB | stdin | stdout
1336 .RB [[ : ] file [ : ]]
1362 .RB [ : ] null [ : ]
1364 .SS "Exec source and target"
1404 .SS "Socket source and target"
1416 .RB [ socket [ .\& ]]
1424 .RB [ socket [ .\& ]]
1463 .\"--------------------------------------------------------------------------
1464 .SH "OPTION SUMMARY"
1466 .SS "File attributes (`fattr')"
1467 .IB prefix .fattr.mode
1471 .IB prefix .fattr.owner
1475 .IB prefix .fattr.group
1486 .BR no | truncate | append
1511 .BI exec.rlimit. limit \c
1512 .RB [ .hard | .soft ]
1521 .BR exec.env. [ set ]
1526 .SS "Socket options"
1530 .BR unlimited | one-shot
1540 .BR socket.inet.source. [ allow | deny ]
1546 .BR socket.inet.source. [ allow | deny ]
1549 .B socket.inet.source.addr
1554 .B socket.inet.dest.addr
1559 .BR socket.unix.fattr. *
1561 .\"--------------------------------------------------------------------------
1564 The syntax for IP addresses and filenames is nasty.
1566 IPv6 is not supported yet. Because of
1568 socket address architecture, it's probably not a major piece of work to
1571 Please inform me of any security problems you think you've identified in
1572 this program. I take security very seriously, and I will fix security
1573 holes as a matter of priority when I find out about them. I will be
1574 annoyed if I have to read about problems on Bugtraq because they weren't
1577 The program is too complicated, and this manual page is too long.
1579 .\"--------------------------------------------------------------------------
1582 Mark Wooding, <mdw@nsict.org>
1584 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob