From: mdw Date: Sun, 10 Oct 1999 16:46:29 +0000 (+0000) Subject: Include grammar and options references at the end of the manual. X-Git-Tag: 1.2.0~10 X-Git-Url: https://git.distorted.org.uk/~mdw/fwd/commitdiff_plain/333c51f409d9d8c3ed7bc8b46c1111c6c39ee743 Include grammar and options references at the end of the manual. --- diff --git a/fw.1 b/fw.1 index 5c596e1..885d5b9 100644 --- a/fw.1 +++ b/fw.1 @@ -1,6 +1,6 @@ .\" -*-nroff-*- .\" -.\" $Id: fw.1,v 1.5 1999/09/26 18:18:05 mdw Exp $ +.\" $Id: fw.1,v 1.6 1999/10/10 16:46:29 mdw Exp $ .\" .\" Manual page for fw .\" @@ -28,6 +28,9 @@ .\" ---- Revision history --------------------------------------------------- .\" .\" $Log: fw.1,v $ +.\" Revision 1.6 1999/10/10 16:46:29 mdw +.\" Include grammar and options references at the end of the manual. +.\" .\" Revision 1.5 1999/09/26 18:18:05 mdw .\" Remove a fixed bug from the list. Fix some nasty formatting .\" misfeatures. @@ -66,6 +69,28 @@ .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 \{\ @@ -234,7 +259,7 @@ necessary. . .SS "Basic syntax" The overall syntax looks a bit like this: -.PP +.GS "Basic syntax" .I file ::= .I empty @@ -271,7 +296,7 @@ The overall syntax looks a bit like this: .I option-stmt .RB [ ; ] .I option-seq -.PP +.GE If you prefer, the keyword .RB ` fw ' may be spelt @@ -349,7 +374,7 @@ 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: -.PP +.GS "Option syntax" .I option-stmt ::= .I q-option @@ -372,7 +397,7 @@ The syntax for qualifying options is like this: .I prefix ::= .I word -.PP +.GE Thus, you may qualify either an individual option or a sequence of options. The two are equivalent; for example, .VS @@ -415,6 +440,73 @@ 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 @@ -431,7 +523,7 @@ is used as a source, it is set up immediately. The syntax of .B file sources and targets is like this: -.PP +.GS "File sources and targets" .I source ::= .I file @@ -491,7 +583,7 @@ sources and targets is like this: .I null-spec ::= .RB [ : ] null [ : ] -.PP +.GE The .I file specification describes two files, the first to be used as input, the @@ -544,22 +636,22 @@ All .B file options apply equally to sources and targets. The options are as follows: -.PP +.OS "File options" .B file.create .RB [ = ] .BR yes | no -.RS +.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. -.RE -.PP +.OE +.OS "File options" .B file.open .RB [ = ] .BR no | truncate | append -.RS +.OD Controls the behaviour if the output file already exists. If .BR no , an error is reported. If @@ -567,86 +659,20 @@ an error is reported. If (the default), the existing file is replaced by the new data. If .BR append , the new data is appended to the file. -.RE -.PP -Under no circumstances will -.B fw -create a file through a `dangling' symbolic link. -.PP +.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. The prefix -for setting file attributes is -.BR file.fattr . -. -.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: -.PP -.IB prefix .fattr.mode -.RB [ = ] -.I mode -.RS -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. -.RE -.PP -.IB prefix .fattr.owner -.RB [ = ] -.I user -.RS -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 . -.RE +options for controlling the attributes of the created file. +.OE .PP -.IB prefix .fattr.group -.RB [ = ] -.I group -.RS -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 . -.RE +Under no circumstances will +.B fw +create a file through a `dangling' symbolic link. . .SS "The `exec' source and target types" The @@ -654,7 +680,7 @@ The 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: -.PP +.GS "Exec source and target" .I source ::= .I exec @@ -693,7 +719,7 @@ exec .I argv0 ::= .I word -.PP +.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 @@ -714,11 +740,11 @@ The .B exec source and target both understand the same set of options. The list of options supported is as follows: -.PP +.OS "Exec options" .B exec.logging .RB [ = ] .BR yes | no -.RS +.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 @@ -730,12 +756,12 @@ still logged. The .B log abbreviation is accepted as a synonym for .BR logging . -.RE -.PP +.OE +.OS "Exec options" .B exec.dir .RB [ = ] .I file-name -.RS +.OD Sets the current directory from which the the program should be run. The default is not to change directory. The synonyms .BR cd , @@ -744,12 +770,12 @@ and .B cwd are accepted in place of .BR dir . -.RE -.PP +.OE +.OS "Exec options" .B exec.root .RB [ = ] .I file-name -.RS +.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 @@ -760,24 +786,24 @@ and .B cwd are accepted in place of .B dir . -.RE -.PP +.OE +.OS "Exec options" .B exec.user .RB [ = ] .I user -.RS +.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 . -.RE -.PP +.OE +.OS "Exec options" .B exec.group .RB [ = ] .I group -.RS +.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 @@ -785,13 +811,13 @@ the supplementary groups list). The synonym .B gid is accepted in place of .BR group . -.RE -.PP +.OE +.OS "Exec options" .BI exec.rlimit. limit \c .RB [ .hard | .soft ] .RB [ = ] .I value -.RS +.OD Set resource limits for the program. The .I limit may be one of the resource limit names described in @@ -818,28 +844,28 @@ or 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. -.RE -.PP +.OE +.OS "Exec options" .B exec.env.clear -.RS +.OD Clears the program's environment. -.RE +.OE .PP .B exec.env.unset .I var -.RS +.OD Removes .I var from the program's environment. It is not an error if no variable named .I var exists. -.RE -.PP +.OE +.OS "Exec options" .BR exec.env. [ set ] .I var .RB [ = ] .I value -.RS +.OD Assigns the variable .I var the value @@ -850,7 +876,7 @@ The may be omitted if the .B env qualifier is present. -.RE +.OE .PP Note that environment variable modifications are performed in order, global modifications before local ones. @@ -863,7 +889,7 @@ 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: -.PP +.GS "Socket source and target" .ll +8i .I source ::= @@ -889,7 +915,7 @@ The syntax for socket sources and targets is: .RB [ : ]] .I target-addr .ll -8i -.PP +.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 @@ -898,20 +924,20 @@ is given, is .PP Socket sources support options; socket targets do not. The source options provided are: -.PP +.OS "Socket options" .B socket.conn .RB [ = ] .I number -.RS +.OD Limits the number of simultaneous connections to this socket to the .I number given. The default is 256. -.RE -.PP +.OE +.OS "Socket options" .B socket.logging .RB [ = ] .BR yes | no -.RS +.OD Whether to log incoming connections. If .B yes (the default) incoming connections are logged, together with information @@ -919,7 +945,7 @@ about the client (where available) and whether the connection was accepted or refused. If .BR no , log messages are not generated. -.RE +.OE .PP Address types also provide their own options. . @@ -929,7 +955,7 @@ The address type provides access to TCP ports. The .B inet source and target addresses have the following syntax: -.PP +.GS "Socket source and target" .I inet-source-addr ::= .RB [ port ] @@ -953,7 +979,7 @@ source and target addresses have the following syntax: .B . | .I word -.PP +.GE A .I port may be given as a port number or a service name from the @@ -965,13 +991,13 @@ may be a textual hostname or a numerical IP address. The .B inet source address accepts the following options: -.PP +.OS "Socket options" .BR socket.inet. [ allow | deny ] .RB [ from ] .I address .RB [ / .IR address ] -.RS +.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 @@ -982,15 +1008,15 @@ 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 .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 +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. -.RE . .SS "The `unix' socket address type" The @@ -998,25 +1024,29 @@ The address type allows access to Unix-domain sockets. The syntax for .B unix source and target addresses is like this: -.PP -.I source-addr +.GS "Socket source and target" +.I unix-source-addr ::= -.I unix-addr -.br -.I target-addr -::= -.I unix-addr +.I file-name .br -.I unix-addr +.I unix-target-addr ::= .I file-name -.PP +.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. Sockets -are removed if +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 killed by SIGINT or SIGTERM). @@ -1041,6 +1071,311 @@ from stdin, null to null, stdout .VE . .\"-------------------------------------------------------------------------- +.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 [[ : ] file [ : ]] +.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 [ = ] +.I number +.br +.B socket.logging +.RB [ = ] +.BR yes | no +.PP +.BR socket.inet. [ allow | deny ] +.RB [ from ] +.I address +.RB [ / +.IR address ] +.PP +.BR socket.unix.fattr. * +. +.\"-------------------------------------------------------------------------- .SH "BUGS" . The syntax for IP addresses and filenames is nasty.