X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/blobdiff_plain/f65809f707319adc063bc77a68547bc82af3b0e2..8cf7c7c277cbdea379003dc8e872392b8c519c7d:/fw.1 diff --git a/fw.1 b/fw.1 deleted file mode 100644 index 51dc460..0000000 --- a/fw.1 +++ /dev/null @@ -1,1577 +0,0 @@ -.\" -*-nroff-*- -.\" -.\" $Id$ -.\" -.\" Manual page for fw -.\" -.\" (c) 1999 Straylight/Edgeware -.\" -. -.\"----- Licensing notice --------------------------------------------------- -.\" -.\" This file is part of the `fw' port forwarder. -.\" -.\" `fw' 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. -.\" -.\" `fw' 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 `fw'; 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 OS -.PP -.. -.de OD -.RS -.. -.de OE -.RE -.. -. -.\" --- 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 fw 1 "1 July 1999" "Straylight/Edgeware" "fw port forwarder" -. -.\"-------------------------------------------------------------------------- -.SH NAME -. -fw \- port forwarder -. -.\"-------------------------------------------------------------------------- -.SH SYNOPSIS -. -.B fw -.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 fw -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 fw -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 fw '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 fw -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 fw-stmt -.br -.I fw-stmt -::= -.B fw -.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 ` fw ' -may be spelt -.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 fw -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 fw -will quit when no more active sources remain and all connections have -terminated. -.PP -The -.B fw -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 fw -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 fw-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 fw-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 fw '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 attribute options (`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 attribute options (`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 attribute options (`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 sources and targets" -.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 fw -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 -::= -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 fw -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 -.PP -.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" -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 [ = ] -.RR 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 [ = ] -.RR 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 fw -was started with root privileges. However, it still works if -.B fw -has -.I dropped -privileges after initialization (the -.B \-s -option). Before dropping privileges, -.B fw -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 fw -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 fw -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" -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 fw -exits normally (which it will do if it runs out of sources or -connections, or if -.B fw -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 fw -program responds to various signals when it's running. If it receives -.B SIGTERM -or -.BR SIGINT , -.B fw -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 fw -does not re-enable the signal. You'll have to send -.B SIGTERM -in that case.) If -.B fw -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 fw -on its command line using the -.B \-f -option, a -.B SIGHUP -signal may be sent to instruct -.B fw -to reload its configuration. Any existing connections are allowed to -run their course. If no such configuration files are available, -.B fw -just logs a message about the signal and continues. -. -.\"-------------------------------------------------------------------------- -.SH "GRAMMAR SUMMARY" -. -.SS "Basic syntax" -.I file -::= -.I empty -| -.I file -.I stmt -.RB [ ; ] -.br -.I stmt -::= -.I option-stmt -| -.I fw-stmt -.br -.I fw-stmt -::= -.B fw -.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 -. -.SS "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 -. -.SS "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 [ : ] -. -.SS "Exec source and target" -.I source -::= -.I exec -.br -.I target -::= -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 -. -.SS "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 -.PP -.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 -.PP -.I unix-source-addr -::= -.I file-name -.br -.I unix-target-addr -::= -.I file-name -. -.\"-------------------------------------------------------------------------- -.SH "OPTION SUMMARY" -. -.SS "File attributes (`fattr')" -.IB prefix .fattr.mode -.RB [ = ] -.I mode -.br -.IB prefix .fattr.owner -.RB [ = ] -.I user -.br -.IB prefix .fattr.group -.RB [ = ] -.I group -. -.SS "File options" -.B file.create -.RB [ = ] -.BR yes | no -.br -.B file.open -.RB [ = ] -.BR no | truncate | append -.br -.BR file.fattr. * -. -.SS "Exec options" -.B exec.logging -.RB [ = ] -.BR yes | no -.br -.B exec.dir -.RB [ = ] -.I file-name -.br -.B exec.root -.RB [ = ] -.I file-name -.br -.B exec.user -.RB [ = ] -.I user -.br -.B exec.group -.RB [ = ] -.I group -.br -.BI exec.rlimit. limit \c -.RB [ .hard | .soft ] -.RB [ = ] -.I value -.br -.B exec.env.clear -.br -.B exec.env.unset -.I var -.br -.BR exec.env. [ set ] -.I var -.RB [ = ] -.I value -. -.SS "Socket options" -.B socket.conn -.RB [ = ] -.IR number | \c -.BR unlimited | one-shot -.br -.B socket.listen -.RB [ = ] -.I number -.br -.B socket.logging -.RB [ = ] -.BR yes | no -.PP -.BR socket.inet.source. [ allow | deny ] -.RB [ host ] -.I addr -.RB [ / -.IR addr ] -.br -.BR socket.inet.source. [ allow | deny ] -.B priv-port -.br -.B socket.inet.source.addr -.RB [ = ] -.BR any | \c -.I addr -.br -.B socket.inet.dest.addr -.RB [ = ] -.BR any | \c -.I addr -.br -.B socket.inet.dest.priv-port -.RB [=] -.BR yes | no -.PP -.BR socket.unix.fattr. * -. -.\"-------------------------------------------------------------------------- -.SH "BUGS" -. -The syntax for IP addresses and filenames is nasty. -.PP -IPv6 is not supported yet. Because of -.BR fw '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 --------------------------------------------------