X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/blobdiff_plain/a542396b43f4217f5b76bf884ca1b9080dbd5cfa..9155ea97b695b6eb5fca1ee79f57b334f6c4ef53:/fwd.1.in diff --git a/fwd.1.in b/fwd.1.in new file mode 100644 index 0000000..d596b79 --- /dev/null +++ b/fwd.1.in @@ -0,0 +1,1265 @@ +.\" -*-nroff-*- +.\" +.\" Manual page for fwd +.\" +.\" (c) 1999 Straylight/Edgeware +.\" +. +.\"----- Licensing notice --------------------------------------------------- +.\" +.\" This file is part of the `fwd' port forwarder. +.\" +.\" `fwd' is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" `fwd' is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with `fwd'; if not, write to the Free Software Foundation, +.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. +. +.\"----- Various bits of fancy styling -------------------------------------- +. +.\" --- Indented paragraphs with right-aligned tags --- +. +.de hP +.IP +\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c +.. +. +.\" --- Verbatim-oid typesetting --- +.de VS +.sp 1 +.RS +.nf +.ft B +.. +.de VE +.ft R +.fi +.RE +.sp 1 +.. +. +.\" --- Grammar markup --- +.\" +.\" This is mainly for the benefit of the automatic scripts which +.\" generate the grammar summary. +. +.de GS +.PP +.. +.de GE +.PP +.. +.de GL +.. +. +.de OS +.PP +.. +.de OD +.RS +.. +.de OE +.RE +.. +.de OL +.. +. +.\" --- Other bits of styling --- +. +.ie t \{\ +. ds o \(bu +. ds ss \s8\u +. ds se \d\s0 +. if \n(.g \{\ +. fam P +. \} +.\} +.el \{\ +. ds o o +. ds ss ^ +. ds se +.\} +. +.\"-------------------------------------------------------------------------- +. +.TH fwd 1 "1 July 1999" "Straylight/Edgeware" "fwd port forwarder" +. +.\"-------------------------------------------------------------------------- +.SH NAME +. +fwd \- port forwarder +. +.\"-------------------------------------------------------------------------- +.SH SYNOPSIS +. +.B fwd +.RB [ \-dlq ] +.RB [ \-p +.IR file ] +.RB [ \-f +.IR file ] +.RB [ \-s +.IR user ] +.RB [ \-g +.IR group ] +.IR config-stmt ... +. +.\"-------------------------------------------------------------------------- +.SH "DESCRIPTION" +. +The +.B fwd +program is a simple port forwarder. It supports a number of features +the author hasn't found in similar programs: +.TP +.I "Connection logging" +Each connection attempt to the forwarder is logged, giving the time of +the connection, the DNS-resolved hostname (if available), and the user +name resulting from an RFC931 lookup. These lookups are done +asynchronously to the main forwarder's operation. +.TP +.I "Access control" +Each forwarded port may have an access control list attached to it. +Only authorized hosts are allowed to connect. Access control checks are +performed by quick checks on the client's IP address. +.TP +.I "Nonblocking single-process design" +The internal structure of the server is completely nonblocking. The +connections don't block; the reading and writing don't block; the name +lookups don't block. This is all done in a single process, with the +single exception of the DNS resolver. +.TP +.I "Support for Unix-domain sockets" +Connections from and to Unix-domain sockets can be handled just as +easily as more normal Internet sockets. Access control doesn't work on +Unix domain sockets, though. (Yet.) +.SS "Command line options" +The +.B fwd +program understands a few simple command line options: +.TP +.B "\-h, \-\-help" +Displays a screen of help text on standard output and exits +successfully. +.TP +.B "\-v, \-\-version" +Writes the version number to standard output and exits successfully. +.TP +.B "\-u, \-\-usage" +Writes a terse usage summary to standard output and exits successfully. +.TP +.B "\-G, \-\-grammar" +Writes a summary of the configuration file grammar to standard output +and exits successfully. +.TP +.B "\-O, \-\-options" +Writes a summary of the source and target options to standard output and +exits successfully. +.TP +.BI "\-f, \-\-file=" file +Read configuration information from +.IR file . +Equivalent to an +.RB ` include +.IR file ' +configuration file statement. +.TP +.B "\-d, \-\-daemon, \-\-fork" +Forks into the background after reading the configuration and +initializing properly. +.TP +.B "\-l, \-\-syslog, \-\-log" +Emit logging information to the system log, rather than standard error. +.TP +.BI "\-p, \-\-pidfile=" file +Write +.BR fwd 's +process-id to +.I file +during start-up. If +.B \-d +is given too, then the process-id is written after forking (obviously). +.TP +.B "\-q, \-\-quiet" +Don't output any logging information. This option is not recommended +for normal use, although it can make system call traces clearer so I use +it when debugging. +.TP +.BI "\-s, \-\-setuid=" user +Change uid to that of +.IR user , +which may be either a user name or uid number, after initializing all +the sources. This will usually require elevated privileges. +.TP +.BI "\-g, \-\-setgid=" group +Change gid to that of +.IR group , +which may be either a group name or gid number, after initializing all +the sources. If the operating system understands supplementary groups +then the supplementary groups list is altered to include only +.IR group . +.PP +Any further command line arguments are interpreted as configuration +lines to be read. Configuration supplied in command line arguments has +precisely the same syntax as configuration in files. If there are no +configuration statements on the command line, and no +.B \-f +options were supplied, configuration is read from standard input, if +stdin is not a terminal. +. +.\"-------------------------------------------------------------------------- +.SH "CONFIGURATION LANGUAGE" +. +The +.B fwd +program has a fairly sophisticated configuration language to let you +describe which things should be forwarded where and what special +features there should be. +.SS "Lexical structure" +There are four types of characters. +.TP +.I "word constituent characters" +Word constituent characters are gathered together into words. +Depending on its surrounding context, a word might act as a keyword or a +string. All alphanumerics are word constituents, as is the hyphen +.RB ` \- '. +Other characters may change their status in future versions. +.TP +.I "self-delimiting characters" +Self-delimiting characters always stand alone. They act as punctuation, +shaping the sequence of words into more complex grammatical forms. The +characters +.RB ` { ', +.RB ` } ', +.RB ` [ ', +.RB ` ] ', +.RB ` / ', +.RB ` , ', +.RB ` = ', +.RB ` : ', +.RB ` ; ' +and +.RB ` . ' +are self-delimiting. Note that while some characters, e.g., +.RB ` [ ' +and +.RB ` ; ', +require escaping by the shell, they are mostly optional in the grammar +and can tend to be omitted in quick hacks at the shell prompt. +.TP +.I "whitespace characters" +Whitespace characters separate words but are otherwise ignored. All +`normal' whitespace characters (e.g., space, tab and newline) are +considered to be whitespace for these purposes. +.TP +.I "special characters" +There are three special characters. The +.RB ` # ' +character, if it appears at the start of a word, introduces a +.I comment +which extends to the end of the current line or command-line argument. +Within a word, it behaves like a normal word-constituent character. The +backslash +.RB ` \e ' +escapes the following character causing it to be interpreted as a word +constituent regardless of its normal type. The double-quote +.RB ` """" ' +escapes all characters other than backslashes up to the next +double-quote and causes them to be regarded as word constituents. Note +that you don't have to quote a whole word. The backslash can escape a +quote character allowing you to insert it into a word if really +necessary. +. +.SS "Basic syntax" +The overall syntax looks a bit like this: +.GS "Basic syntax" +.I file +::= +.I empty +| +.I file +.I stmt +.RB [ ; ] +.br +.I stmt +::= +.I option-stmt +| +.I fwd-stmt +.br +.I fwd-stmt +::= +.B fwd +.I source +.I options +.RB [ to | \-> ] +.I target +.I options +.br +.I options +::= +.B { +.I option-seq +.B } +.br +.I option-seq +::= +.I empty +| +.I option-stmt +.RB [ ; ] +.I option-seq +.GE +If you prefer, the keyword +.RB ` fwd ' +may be spelt +.RB ` fwd ', +.RB ` forward ', +or +.RB ` from '. +All are equivalent. +. +.SS "Sources and targets" +Forwarding is set up by attaching +.I targets +to +.IR sources . +Sources are things which are capable of +.I initiating +one end of a data flow on their own, while targets are things which are +capable of setting up the other end on demand. In the case of a TCP +port forwarder, the part which listens for incoming client connections +is the source, while the part which sets up outgoing connections to the +destination server is the target. +.PP +Essentially, all +.B fwd +does is set up a collection of sources and targets based on your +configuration file so that when a source decides to initiate a data +flow, it tells its target to set its end up, and then squirts data back +and forth between the two until there's no more. +.PP +Some sources are +.IR persistent : +they stay around indefinitely setting up multiple attachments to +targets. Others are +.IR transient : +they set up one connection and then disappear. If all the sources +defined are transient, then +.B fwd +will quit when no more active sources remain and all connections have +terminated. +.PP +The +.B fwd +program is fairly versatile. It allows you to attach any supported type +of source to any supported type of target. This will, I hope, be the +case in all future versions. +.PP +The syntax of a +.I source +or +.I target +depend on the source or target type, and are therefore described in the +sections specific to the various types. +. +.SS "Options structure" +Most of the objects that +.B fwd +knows about (including sources and targets, but also other more specific +things such as socket address types) can have their behaviour modified +by +.IR options . +The options available at a particular point in the configuration depend +on the +.IR context . +A global option, outside of a +.I fwd-stmt +has no context unless it is explicitly qualified, and affects global +behaviour. A local option, applied to a source or target in a +.IR fwd-stmt , +has the context of the type of source or target to which it is applied, +and affects only that source or target. +.PP +Note that it's important to distinguish between an option's context +(which is affected by its qualification) and its local or global +status. No matter how qualified, a global option will always control +default options for objects, and a local option will only affect a +specific source or target. +.PP +The syntax for qualifying options is like this: +.GS "Option syntax" +.I option-stmt +::= +.I q-option +.br +.I q-option +::= +.I option +.br + | +.I prefix +.B .\& +.I q-option +.br + | +.I prefix +.B { +.I option-seq +.B } +.br +.I prefix +::= +.I word +.GE +Thus, you may qualify either an individual option or a sequence of +options. The two are equivalent; for example, +.VS +exec.rlimit { + core = 0; + cpu = 60; +} +.VE +means the same as +.VS +exec.rlimit.core = 0; +exec.rlimit.cpu = 0; +.VE +For each option, there is a sequence of prefixes which maximally qualify +that option. An option prefixed with this sequence is +.IR "fully qualified" . +In actual use, some or all of those prefixes may be omitted. However, +it's possible for the option to become +.I ambiguous +if you do this. For example, the option +.B fattr.owner +may refer either to +.B file.fattr.owner +or to +.BR socket.unix.fattr.owner . +In this case, the ambiguity is benign: a local option will have as its +context an appropriate source or target, and both global options +actually control the same default. However, the option +.B logging +may mean either +.B socket.logging +or +.BR exec.logging , +which have separate defaults, and which one you actually get depends on +the exact implementation of +.BR fwd 's +option parser. (Currently this would resolve to +.BR exec.logging , +although this may change in a later version.) +.PP +In this manual, options are usually shown in their fully-qualified form. +. +.SS "File attributes for created files: `fattr'" +Both the +.B file +and +.B socket +sources and targets can create new filesystem objects. The +.B fattr +options allow control over the attributes of the newly-created objects. +Both +.B file +and +.B socket +use the same set of defaults, so a prefix of +.B fattr +is good enough for setting global options, and the implicit context +disambiguates local options. +.PP +The following file attribute options are supported: +.OS "File attributes (`fattr')" +.IB prefix .fattr.mode +.RB [ = ] +.I mode +.OD +Sets the permissions mode for a new file. The +.I mode +argument may be either an octal number or a +.BR chmod (1)-style +string which acts on the default permissions established by the +prevailing +.BR umask (2) +setting. The characters +.RB ` = ' +and +.RB ` , ' +do not have to be quoted within the mode string. +.OE +.OS "File attributes (`fattr')" +.IB prefix .fattr.owner +.RB [ = ] +.I user +.OD +Sets the owner for newly created files. On non-broken systems you will +need to be the superuser to set the owner on a file. The +.I user +may either be a numeric uid or a username. The default is not to change +the owner of the file once it's created. The synonyms +.B uid +and +.B user +are accepted in place of +.BR owner . +.OE +.OS "File attributes (`fattr')" +.IB prefix .fattr.group +.RB [ = ] +.I group +.OD +Sets the group for newly created files. You will usually need to be a +member of the group in question order to set the group of a file. The +.I group +may either be a numeric gid or a group name. The default is not to +change the group of the file once it's created. The synonym +.B gid +is accepted in place of +.BR group . +.OE +. +.SS "The `file' source and target types" +The +.B file +source and target allow data to move to and from objects other +than sockets within the Unix filesystem. (Unix-domain sockets are +handled using the +.B socket +source and target.) +.PP +If a +.B file +is used as a source, it is set up immediately. +.PP +The syntax of +.B file +sources and targets is like this: +.GS "File source and target" +.I source +::= +.I file +.br +.I target +::= +.I file +.br +.I file +::= +.B file +.RB [ .\& ] +.I fspec +.RB [ , +.IR fspec ] +.br +.I fspec +::= +.I fd-spec +| +.I name-spec +| +.I null-spec +.br +.I fd-spec +::= +.RB [[ : ] fd [ : ]] +.IR number \c +.RB | stdin | stdout +.br +.I name-spec +::= +.RB [[ : ] name [ : ]] +.I file-name +.br +.I file-name +::= +.I path-seq +| +.B [ +.I path-seq +.B ] +.br +.I path-seq +::= +.I path-elt +| +.I path-seq +.I path-elt +.br +.I path-elt +::= +.B / +| +.I word +.br +.I null-spec +::= +.RB [ : ] null [ : ] +.GE +The +.I file +specification describes two files, the first to be used as input, the +second to be used as output, each described by an +.IR fspec . +.PP +If none of the keywords +.RB ` fd ', +.RB ` name ' +or +.RB ` null ' +are given, the type of an +.I fspec +is deduced from its nature: if it matches one of the strings +.RB ` stdin ' +or +.RB ` stdout ', +or begins with a digit, it's considered to be a file descriptor; +otherwise it's interpreted as a filename. +.PP +A +.RB ` name ' +spec describes a file by its name within the filesystem. It is opened +when needed and closed again after use. For output files, the precise +behaviour is controlled by options described below. +.PP +A +.RB ` null ' +spec attaches the input or output of the source or target to +.BR /dev/null . +.PP +An +.RB ` fd ' +spec uses an existing open file descriptor, given either by number or a +symbolic name. The name +.RB ` stdin ' +refers to standard input (file descriptor 0 on normal systems) and +.RB ` stdout ' +refers to standard output (file descriptor 1). The names work in +exactly the same way as the equivalent file descriptor numbers. +.PP +If the output +.I fspec +is omitted, the input +.I fspec +is used for both input and output. Exception: if the input refers to +standard input then the output will refer to standard output instead. +.PP +All +.B file +options apply equally to sources and targets. The options are as +follows: +.OS "File options" +.B file.create +.RB [ = ] +.BR yes | no +.OD +Whether to create the output file if it doesn't exist. If +.B no +(the default), an error is reported if the file doesn't exist. If +.BR yes , +the file is created if it doesn't exist. +.OE +.OS "File options" +.B file.open +.RB [ = ] +.BR no | truncate | append +.OD +Controls the behaviour if the output file already exists. If +.BR no , +an error is reported. If +.B truncate +(the default), the existing file is replaced by the new data. If +.BR append , +the new data is appended to the file. +.OE +.OS "File options" +.BR file.fattr. * +.OD +The +.B file +source and target also accept +.B fattr +options for controlling the attributes of the created file. +.OE +.PP +Under no circumstances will +.B fwd +create a file through a `dangling' symbolic link. +. +.SS "The `exec' source and target types" +The +.B exec +source and target execute programs and allow access to their standard +input and output streams. Both source and target have the same syntax, +which is as follows: +.GS "Exec source and target" +.I source +::= +.I exec +.br +.I target +::= +.I exec +.br +.I exec +::= +.BR exec +.RB [ .\& ] +.I cmd-spec +.br +.I cmd-spec +::= +.I shell-cmd +| +.RI [ prog-name ] +.B [ +.I argv0 +.I arg-seq +.B ] +.br +.I arg-seq +::= +.I word +| +.I arg-seq +.I word +.br +.I shell-cmd +::= +.I word +.br +.I argv0 +::= +.I word +.GE +If a single word is given, it is a +.I shell-cmd +and will be passed to the Bourne shell for execution. If a +bracket-enclosed sequence of words is given, it is considered to be a +list of arguments to pass to the program: if a +.I prog-name +is also supplied, it names the file containing the program to execute; +otherwise the file named by the first argument +.RI ( argv0 ) +is used. +.PP +Note that the shell command or program name string must, if present, +have any delimiter characters (including +.RB ` / ' +and +.RB ` . ') +quoted; this is not required in the +.RB ` [ '-enclosed +argument list. +.PP +The standard input and output of the program are forwarded to the other +end of the connection. The standard error stream is caught by +.B fwd +and logged. +.PP +The +.B exec +source and target both understand the same set of options. The list of +options supported is as follows: +.OS "Exec options" +.B exec.logging +.RB [ = ] +.BR yes | no +.OD +Whether to log the start and end of executed programs. If +.B yes +(the default), a log message is emitted when the program is started +listing its process id, and another is emitted when the program finishes +giving its process id and exit status. If +.BR no , +these messages are not emitted. However the standard error stream is +still logged. The +.B log +abbreviation is accepted as a synonym for +.BR logging . +.OE +.OS "Exec options" +.B exec.dir +.RB [ = ] +.I file-name +.OD +Sets the current directory from which the the program should be run. +The default is not to change directory. The synonyms +.BR cd , +.B chdir +and +.B cwd +are accepted in place of +.BR dir . +.OE +.OS "Exec options" +.B exec.root +.RB [ = ] +.I file-name +.OD +Sets the root directory for the program, using the +.BR chroot (2) +system call. You must be the superuser for this option to work. The +default is not to set a root directory. The synonym +.B chroot +is accepted in place of +.BR root . +.OE +.OS "Exec options" +.B exec.user +.RB [ = ] +.I user +.OD +Sets the user (real and effective uid) to run the program as. This will +usually require superuser privileges to work. The default is not to +change uid. The synonym +.B uid +is accepted in place of +.BR user . +.OE +.OS "Exec options" +.B exec.group +.RB [ = ] +.I group +.OD +Sets the group (real and effective gid) to run the program as. If +running with superuser privileges, the supplementary groups list is +cleared at the same time. The default is not to change gid (or clear +the supplementary groups list). The synonym +.B gid +is accepted in place of +.BR group . +.OE +.OS "Exec options" +.BI exec.rlimit. limit \c +.RB [ .hard | .soft ] +.RB [ = ] +.I value +.OD +Set resource limits for the program. The +.I limit +may be one of the resource limit names described in +.BR setrlimit (2), +in lower-case and without the +.B RLIMIT_ +prefix; for example, +.B RLIMIT_CORE +becomes simply +.BR core . +The +.I value +is a number, followed optionally by +.B k +to multiply by 1024 (2\*(ss10\*(se), +.B m +to multiply by 1048576 (2\*(ss20\*(se), or +.B g +to multiply by 1073741824 (2\*(ss30\*(se); purists can use upper-case +versions of these if they want. If +.B .hard +or +.B .soft +was specified, only the hard or soft limit is set; otherwise both are +set to the same value. Only the superuser can raise the hard limit. +The soft limit cannot be set above the hard limit. +.OE +.OS "Exec options" +.B exec.env.clear +.OD +Clears the program's environment. +.OE +.OS "Exec options" +.B exec.env.unset +.I var +.OD +Removes +.I var +from the program's environment. It is not an error if no variable named +.I var +exists. +.OE +.OS "Exec options" +.BR exec.env. [ set ] +.I var +.RB [ = ] +.I value +.OD +Assigns the variable +.I var +the value +.I value +in the program's environment, possibly replacing the existing value. +The +.B set +may be omitted if the +.B env +qualifier is present. +.OE +.PP +Note that environment variable modifications are performed in order, +global modifications before local ones. +. +.SS "The `socket' source and target types" +The +.B socket +source and target provide access to network services. Support is +currently provided for TCP/IP and Unix-domain sockets, although other +address types can be added with reasonable ease. +.PP +The syntax for socket sources and targets is: +.GS "Socket source and target" +.ll +8i +.I source +::= +.I socket-source +.br +.I target +::= +.I socket-target +.br +.I socket-source +::= +.RB [ socket [ .\& ]] +.RB [[ : ] \c +.IR addr-type \c +.RB [ : ]] +.I source-addr +.br +.I socket-target +::= +.RB [ socket [ .\& ]] +.RB [[ : ] \c +.IR addr-type \c +.RB [ : ]] +.I target-addr +.ll -8i +.GE +The syntax of the source and target addresses depend on the address +types, which are described below. The default address type, if no +.I addr-type +is given, is +.BR inet . +.PP +Socket sources support options; socket targets do not. The source +options provided are: +.OS "Socket options" +.B socket.conn +.RB [ = ] +.IR number | \c +.BR unlimited | one-shot +.OD +Controls the behaviour of the source when it receives connections. A +.I number +limits the number of simultaneous connections. The value +.B unlimited +(or +.BR infinite ) +removes any limit on the number of connections possible. The value +.B one-shot +will remove the socket source after a single successful connection. +(Connections refused by access control systems don't count here.) +The default is to apply a limit of 256 concurrent connections. Use of +the +.B unlimited +option is not recommended. +.OE +.OS "Socket options" +.B socket.listen +.RB [ = ] +.I number +.OD +Sets the maximum of the kernel incoming connection queue for this socket +source. This is the number given to the +.BR listen (2) +system call. The default is 5. +.OE +.OS "Socket options" +.B socket.logging +.RB [ = ] +.BR yes | no +.OD +Whether to log incoming connections. If +.B yes +(the default) incoming connections are logged, together with information +about the client (where available) and whether the connection was +accepted or refused. If +.BR no , +log messages are not generated. +.OE +.PP +Address types also provide their own options. +. +.SS "The `inet' socket address type" +.GL "Socket source and target" +.OL "Socket options" +The +.B inet +address type provides access to TCP ports. The +.B inet +source and target addresses have the following syntax: +.GS "Socket source and target" +.I inet-source-addr +::= +.RB [ port ] +.I port +.br +.I inet-target-addr +::= +.I address +.RB [ : ] +.I port +.br +.I address +::= +.I addr-elt +| +.I address +.I addr-elt +.br +.I addr-elt +::= +.B .\& +| +.I word +.GE +A +.I port +may be given as a port number or a service name from the +.B /etc/services +file (or YP map if you do that sort of thing). A +.B hostname +may be a textual hostname or a numerical IP address. +.PP +The +.B inet +source address accepts the following options: +.OS "Socket options" +.B socket.inet.source.addr +.RB [ = ] +.BR any | \c +.I addr +.OD +Specify the IP address on which to listen for incoming connections. The +default is +.BR any , +which means to listen on all addresses, though it may be useful to +specify this explicitly, if the global setting is different. +.OE +.OS "Socket options" +.BR socket.inet.source. [ allow | deny ] +.RB [ host ] +.I addr +.RB [ / +.IR addr ] +.OD +Adds an entry to the source's access control list. If only one +.I address +is given, the entry applies only to that address; if two are given, the +first is a network address and the second is a netmask either in +dotted-quad format or a simple number of bits (e.g., +.B /255.255.255.192 +and +.B /26 +mean the same), and the entry applies to any address which, when masked +by the netmask, is equal to the masked network address. +.OE +.OS "Socket options" +.BR socket.inet.source. [ allow | deny ] +.B priv-port +.OD +Accept or reject connections from low-numbered `privileged' ports, in +the range 0--1023. +.OE +.OS "Socket options" +.B socket.inet.dest.addr +.RB [ = ] +.BR any | \c +.I addr +.OD +Specify the IP address to bind the local socket to when making an +outbound connection. The default is +.BR any , +which means to use whichever address the kernel thinks is most +convenient. This option is useful if the destination is doing +host-based access control and your server is multi-homed. +.OE +.OS "Socket options" +.B socket.inet.dest.priv-port +.RB [=] +.BR yes | no +.OD +Make a privileged connection (i.e., from a low-numbered port) to the +target. This only works if +.B fwd +was started with root privileges. However, it still works if +.B fwd +has +.I dropped +privileges after initialization (the +.B \-s +option). Before dropping privileges, +.B fwd +forks off a separate process which continues to run with root +privileges, and on demand passes sockets bound to privileged ports and +connected to the appropriate peer back to the main program. The +privileged child only passes back sockets connected to peer addresses +named in the configuration; even if the +.B fwd +process is compromised, it can't make privileged connections to other +addresses. Note that because of this privilege separation, it's also +not possible to reconfigure +.B fwd +to make privileged connections to different peer addresses later by +changing configuration files and sending the daemon a +.BR SIGHUP . +.OE +.PP +The access control rules are examined in the order: local entries first, +then global ones, each in the order given in the configuration file. +The first matching entry is used. If no entries match, the behaviour is +the +.I opposite +of the last entry tried. If there are no entries defined, the default +is to allow all clients. +. +.SS "The `unix' socket address type" +.GL "Socket source and target" +.OL "Socket options" +The +.B unix +address type allows access to Unix-domain sockets. The syntax for +.B unix +source and target addresses is like this: +.GS "Socket source and target" +.I unix-source-addr +::= +.I file-name +.br +.I unix-target-addr +::= +.I file-name +.GE +The following options are supported by the +.B unix +source address type: +.OS "Socket options" +.BR socket.unix.fattr. * +.OD +The +.B unix +source address accepts +.B fattr +options to control the attributes of the socket file created. +.OE +.PP +Sockets are removed if +.B fwd +exits normally (which it will do if it runs out of sources or +connections, or if +.B fwd +shuts down in a clean way). +.SH "EXAMPLES" +To forward the local port 25 to a main mail server: +.VS +from 25 to mailserv:25 +.VE +To attach a fortune server to a Unix-domain socket: +.VS +from unix:/tmp/fortunes +to exec [/usr/games/fortune] { user nobody } +.VE +To fetch a fortune from the server: +.VS +from file stdin, stdout to unix:/tmp/fortunes +.VE +To emulate +.BR cat (1): +.VS +from file stdin, null to file null, stdout +.VE +.sp -1 \" undo final space +. +.\"-------------------------------------------------------------------------- +.SH "SIGNAL HANDLING" +. +The +.B fwd +program responds to various signals when it's running. If it receives +.B SIGTERM +or +.BR SIGINT , +.B fwd +performs a +.I graceful +shutdown: it removes all of its sources, and will exit when no more +connections are running. (Note that if the disposition +.B SIGINT +was to ignore it, +.B fwd +does not re-enable the signal. You'll have to send +.B SIGTERM +in that case.) If +.B fwd +receives +.BR SIGQUIT , +it performs an +.I abrupt +shutdown: it removes all sources and extant connections and closes down +more-or-less immediately. +.PP +Finally, if any configuration files (other than standard input) were +provided to +.B fwd +on its command line using the +.B \-f +option, a +.B SIGHUP +signal may be sent to instruct +.B fwd +to reload its configuration. Any existing connections are allowed to +run their course. If no such configuration files are available, +.B fwd +just logs a message about the signal and continues. +. +.\"-------------------------------------------------------------------------- +.SH "GRAMMAR SUMMARY" +. +@@@ grammar +.\"-------------------------------------------------------------------------- +.SH "OPTION SUMMARY" +. +@@@ option +.\"-------------------------------------------------------------------------- +.SH "BUGS" +. +The syntax for IP addresses and filenames is nasty. +.PP +IPv6 is not supported yet. Because of +.BR fwd 's +socket address architecture, it's probably not a major piece of work to +add. +.PP +Please inform me of any security problems you think you've identified in +this program. I take security very seriously, and I will fix security +holes as a matter of priority when I find out about them. I will be +annoyed if I have to read about problems on Bugtraq because they weren't +mailed to me first. +.PP +The program is too complicated, and this manual page is too long. +. +.\"-------------------------------------------------------------------------- +.SH "AUTHOR" +. +Mark Wooding, +. +.\"----- That's all, folks --------------------------------------------------