3 .\" $Id: fw.1,v 1.5 1999/09/26 18:18:05 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.5 1999/09/26 18:18:05 mdw
32 .\" Remove a fixed bug from the list. Fix some nasty formatting
35 .\" Revision 1.4 1999/08/19 18:32:48 mdw
36 .\" Improve lexical analysis. In particular, `chmod' patterns don't have to
37 .\" be quoted any more.
39 .\" Revision 1.3 1999/07/30 06:49:00 mdw
40 .\" Minor tidying and typo correction.
42 .\" Revision 1.2 1999/07/26 23:31:04 mdw
43 .\" Document lots of new features and syntax.
46 .\"----- Various bits of fancy styling --------------------------------------
48 .\" --- Indented paragraphs with right-aligned tags ---
52 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
55 .\" --- Verbatim-oid typesetting ---
69 .\" --- Other bits of styling ---
85 .\"--------------------------------------------------------------------------
87 .TH fw 1 "1 July 1999" fw
89 .\"--------------------------------------------------------------------------
94 .\"--------------------------------------------------------------------------
103 .\"--------------------------------------------------------------------------
108 program is a simple port forwarder. It supports a number of features
109 the author hasn't found in similar programs:
111 .I "Connection logging"
112 Each connection attempt to the forwarder is logged, giving the time of
113 the connection, the DNS-resolved hostname (if available), and the user
114 name resulting from an RFC931 lookup. These lookups are done
115 asynchronously to the main forwarder's operation.
118 Each forwarded port may have an access control list attached to it.
119 Only authorized hosts are allowed to connect. Access control checks are
120 performed by quick checks on the client's IP address.
122 .I "Nonblocking single-process design"
123 The internal structure of the server is completely nonblocking. The
124 connections don't block; the reading and writing don't block; the name
125 lookups don't block. This is all done in a single process, with the
126 single exception of the DNS resolver.
128 .I "Support for Unix-domain sockets"
129 Connections from and to Unix-domain sockets can be handled just as
130 easily as more normal Internet sockets. Access control doesn't work on
131 Unix domain sockets, though. (Yet.)
132 .SS "Command line options"
135 program understands a few simple command line options:
138 Displays a screen of help text on standard output and exits
141 .B "\-v, \-\-version"
142 Writes the version number to standard output and exits successfully.
145 Writes a terse usage summary to standard output and exits successfully.
147 .BI "\-f, \-\-file=" file
148 Read configuration information from
153 configuration file statement.
155 .B "\-d, \-\-daemon, \-\-fork"
156 Forks into the background after reading the configuration and
157 initializing properly.
160 Don't output any logging information. This option is not recommended
161 for normal use, although it can make system call traces clearer so I use
164 Any further command line arguments are interpreted as configuration
165 lines to be read. Configuration supplied in command line arguments has
166 precisely the same syntax as configuration in files. If there are no
167 configuration statements on the command line, and no
169 options were supplied, configuration is read from standard input, if
170 stdin is not a terminal.
172 .\"--------------------------------------------------------------------------
173 .SH "CONFIGURATION LANGUAGE"
177 program has a fairly sophisticated configuration language to let you
178 describe which things should be forwarded where and what special
179 features there should be.
180 .SS "Lexical structure"
181 There are four types of characters.
183 .I "word constituent characters"
184 Word constituent characters are gathered together into words.
185 Depending on its surrounding context, a word might act as a keyword or a
186 string. All alphanumerics are word constituents, as is the hyphen
188 Other characters may change their status in future versions.
190 .I "self-delimiting characters"
191 Self-delimiting characters always stand alone. They act as punctuation,
192 shaping the sequence of words into more complex grammatical forms. The
205 are self-delimiting. Note that while some characters, e.g.,
209 require escaping by the shell, they are strictly optional in the grammar
210 and can be omitted in quick hacks at the shell prompt.
212 .I "whitespace characters"
213 Whitespace characters separate words but are otherwise ignored. All
214 `normal' whitespace characters (e.g., space, tab and newline) are
215 considered to be whitespace for these purposes.
217 .I "special characters"
218 There are three special characters. The
220 character, if it appears at the start of a word, introduces a
222 which extends to the end of the current line or command-line argument.
223 Within a word, it behaves like a normal word-constituent character. The
226 escapes the following character causing it to be interpreted as a word
227 constituent regardless of its normal type. The double-quote
229 escapes all characters other than backslashes up to the next
230 double-quote and causes them to be regarded as word constituents. Note
231 that you don't have to quote a whole word. The backslash can escape a
232 quote character allowing you to insert it into a word if really
236 The overall syntax looks a bit like this:
275 If you prefer, the keyword
283 .SS "Sources and targets"
284 Forwarding is set up by attaching
288 Sources are things which are capable of
290 one end of a data flow on their own, while targets are things which are
291 capable of setting up the other end on demand. In the case of a TCP
292 port forwarder, the part which listens for incoming client connections
293 is the source, while the part which sets up outgoing connections to the
294 destination server is the target.
298 does is set up a collection of sources and targets based on your
299 configuration file so that when a source decides to initiate a data
300 flow, it tells its target to set its end up, and then squirts data back
301 and forth between the two until there's no more.
305 they stay around indefinitely setting up multiple attachments to
308 they set up one connection and then disappear. If all the sources
309 defined are transient, then
311 will quit when no more active sources remain and all connections have
316 program is fairly versatile. It allows you to attach any supported type
317 of source to any supported type of target. This will, I hope, be the
318 case in all future versions.
324 depend on the source or target type, and are therefore described in the
325 sections specific to the various types.
327 .SS "Options structure"
328 Most of the objects that
330 knows about (including sources and targets, but also other more specific
331 things such as socket address types) can have their behaviour modified
334 The options available at a particular point in the configuration depend
337 A global option, outside of a
339 has no context unless it is explicitly qualified, and affects global
340 behaviour. Local options, applied to a source or target in a
342 has the context of the type of source or target to which it is applied,
343 and affects only that source or target.
345 Note that it's important to distinguish between an option's context
346 (which is affected by its qualification) and its local or global
347 status. No matter how qualified, a global option will always control
348 default options for objects, and a local option will only affect a
349 specific source or target.
351 The syntax for qualifying options is like this:
376 Thus, you may qualify either an individual option or a sequence of
377 options. The two are equivalent; for example,
386 exec.rlimit.core = 0;
389 For each option, there is a sequence of prefixes which maximally qualify
390 that option. An option prefixed with this sequence is
391 .IR "fully qualified" .
392 In actual use, some or all of those prefixes may be omitted. However,
393 it's possible for the option to become
395 if you do this. For example, the option
400 .BR socket.unix.fattr.owner .
401 In this case, the ambiguity is benign: a local option will have as its
402 context an appropriate source or target, and both global options
403 actually control the same default. However, the option
409 which have separate defaults, and which one you actually get depends on
410 the exact implementation of
412 option parser. (Currently this would resolve to
414 although this may change in a later version.)
416 In this manual, options are usually shown in their fully-qualified form.
418 .SS "The `file' source and target types"
421 source and target allow data to move to and from objects other
422 than sockets within the Unix filesystem. (Unix-domain sockets are
429 is used as a source, it is set up immediately.
433 sources and targets is like this:
467 .RB [[ : ] file [ : ]]
497 specification describes two files, the first to be used as input, the
498 second to be used as output, each described by an
501 If none of the keywords
506 are given, the type of an
508 is deduced from its nature: if it matches one of the strings
512 or begins with a digit, it's considered to be a file descriptor;
513 otherwise it's interpreted as a filename.
517 spec describes a file by its name within the filesystem. It is opened
518 when needed and closed again after use. For output files, the precise
519 behaviour is controlled by options described below.
523 spec attaches the input or output of the source or target to
528 spec uses an existing open file descriptor, given either by number or a
529 symbolic name. The name
531 refers to standard input (file descriptor 0 on normal systems) and
533 refers to standard output (file descriptor 1). The names work in
534 exactly the same way as the equivalent file descriptor numbers.
538 is omitted, the input
540 is used for both input and output. Exception: if the input refers to
541 standard input then the output will refer to standard output instead.
545 options apply equally to sources and targets. The options are as
552 Whether to create the output file if it doesn't exist. If
554 (the default), an error is reported if the file doesn't exist. If
556 the file is created if it doesn't exist.
561 .BR no | truncate | append
563 Controls the behaviour if the output file already exists. If
565 an error is reported. If
567 (the default), the existing file is replaced by the new data. If
569 the new data is appended to the file.
572 Under no circumstances will
574 create a file through a `dangling' symbolic link.
578 source and target also accept
580 options for controlling the attributes of the created file. The prefix
581 for setting file attributes is
584 .SS "File attributes for created files: `fattr'"
589 sources and targets can create new filesystem objects. The
591 options allow control over the attributes of the newly-created objects.
596 use the same set of defaults, so a prefix of
598 is good enough for setting global options, and the implicit context
599 disambiguates local options.
601 The following file attribute options are supported:
603 .IB prefix .fattr.mode
607 Sets the permissions mode for a new file. The
609 argument may be either an octal number or a
611 string which acts on the default permissions established by the
614 setting. The characters
618 do not have to be quoted within the mode string.
621 .IB prefix .fattr.owner
625 Sets the owner for newly created files. On non-broken systems you will
626 need to be the superuser to set the owner on a file. The
628 may either be a numeric uid or a username. The default is not to change
629 the owner of the file once it's created. The synonyms
633 are accepted in place of
637 .IB prefix .fattr.group
641 Sets the group for newly created files. You will usually need to be a
642 member of the group in question order to set the group of a file. The
644 may either be a numeric gid or a group name. The default is not to
645 change the group of the file once it's created. The synonym
647 is accepted in place of
651 .SS "The `exec' source and target types"
654 source and target execute programs and allow access to their standard
655 input and output streams. Both source and target have the same syntax,
697 If a single word is given, it is a
699 and will be passed to the Bourne shell for execution. If a
700 bracket-enclosed sequence of words is given, it is considered to be a
701 list of arguments to pass to the program: if a
703 is also supplied, it names the file containing the program to execute;
704 otherwise the file named by the first argument
708 The standard input and output of the program are forwarded to the other
709 end of the connection. The standard error stream is caught by
715 source and target both understand the same set of options. The list of
716 options supported is as follows:
722 Whether to log the start and end of executed programs. If
724 (the default), a log message is emitted when the program is started
725 listing its process id, and another is emitted when the program finishes
726 giving its process id and exit status. If
728 these messages are not emitted. However the standard error stream is
731 abbreviation is accepted as a synonym for
739 Sets the current directory from which the the program should be run.
740 The default is not to change directory. The synonyms
745 are accepted in place of
753 Sets the root directory for the program, using the
755 system call. You must be the superuser for this option to work. The
756 default is not to set a root directory. The synonyms
761 are accepted in place of
769 Sets the user (real and effective uid) to run the program as. This will
770 usually require superuser privileges to work. The default is not to
771 change uid. The synonym
773 is accepted in place of
781 Sets the group (real and effective gid) to run the program as. If
782 running with superuser privileges, the supplementary groups list is
783 cleared at the same time. The default is not to change gid (or clear
784 the supplementary groups list). The synonym
786 is accepted in place of
790 .BI exec.rlimit. limit \c
791 .RB [ .hard | .soft ]
795 Set resource limits for the program. The
797 may be one of the resource limit names described in
799 in lower-case and without the
807 is a number, followed optionally by
809 to multiply by 1024 (2\*(ss10\*(se),
811 to multiply by 1048576 (2\*(ss20\*(se), or
813 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
814 versions of these if they want. If
818 was specified, only the hard or soft limit is set; otherwise both are
819 set to the same value. Only the superuser can raise the hard limit.
820 The soft limit cannot be set above the hard limit.
825 Clears the program's environment.
833 from the program's environment. It is not an error if no variable named
838 .BR exec.env. [ set ]
847 in the program's environment, possibly replacing the existing value.
850 may be omitted if the
852 qualifier is present.
855 Note that environment variable modifications are performed in order,
856 global modifications before local ones.
858 .SS "The `socket' source and target types"
861 source and target provide access to network services. Support is
862 currently provided for TCP/IP and Unix-domain sockets, although other
863 address types can be added with reasonable ease.
865 The syntax for socket sources and targets is:
893 The syntax of the source and target addresses depend on the address
894 types, which are described below. The default address type, if no
899 Socket sources support options; socket targets do not. The source
900 options provided are:
906 Limits the number of simultaneous connections to this socket to the
908 given. The default is 256.
915 Whether to log incoming connections. If
917 (the default) incoming connections are logged, together with information
918 about the client (where available) and whether the connection was
919 accepted or refused. If
921 log messages are not generated.
924 Address types also provide their own options.
926 .SS "The `inet' socket address type"
929 address type provides access to TCP ports. The
931 source and target addresses have the following syntax:
959 may be given as a port number or a service name from the
961 file (or YP map if you do that sort of thing). A
963 may be a textual hostname or a numerical IP address.
967 source address accepts the following options:
969 .BR socket.inet. [ allow | deny ]
975 Adds an entry to the source's access control list. If only one
977 is given, the entry applies only to that address; if two are given, the
978 first is a network address and the second is a netmask either in
979 dotted-quad format or a simple number of bits (e.g.,
983 mean the same), and the entry applies to any address which, when masked
984 by the netmask, is equal to the masked network address.
987 control rules are examined in the order: local entries first, then
988 global ones, each in the order given in the configuration file. The
989 first matching entry is used. If no entries match, the behaviour is the
991 of the last entry tried. If there are no entries defined, the default
992 is to allow all clients.
995 .SS "The `unix' socket address type"
998 address type allows access to Unix-domain sockets. The syntax for
1000 source and target addresses is like this:
1016 source address accepts
1018 options to control the attributes of the socket file created. Sockets
1021 exits normally (which it will do if it runs out of sources or
1022 connections, or if killed by SIGINT or SIGTERM).
1024 To forward the local port 25 to a main mail server:
1026 from 25 to mailserv:25
1028 To attach a fortune server to a Unix-domain socket:
1030 from unix:/tmp/fortunes
1031 to exec [/usr/games/fortune] { user nobody }
1033 To fetch a fortune from the server:
1035 from file stdin, stdout to unix:/tmp/fortunes
1040 from stdin, null to null, stdout
1043 .\"--------------------------------------------------------------------------
1046 The syntax for IP addresses and filenames is nasty.
1048 IPv6 is not supported yet. It's probably not a major piece of work to
1051 Please inform me of any security problems you think you've identified in
1052 this program. I take security very seriously, and I will fix security
1053 holes as a matter of priority when I find out about them. I will be
1054 annoyed if I have to read about problems on Bugtraq because they weren't
1057 .\"--------------------------------------------------------------------------
1060 Mark Wooding, <mdw@nsict.org>
1062 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob