3 .\" Manual page for fwd
5 .\" (c) 1999 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the `fwd' port forwarder.
12 .\" `fwd' is free software; you can redistribute it and/or modify
13 .\" it under the terms of the GNU General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (at your option) any later version.
17 .\" `fwd' is distributed in the hope that it will be useful,
18 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 .\" GNU General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with `fwd'; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
26 .\"----- Various bits of fancy styling --------------------------------------
28 .\" --- Indented paragraphs with right-aligned tags ---
32 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
35 .\" --- Verbatim-oid typesetting ---
49 .\" --- Grammar markup ---
51 .\" This is mainly for the benefit of the automatic scripts which
52 .\" generate the grammar summary.
75 .\" --- Other bits of styling ---
91 .\"--------------------------------------------------------------------------
93 .TH fwd 1 "1 July 1999" "Straylight/Edgeware" "fwd port forwarder"
95 .\"--------------------------------------------------------------------------
100 .\"--------------------------------------------------------------------------
115 .\"--------------------------------------------------------------------------
120 program is a simple port forwarder. It supports a number of features
121 the author hasn't found in similar programs:
123 .I "Connection logging"
124 Each connection attempt to the forwarder is logged, giving the time of
125 the connection, the DNS-resolved hostname (if available), and the user
126 name resulting from an RFC931 lookup. These lookups are done
127 asynchronously to the main forwarder's operation.
130 Each forwarded port may have an access control list attached to it.
131 Only authorized hosts are allowed to connect. Access control checks are
132 performed by quick checks on the client's IP address.
134 .I "Nonblocking single-process design"
135 The internal structure of the server is completely nonblocking. The
136 connections don't block; the reading and writing don't block; the name
137 lookups don't block. This is all done in a single process, with the
138 single exception of the DNS resolver.
140 .I "Support for Unix-domain sockets"
141 Connections from and to Unix-domain sockets can be handled just as
142 easily as more normal Internet sockets. Access control doesn't work on
143 Unix domain sockets, though. (Yet.)
144 .SS "Command line options"
147 program understands a few simple command line options:
150 Displays a screen of help text on standard output and exits
153 .B "\-v, \-\-version"
154 Writes the version number to standard output and exits successfully.
157 Writes a terse usage summary to standard output and exits successfully.
159 .B "\-G, \-\-grammar"
160 Writes a summary of the configuration file grammar to standard output
161 and exits successfully.
163 .B "\-O, \-\-options"
164 Writes a summary of the source and target options to standard output and
167 .BI "\-f, \-\-file=" file
168 Read configuration information from
173 configuration file statement.
175 .B "\-d, \-\-daemon, \-\-fork"
176 Forks into the background after reading the configuration and
177 initializing properly.
179 .B "\-l, \-\-syslog, \-\-log"
180 Emit logging information to the system log, rather than standard error.
182 .BI "\-p, \-\-pidfile=" file
189 is given too, then the process-id is written after forking (obviously).
192 Don't output any logging information. This option is not recommended
193 for normal use, although it can make system call traces clearer so I use
196 .BI "\-s, \-\-setuid=" user
197 Change uid to that of
199 which may be either a user name or uid number, after initializing all
200 the sources. This will usually require elevated privileges.
202 .BI "\-g, \-\-setgid=" group
203 Change gid to that of
205 which may be either a group name or gid number, after initializing all
206 the sources. If the operating system understands supplementary groups
207 then the supplementary groups list is altered to include only
210 Any further command line arguments are interpreted as configuration
211 lines to be read. Configuration supplied in command line arguments has
212 precisely the same syntax as configuration in files. If there are no
213 configuration statements on the command line, and no
215 options were supplied, configuration is read from standard input, if
216 stdin is not a terminal.
218 .\"--------------------------------------------------------------------------
219 .SH "CONFIGURATION LANGUAGE"
223 program has a fairly sophisticated configuration language to let you
224 describe which things should be forwarded where and what special
225 features there should be.
226 .SS "Lexical structure"
227 There are four types of characters.
229 .I "word constituent characters"
230 Word constituent characters are gathered together into words.
231 Depending on its surrounding context, a word might act as a keyword or a
232 string. All alphanumerics are word constituents, as is the hyphen
234 Other characters may change their status in future versions.
236 .I "self-delimiting characters"
237 Self-delimiting characters always stand alone. They act as punctuation,
238 shaping the sequence of words into more complex grammatical forms. The
251 are self-delimiting. Note that while some characters, e.g.,
255 require escaping by the shell, they are mostly optional in the grammar
256 and can tend to be omitted in quick hacks at the shell prompt.
258 .I "whitespace characters"
259 Whitespace characters separate words but are otherwise ignored. All
260 `normal' whitespace characters (e.g., space, tab and newline) are
261 considered to be whitespace for these purposes.
263 .I "special characters"
264 There are three special characters. The
266 character, if it appears at the start of a word, introduces a
268 which extends to the end of the current line or command-line argument.
269 Within a word, it behaves like a normal word-constituent character. The
272 escapes the following character causing it to be interpreted as a word
273 constituent regardless of its normal type. The double-quote
275 escapes all characters other than backslashes up to the next
276 double-quote and causes them to be regarded as word constituents. Note
277 that you don't have to quote a whole word. The backslash can escape a
278 quote character allowing you to insert it into a word if really
282 The overall syntax looks a bit like this:
321 If you prefer, the keyword
330 .SS "Sources and targets"
331 Forwarding is set up by attaching
335 Sources are things which are capable of
337 one end of a data flow on their own, while targets are things which are
338 capable of setting up the other end on demand. In the case of a TCP
339 port forwarder, the part which listens for incoming client connections
340 is the source, while the part which sets up outgoing connections to the
341 destination server is the target.
345 does is set up a collection of sources and targets based on your
346 configuration file so that when a source decides to initiate a data
347 flow, it tells its target to set its end up, and then squirts data back
348 and forth between the two until there's no more.
352 they stay around indefinitely setting up multiple attachments to
355 they set up one connection and then disappear. If all the sources
356 defined are transient, then
358 will quit when no more active sources remain and all connections have
363 program is fairly versatile. It allows you to attach any supported type
364 of source to any supported type of target. This will, I hope, be the
365 case in all future versions.
371 depend on the source or target type, and are therefore described in the
372 sections specific to the various types.
374 .SS "Options structure"
375 Most of the objects that
377 knows about (including sources and targets, but also other more specific
378 things such as socket address types) can have their behaviour modified
381 The options available at a particular point in the configuration depend
384 A global option, outside of a
386 has no context unless it is explicitly qualified, and affects global
387 behaviour. A local option, applied to a source or target in a
389 has the context of the type of source or target to which it is applied,
390 and affects only that source or target.
392 Note that it's important to distinguish between an option's context
393 (which is affected by its qualification) and its local or global
394 status. No matter how qualified, a global option will always control
395 default options for objects, and a local option will only affect a
396 specific source or target.
398 The syntax for qualifying options is like this:
423 Thus, you may qualify either an individual option or a sequence of
424 options. The two are equivalent; for example,
433 exec.rlimit.core = 0;
436 For each option, there is a sequence of prefixes which maximally qualify
437 that option. An option prefixed with this sequence is
438 .IR "fully qualified" .
439 In actual use, some or all of those prefixes may be omitted. However,
440 it's possible for the option to become
442 if you do this. For example, the option
447 .BR socket.unix.fattr.owner .
448 In this case, the ambiguity is benign: a local option will have as its
449 context an appropriate source or target, and both global options
450 actually control the same default. However, the option
456 which have separate defaults, and which one you actually get depends on
457 the exact implementation of
459 option parser. (Currently this would resolve to
461 although this may change in a later version.)
463 In this manual, options are usually shown in their fully-qualified form.
465 .SS "File attributes for created files: `fattr'"
470 sources and targets can create new filesystem objects. The
472 options allow control over the attributes of the newly-created objects.
477 use the same set of defaults, so a prefix of
479 is good enough for setting global options, and the implicit context
480 disambiguates local options.
482 The following file attribute options are supported:
483 .OS "File attributes (`fattr')"
484 .IB prefix .fattr.mode
488 Sets the permissions mode for a new file. The
490 argument may be either an octal number or a
492 string which acts on the default permissions established by the
495 setting. The characters
499 do not have to be quoted within the mode string.
501 .OS "File attributes (`fattr')"
502 .IB prefix .fattr.owner
506 Sets the owner for newly created files. On non-broken systems you will
507 need to be the superuser to set the owner on a file. The
509 may either be a numeric uid or a username. The default is not to change
510 the owner of the file once it's created. The synonyms
514 are accepted in place of
517 .OS "File attributes (`fattr')"
518 .IB prefix .fattr.group
522 Sets the group for newly created files. You will usually need to be a
523 member of the group in question order to set the group of a file. The
525 may either be a numeric gid or a group name. The default is not to
526 change the group of the file once it's created. The synonym
528 is accepted in place of
532 .SS "The `file' source and target types"
535 source and target allow data to move to and from objects other
536 than sockets within the Unix filesystem. (Unix-domain sockets are
543 is used as a source, it is set up immediately.
547 sources and targets is like this:
548 .GS "File source and target"
581 .RB [[ : ] name [ : ]]
611 specification describes two files, the first to be used as input, the
612 second to be used as output, each described by an
615 If none of the keywords
620 are given, the type of an
622 is deduced from its nature: if it matches one of the strings
626 or begins with a digit, it's considered to be a file descriptor;
627 otherwise it's interpreted as a filename.
631 spec describes a file by its name within the filesystem. It is opened
632 when needed and closed again after use. For output files, the precise
633 behaviour is controlled by options described below.
637 spec attaches the input or output of the source or target to
642 spec uses an existing open file descriptor, given either by number or a
643 symbolic name. The name
645 refers to standard input (file descriptor 0 on normal systems) and
647 refers to standard output (file descriptor 1). The names work in
648 exactly the same way as the equivalent file descriptor numbers.
652 is omitted, the input
654 is used for both input and output. Exception: if the input refers to
655 standard input then the output will refer to standard output instead.
659 options apply equally to sources and targets. The options are as
666 Whether to create the output file if it doesn't exist. If
668 (the default), an error is reported if the file doesn't exist. If
670 the file is created if it doesn't exist.
675 .BR no | truncate | append
677 Controls the behaviour if the output file already exists. If
679 an error is reported. If
681 (the default), the existing file is replaced by the new data. If
683 the new data is appended to the file.
690 source and target also accept
692 options for controlling the attributes of the created file.
695 Under no circumstances will
697 create a file through a `dangling' symbolic link.
699 .SS "The `exec' source and target types"
702 source and target execute programs and allow access to their standard
703 input and output streams. Both source and target have the same syntax,
705 .GS "Exec source and target"
745 If a single word is given, it is a
747 and will be passed to the Bourne shell for execution. If a
748 bracket-enclosed sequence of words is given, it is considered to be a
749 list of arguments to pass to the program: if a
751 is also supplied, it names the file containing the program to execute;
752 otherwise the file named by the first argument
756 Note that the shell command or program name string must, if present,
757 have any delimiter characters (including
761 quoted; this is not required in the
765 The standard input and output of the program are forwarded to the other
766 end of the connection. The standard error stream is caught by
772 source and target both understand the same set of options. The list of
773 options supported is as follows:
779 Whether to log the start and end of executed programs. If
781 (the default), a log message is emitted when the program is started
782 listing its process id, and another is emitted when the program finishes
783 giving its process id and exit status. If
785 these messages are not emitted. However the standard error stream is
788 abbreviation is accepted as a synonym for
796 Sets the current directory from which the the program should be run.
797 The default is not to change directory. The synonyms
802 are accepted in place of
810 Sets the root directory for the program, using the
812 system call. You must be the superuser for this option to work. The
813 default is not to set a root directory. The synonym
815 is accepted in place of
823 Sets the user (real and effective uid) to run the program as. This will
824 usually require superuser privileges to work. The default is not to
825 change uid. The synonym
827 is accepted in place of
835 Sets the group (real and effective gid) to run the program as. If
836 running with superuser privileges, the supplementary groups list is
837 cleared at the same time. The default is not to change gid (or clear
838 the supplementary groups list). The synonym
840 is accepted in place of
844 .BI exec.rlimit. limit \c
845 .RB [ .hard | .soft ]
849 Set resource limits for the program. The
851 may be one of the resource limit names described in
853 in lower-case and without the
861 is a number, followed optionally by
863 to multiply by 1024 (2\*(ss10\*(se),
865 to multiply by 1048576 (2\*(ss20\*(se), or
867 to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case
868 versions of these if they want. If
872 was specified, only the hard or soft limit is set; otherwise both are
873 set to the same value. Only the superuser can raise the hard limit.
874 The soft limit cannot be set above the hard limit.
879 Clears the program's environment.
887 from the program's environment. It is not an error if no variable named
892 .BR exec.env. [ set ]
901 in the program's environment, possibly replacing the existing value.
904 may be omitted if the
906 qualifier is present.
909 Note that environment variable modifications are performed in order,
910 global modifications before local ones.
912 .SS "The `socket' source and target types"
915 source and target provide access to network services. Support is
916 currently provided for TCP/IP and Unix-domain sockets, although other
917 address types can be added with reasonable ease.
919 The syntax for socket sources and targets is:
920 .GS "Socket source and target"
932 .RB [ socket [ .\& ]]
940 .RB [ socket [ .\& ]]
947 The syntax of the source and target addresses depend on the address
948 types, which are described below. The default address type, if no
953 Socket sources support options; socket targets do not. The source
954 options provided are:
956 .BR socket. [ accept | accept-count ]
961 Controls the number of connections that
963 accepts at a time on a particular socket. This parameter affects how
965 prioritizes between keeping up with connection turnover and processing
966 existing connections. The default is 1, which strongly favours existing
967 connections. The special value
971 removes any limit, and therefore favours connection turnover.
977 .BR unlimited | one-shot
979 Controls the behaviour of the source when it receives connections. A
981 limits the number of simultaneous connections. The value
985 removes any limit on the number of connections possible. The value
987 will remove the socket source after a single successful connection.
988 (Connections refused by access control systems don't count here.)
989 The default is to apply a limit of 256 concurrent connections. Use of
992 option is not recommended.
999 Sets the maximum of the kernel incoming connection queue for this socket
1000 source. This is the number given to the
1002 system call. The default is 5.
1004 .OS "Socket options"
1009 Whether to log incoming connections. If
1011 (the default) incoming connections are logged, together with information
1012 about the client (where available) and whether the connection was
1013 accepted or refused. If
1015 log messages are not generated.
1018 Address types also provide their own options.
1020 .SS "The `inet' socket address type"
1021 .GL "Socket source and target"
1022 .OL "Socket options"
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 .B socket.inet.source.addr
1070 Specify the IP address on which to listen for incoming connections. The
1073 which means to listen on all addresses, though it may be useful to
1074 specify this explicitly, if the global setting is different.
1076 .OS "Socket options"
1077 .BR socket.inet.source. [ allow | deny ]
1083 Adds an entry to the source's access control list. If only one
1085 is given, the entry applies only to that address; if two are given, the
1086 first is a network address and the second is a netmask either in
1087 dotted-quad format or a simple number of bits (e.g.,
1091 mean the same), and the entry applies to any address which, when masked
1092 by the netmask, is equal to the masked network address.
1094 .OS "Socket options"
1095 .BR socket.inet.source. [ allow | deny ]
1098 Accept or reject connections from low-numbered `privileged' ports, in
1101 .OS "Socket options"
1102 .B socket.inet.dest.addr
1107 Specify the IP address to bind the local socket to when making an
1108 outbound connection. The default is
1110 which means to use whichever address the kernel thinks is most
1111 convenient. This option is useful if the destination is doing
1112 host-based access control and your server is multi-homed.
1114 .OS "Socket options"
1115 .B socket.inet.dest.priv-port
1119 Make a privileged connection (i.e., from a low-numbered port) to the
1120 target. This only works if
1122 was started with root privileges. However, it still works if
1126 privileges after initialization (the
1128 option). Before dropping privileges,
1130 forks off a separate process which continues to run with root
1131 privileges, and on demand passes sockets bound to privileged ports and
1132 connected to the appropriate peer back to the main program. The
1133 privileged child only passes back sockets connected to peer addresses
1134 named in the configuration; even if the
1136 process is compromised, it can't make privileged connections to other
1137 addresses. Note that because of this privilege separation, it's also
1138 not possible to reconfigure
1140 to make privileged connections to different peer addresses later by
1141 changing configuration files and sending the daemon a
1145 The access control rules are examined in the order: local entries first,
1146 then global ones, each in the order given in the configuration file.
1147 The first matching entry is used. If no entries match, the behaviour is
1150 of the last entry tried. If there are no entries defined, the default
1151 is to allow all clients.
1153 .SS "The `unix' socket address type"
1154 .GL "Socket source and target"
1155 .OL "Socket options"
1158 address type allows access to Unix-domain sockets. The syntax for
1160 source and target addresses is like this:
1161 .GS "Socket source and target"
1170 The following options are supported by the
1172 source address type:
1173 .OS "Socket options"
1174 .BR socket.unix.fattr. *
1178 source address accepts
1180 options to control the attributes of the socket file created.
1183 Sockets are removed if
1185 exits normally (which it will do if it runs out of sources or
1188 shuts down in a clean way).
1190 To forward the local port 25 to a main mail server:
1192 from 25 to mailserv:25
1194 To attach a fortune server to a Unix-domain socket:
1196 from unix:/tmp/fortunes
1197 to exec [/usr/games/fortune] { user nobody }
1199 To fetch a fortune from the server:
1201 from file stdin, stdout to unix:/tmp/fortunes
1206 from file stdin, null to file null, stdout
1208 .sp -1 \" undo final space
1210 .\"--------------------------------------------------------------------------
1211 .SH "SIGNAL HANDLING"
1215 program responds to various signals when it's running. If it receives
1222 shutdown: it removes all of its sources, and will exit when no more
1223 connections are running. (Note that if the disposition
1227 does not re-enable the signal. You'll have to send
1235 shutdown: it removes all sources and extant connections and closes down
1236 more-or-less immediately.
1238 Finally, if any configuration files (other than standard input) were
1241 on its command line using the
1245 signal may be sent to instruct
1247 to reload its configuration. Any existing connections are allowed to
1248 run their course. If no such configuration files are available,
1250 just logs a message about the signal and continues.
1252 .\"--------------------------------------------------------------------------
1253 .SH "GRAMMAR SUMMARY"
1256 .\"--------------------------------------------------------------------------
1257 .SH "OPTION SUMMARY"
1260 .\"--------------------------------------------------------------------------
1263 The syntax for IP addresses and filenames is nasty. (The filename
1264 syntax used to be even nastier, though.)
1266 IPv6 is not supported yet. Because of
1268 socket address architecture, it's probably not a major piece of work to
1271 Please inform me of any security problems you think you've identified in
1272 this program. I take security very seriously, and I will fix security
1273 holes as a matter of priority when I find out about them. I will be
1274 annoyed if I have to read about problems on Bugtraq because they weren't
1277 The program is too complicated, and this manual page is too long.
1279 .\"--------------------------------------------------------------------------
1282 Mark Wooding, <mdw@distorted.org.uk>
1284 .\"----- That's all, folks --------------------------------------------------
~mdw / fwd / blob