3 .\" $Id: fw.1,v 1.8 1999/12/22 15:44:43 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.8 1999/12/22 15:44:43 mdw
32 .\" Fix some errors, and document new option.
34 .\" Revision 1.7 1999/10/22 22:45:15 mdw
35 .\" Describe new socket connection options.
37 .\" Revision 1.6 1999/10/10 16:46:29 mdw
38 .\" Include grammar and options references at the end of the manual.
40 .\" Revision 1.5 1999/09/26 18:18:05 mdw
41 .\" Remove a fixed bug from the list. Fix some nasty formatting
44 .\" Revision 1.4 1999/08/19 18:32:48 mdw
45 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
46 .\" be quoted any more.
48 .\" Revision 1.3 1999/07/30 06:49:00 mdw
49 .\" Minor tidying and typo correction.
51 .\" Revision 1.2 1999/07/26 23:31:04 mdw
52 .\" Document lots of new features and syntax.
55 .\"----- Various bits of fancy styling --------------------------------------
57 .\" --- Indented paragraphs with right-aligned tags ---
61 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
64 .\" --- Verbatim-oid typesetting ---
78 .\" --- Grammar markup ---
80 .\" This is mainly for the benefit of the automatic scripts which
81 .\" generate the grammar summary.
100 .\" --- Other bits of styling ---
116 .\"--------------------------------------------------------------------------
118 .TH fw 1 "1 July 1999" fw
120 .\"--------------------------------------------------------------------------
125 .\"--------------------------------------------------------------------------
134 .\"--------------------------------------------------------------------------
139 program is a simple port forwarder. It supports a number of features
140 the author hasn't found in similar programs:
142 .I "Connection logging"
143 Each connection attempt to the forwarder is logged, giving the time of
144 the connection, the DNS-resolved hostname (if available), and the user
145 name resulting from an RFC931 lookup. These lookups are done
146 asynchronously to the main forwarder's operation.
149 Each forwarded port may have an access control list attached to it.
150 Only authorized hosts are allowed to connect. Access control checks are
151 performed by quick checks on the client's IP address.
153 .I "Nonblocking single-process design"
154 The internal structure of the server is completely nonblocking. The
155 connections don't block; the reading and writing don't block; the name
156 lookups don't block. This is all done in a single process, with the
157 single exception of the DNS resolver.
159 .I "Support for Unix-domain sockets"
160 Connections from and to Unix-domain sockets can be handled just as
161 easily as more normal Internet sockets. Access control doesn't work on
162 Unix domain sockets, though. (Yet.)
163 .SS "Command line options"
166 program understands a few simple command line options:
169 Displays a screen of help text on standard output and exits
172 .B "\-v, \-\-version"
173 Writes the version number to standard output and exits successfully.
176 Writes a terse usage summary to standard output and exits successfully.
178 .BI "\-f, \-\-file=" file
179 Read configuration information from
184 configuration file statement.
186 .B "\-d, \-\-daemon, \-\-fork"
187 Forks into the background after reading the configuration and
188 initializing properly.
190 .B "\-l, \-\-syslog, \-\-log"
191 Emit logging information to the system log, rather than standard error.
194 Don't output any logging information. This option is not recommended
195 for normal use, although it can make system call traces clearer so I use
198 Any further command line arguments are interpreted as configuration
199 lines to be read. Configuration supplied in command line arguments has
200 precisely the same syntax as configuration in files. If there are no
201 configuration statements on the command line, and no
203 options were supplied, configuration is read from standard input, if
204 stdin is not a terminal.
206 .\"--------------------------------------------------------------------------
207 .SH "CONFIGURATION LANGUAGE"
211 program has a fairly sophisticated configuration language to let you
212 describe which things should be forwarded where and what special
213 features there should be.
214 .SS "Lexical structure"
215 There are four types of characters.
217 .I "word constituent characters"
218 Word constituent characters are gathered together into words.
219 Depending on its surrounding context, a word might act as a keyword or a
220 string. All alphanumerics are word constituents, as is the hyphen
222 Other characters may change their status in future versions.
224 .I "self-delimiting characters"
225 Self-delimiting characters always stand alone. They act as punctuation,
226 shaping the sequence of words into more complex grammatical forms. The
239 are self-delimiting. Note that while some characters, e.g.,
243 require escaping by the shell, they are strictly optional in the grammar
244 and can be omitted in quick hacks at the shell prompt.
246 .I "whitespace characters"
247 Whitespace characters separate words but are otherwise ignored. All
248 `normal' whitespace characters (e.g., space, tab and newline) are
249 considered to be whitespace for these purposes.
251 .I "special characters"
252 There are three special characters. The
254 character, if it appears at the start of a word, introduces a
256 which extends to the end of the current line or command-line argument.
257 Within a word, it behaves like a normal word-constituent character. The
260 escapes the following character causing it to be interpreted as a word
261 constituent regardless of its normal type. The double-quote
263 escapes all characters other than backslashes up to the next
264 double-quote and causes them to be regarded as word constituents. Note
265 that you don't have to quote a whole word. The backslash can escape a
266 quote character allowing you to insert it into a word if really
270 The overall syntax looks a bit like this:
309 If you prefer, the keyword
317 .SS "Sources and targets"
318 Forwarding is set up by attaching
322 Sources are things which are capable of
324 one end of a data flow on their own, while targets are things which are
325 capable of setting up the other end on demand. In the case of a TCP
326 port forwarder, the part which listens for incoming client connections
327 is the source, while the part which sets up outgoing connections to the
328 destination server is the target.
332 does is set up a collection of sources and targets based on your
333 configuration file so that when a source decides to initiate a data
334 flow, it tells its target to set its end up, and then squirts data back
335 and forth between the two until there's no more.
339 they stay around indefinitely setting up multiple attachments to
342 they set up one connection and then disappear. If all the sources
343 defined are transient, then
345 will quit when no more active sources remain and all connections have
350 program is fairly versatile. It allows you to attach any supported type
351 of source to any supported type of target. This will, I hope, be the
352 case in all future versions.
358 depend on the source or target type, and are therefore described in the
359 sections specific to the various types.
361 .SS "Options structure"
362 Most of the objects that
364 knows about (including sources and targets, but also other more specific
365 things such as socket address types) can have their behaviour modified
368 The options available at a particular point in the configuration depend
371 A global option, outside of a
373 has no context unless it is explicitly qualified, and affects global
374 behaviour. Local options, applied to a source or target in a
376 has the context of the type of source or target to which it is applied,
377 and affects only that source or target.
379 Note that it's important to distinguish between an option's context
380 (which is affected by its qualification) and its local or global
381 status. No matter how qualified, a global option will always control
382 default options for objects, and a local option will only affect a
383 specific source or target.
385 The syntax for qualifying options is like this:
410 Thus, you may qualify either an individual option or a sequence of
411 options. The two are equivalent; for example,
420 exec.rlimit.core = 0;
423 For each option, there is a sequence of prefixes which maximally qualify
424 that option. An option prefixed with this sequence is
425 .IR "fully qualified" .
426 In actual use, some or all of those prefixes may be omitted. However,
427 it's possible for the option to become
429 if you do this. For example, the option
434 .BR socket.unix.fattr.owner .
435 In this case, the ambiguity is benign: a local option will have as its
436 context an appropriate source or target, and both global options
437 actually control the same default. However, the option
443 which have separate defaults, and which one you actually get depends on
444 the exact implementation of
446 option parser. (Currently this would resolve to
448 although this may change in a later version.)
450 In this manual, options are usually shown in their fully-qualified form.
452 .SS "File attributes for created files: `fattr'"
457 sources and targets can create new filesystem objects. The
459 options allow control over the attributes of the newly-created objects.
464 use the same set of defaults, so a prefix of
466 is good enough for setting global options, and the implicit context
467 disambiguates local options.
469 The following file attribute options are supported:
470 .OS "File attribute options (`fattr')"
471 .IB prefix .fattr.mode
475 Sets the permissions mode for a new file. The
477 argument may be either an octal number or a
479 string which acts on the default permissions established by the
482 setting. The characters
486 do not have to be quoted within the mode string.
488 .OS "File attribute options (`fattr')"
489 .IB prefix .fattr.owner
493 Sets the owner for newly created files. On non-broken systems you will
494 need to be the superuser to set the owner on a file. The
496 may either be a numeric uid or a username. The default is not to change
497 the owner of the file once it's created. The synonyms
501 are accepted in place of
504 .OS "File attribute options (`fattr')"
505 .IB prefix .fattr.group
509 Sets the group for newly created files. You will usually need to be a
510 member of the group in question order to set the group of a file. The
512 may either be a numeric gid or a group name. The default is not to
513 change the group of the file once it's created. The synonym
515 is accepted in place of
519 .SS "The `file' source and target types"
522 source and target allow data to move to and from objects other
523 than sockets within the Unix filesystem. (Unix-domain sockets are
530 is used as a source, it is set up immediately.
534 sources and targets is like this:
535 .GS "File sources and targets"
568 .RB [[ : ] file [ : ]]
598 specification describes two files, the first to be used as input, the
599 second to be used as output, each described by an
602 If none of the keywords
607 are given, the type of an
609 is deduced from its nature: if it matches one of the strings
613 or begins with a digit, it's considered to be a file descriptor;
614 otherwise it's interpreted as a filename.
618 spec describes a file by its name within the filesystem. It is opened
619 when needed and closed again after use. For output files, the precise
620 behaviour is controlled by options described below.
624 spec attaches the input or output of the source or target to
629 spec uses an existing open file descriptor, given either by number or a
630 symbolic name. The name
632 refers to standard input (file descriptor 0 on normal systems) and
634 refers to standard output (file descriptor 1). The names work in
635 exactly the same way as the equivalent file descriptor numbers.
639 is omitted, the input
641 is used for both input and output. Exception: if the input refers to
642 standard input then the output will refer to standard output instead.
646 options apply equally to sources and targets. The options are as
653 Whether to create the output file if it doesn't exist. If
655 (the default), an error is reported if the file doesn't exist. If
657 the file is created if it doesn't exist.
662 .BR no | truncate | append
664 Controls the behaviour if the output file already exists. If
666 an error is reported. If
668 (the default), the existing file is replaced by the new data. If
670 the new data is appended to the file.
677 source and target also accept
679 options for controlling the attributes of the created file.
682 Under no circumstances will
684 create a file through a `dangling' symbolic link.
686 .SS "The `exec' source and target types"
689 source and target execute programs and allow access to their standard
690 input and output streams. Both source and target have the same syntax,
692 .GS "Exec source and target"
732 If a single word is given, it is a
734 and will be passed to the Bourne shell for execution. If a
735 bracket-enclosed sequence of words is given, it is considered to be a
736 list of arguments to pass to the program: if a
738 is also supplied, it names the file containing the program to execute;
739 otherwise the file named by the first argument
743 The standard input and output of the program are forwarded to the other
744 end of the connection. The standard error stream is caught by
750 source and target both understand the same set of options. The list of
751 options supported is as follows:
757 Whether to log the start and end of executed programs. If
759 (the default), a log message is emitted when the program is started
760 listing its process id, and another is emitted when the program finishes
761 giving its process id and exit status. If
763 these messages are not emitted. However the standard error stream is
766 abbreviation is accepted as a synonym for
774 Sets the current directory from which the the program should be run.
775 The default is not to change directory. The synonyms
780 are accepted in place of
788 Sets the root directory for the program, using the
790 system call. You must be the superuser for this option to work. The
791 default is not to set a root directory. The synonyms
796 are accepted in place of
804 Sets the user (real and effective uid) to run the program as. This will
805 usually require superuser privileges to work. The default is not to
806 change uid. The synonym
808 is accepted in place of
816 Sets the group (real and effective gid) to run the program as. If
817 running with superuser privileges, the supplementary groups list is
818 cleared at the same time. The default is not to change gid (or clear
819 the supplementary groups list). The synonym
821 is accepted in place of
825 .BI exec.rlimit. limit \c
826 .RB [ .hard | .soft ]
830 Set resource limits for the program. The
832 may be one of the resource limit names described in
834 in lower-case and without the
842 is a number, followed optionally by
844 to multiply by 1024 (2\*(ss10\*(se),
846 to multiply by 1048576 (2\*(ss20\*(se), or
848 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
849 versions of these if they want. If
853 was specified, only the hard or soft limit is set; otherwise both are
854 set to the same value. Only the superuser can raise the hard limit.
855 The soft limit cannot be set above the hard limit.
860 Clears the program's environment.
868 from the program's environment. It is not an error if no variable named
873 .BR exec.env. [ set ]
882 in the program's environment, possibly replacing the existing value.
885 may be omitted if the
887 qualifier is present.
890 Note that environment variable modifications are performed in order,
891 global modifications before local ones.
893 .SS "The `socket' source and target types"
896 source and target provide access to network services. Support is
897 currently provided for TCP/IP and Unix-domain sockets, although other
898 address types can be added with reasonable ease.
900 The syntax for socket sources and targets is:
901 .GS "Socket source and target"
928 The syntax of the source and target addresses depend on the address
929 types, which are described below. The default address type, if no
934 Socket sources support options; socket targets do not. The source
935 options provided are:
940 .BR unlimited | one-shot
942 Controls the behaviour of the source when it receives connections. A
944 limits the number of simultaneous connections. The value
948 removes any limit on the number of connections possible. The value
950 will remove the socket source after a single successful connection.
951 (Connections refused by access control systems don't count here.)
952 The default is to apply a limit of 256 concurrent connections. Use of
955 option is not recommended.
962 Whether to log incoming connections. If
964 (the default) incoming connections are logged, together with information
965 about the client (where available) and whether the connection was
966 accepted or refused. If
968 log messages are not generated.
971 Address types also provide their own options.
973 .SS "The `inet' socket address type"
976 address type provides access to TCP ports. The
978 source and target addresses have the following syntax:
979 .GS "Socket source and target"
1006 may be given as a port number or a service name from the
1008 file (or YP map if you do that sort of thing). A
1010 may be a textual hostname or a numerical IP address.
1014 source address accepts the following options:
1015 .OS "Socket options"
1016 .BR socket.inet. [ allow | deny ]
1022 Adds an entry to the source's access control list. If only one
1024 is given, the entry applies only to that address; if two are given, the
1025 first is a network address and the second is a netmask either in
1026 dotted-quad format or a simple number of bits (e.g.,
1030 mean the same), and the entry applies to any address which, when masked
1031 by the netmask, is equal to the masked network address.
1034 The access control rules are examined in the order: local entries first,
1035 then global ones, each in the order given in the configuration file.
1036 The first matching entry is used. If no entries match, the behaviour is
1039 of the last entry tried. If there are no entries defined, the default
1040 is to allow all clients.
1042 .SS "The `unix' socket address type"
1045 address type allows access to Unix-domain sockets. The syntax for
1047 source and target addresses is like this:
1048 .GS "Socket source and target"
1057 The following options are supported by the
1059 source address type:
1060 .OS "Socket options"
1061 .BR socket.unix.fattr. *
1065 source address accepts
1067 options to control the attributes of the socket file created.
1070 Sockets are removed if
1072 exits normally (which it will do if it runs out of sources or
1073 connections, or if killed by SIGINT or SIGTERM).
1075 To forward the local port 25 to a main mail server:
1077 from 25 to mailserv:25
1079 To attach a fortune server to a Unix-domain socket:
1081 from unix:/tmp/fortunes
1082 to exec [/usr/games/fortune] { user nobody }
1084 To fetch a fortune from the server:
1086 from file stdin, stdout to unix:/tmp/fortunes
1091 from stdin, null to null, stdout
1094 .\"--------------------------------------------------------------------------
1095 .SH "GRAMMAR SUMMARY"
1159 .SS "File source and target"
1186 .RB [[ : ] fd [ : ]]
1188 .RB | stdin | stdout
1192 .RB [[ : ] file [ : ]]
1218 .RB [ : ] null [ : ]
1220 .SS "Exec source and target"
1260 .SS "Socket source and target"
1319 .\"--------------------------------------------------------------------------
1320 .SH "OPTION SUMMARY"
1322 .SS "File attributes (`fattr')"
1323 .IB prefix .fattr.mode
1327 .IB prefix .fattr.owner
1331 .IB prefix .fattr.group
1342 .BR no | truncate | append
1367 .BI exec.rlimit. limit \c
1368 .RB [ .hard | .soft ]
1377 .BR exec.env. [ set ]
1382 .SS "Socket options"
1386 .BR unlimited | one-shot
1392 .BR socket.inet. [ allow | deny ]
1398 .BR socket.unix.fattr. *
1400 .\"--------------------------------------------------------------------------
1403 The syntax for IP addresses and filenames is nasty.
1405 IPv6 is not supported yet. Because of
1407 socket address architecture, it's probably not a major piece of work to
1410 Please inform me of any security problems you think you've identified in
1411 this program. I take security very seriously, and I will fix security
1412 holes as a matter of priority when I find out about them. I will be
1413 annoyed if I have to read about problems on Bugtraq because they weren't
1416 .\"--------------------------------------------------------------------------
1419 Mark Wooding, <mdw@nsict.org>
1421 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob