Rewrite rush.texi (initial draft)

1 files changed, 1073 insertions, 992 deletions

diff --git a/doc/rush.texi b/doc/rush.texi
index d331948..8cf35d7 100644
--- a/doc/rush.texi
+++ b/doc/rush.texi
@@ -36,7 +36,7 @@
 @copying
 Published by the Free Software Foundation,
 51 Franklin Street, Fifth Floor,
-Boston, MA 02110-1301 USA 
+Boston, MA 02110-1301 USA
 
 Copyright @copyright{} 2008-2019 Sergey Poznyakoff
 
@@ -45,9 +45,9 @@ under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with no
 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
 A copy of the license is included in the section entitled ``GNU Free
-Documentation License''. 
+Documentation License''.
 @end copying
-                                   
+
 @titlepage
 @title GNU Rush -- a restricted user shell
 @subtitle version @value{VERSION}, @value{UPDATED}
@@ -99,37 +99,54 @@ Appendices
 
 Configuration File
 
-* Syntax::                      
-* Rule::                        
-* Include::                     
-* Debugging::                   
-* Regex::                       
-* Sleep Time::                  
-* Error Messages::
+* Lexical Structure::
+* Syntax::
+* Global::
+* Rule::
+* Include::
 
-Syntax
+The @code{global} statement
 
-* Quoted Strings::
+* Expansion control::
+* Debugging::
+* sleep-time::
+* Error Messages::
+* regexp::
+* include-security::
+* Accounting control::
 
 Rule
 
-* Conditions::                  
-* Transformations::             
-* System Actions::              
-* Environment::                 
-* Fall-through::                
-* Accounting and Forked Mode::  
-* Notification::                
+* Request::
+* Matching Conditions::
+* Modifying variables::
+* Transformations::
+* System Actions::
+* Environment::
+* Fall-through::
+* Accounting and Forked Mode::
+* Notification::
 * Exit::
 * Interactive::
 * Localization::
 
-Transformations
+The Request
+
+* Positional variables::
+* Request variables::
+* Variable expansion::
+
+Matching Conditions
 
-* set::
-* delete::
-* transform::
-* map::
+* Comparisons::
+* Membership operators::
+* Boolean expressions::
+
+Modifying variables
+
+* set::             Set variable
+* unset::           Unset variable
+* map::             Use file lookup to modify variable
 
 Localization
 
@@ -146,6 +163,10 @@ Usage Tips
 * git::
 * notification example::
 
+Test Mode
+
+* dump mode::
+
 The @code{rushwho} utility.
 
 * Rushwho Options::
@@ -166,10 +187,10 @@ Accounting Database
 @node Intro
 @chapter Introduction
   GNU Rush is a Restricted User Shell, designed for sites that provide
-limited remote access to their resources, such as svn or git  
+limited remote access to their resources, such as svn or git
 repositories, scp, or the like.  Using a sophisticated configuration
 file, GNU Rush gives you complete control over the command lines that
-users execute, as well as over the usage of system resources, such as 
+users execute, as well as over the usage of system resources, such as
 virtual memory, CPU time, etc.
 
 @node Operation
@@ -193,7 +214,7 @@ for the user who executes @command{rush} are said to form a
 @cindex conditions
 @cindex actions
   After startup, @command{rush} reads a set of @dfn{rules} from its
-configuration file.  Each rule consists of conditions
+configuration file.  Each rule consists of matching conditions
 and actions.  @dfn{Conditions} decide whether the request matches
 the rule.  They can include regular expression matching against entire
 command line or particular words thereof, comparisons of user name or
@@ -231,14 +252,13 @@ following configuration file rule:
 @smallexample
 @group
 rule sftp
-  # Conditions:
-  command ^.*/sftp-server
-  uid >= 100
+  # Matching condition
+  match $uid >= 100 && $command ~ "^.*/sftp-server"
   # Actions:
-  transform[0] s,.*,bin/sftp-server,
+  set [0] = "bin/sftp-server"
   umask 002
-  chroot ~
-  chdir /
+  chroot "~"
+  chdir "/"
 @end group
 @end smallexample
 
@@ -247,34 +267,19 @@ serves as a rule tag, used for diagnostic messages and for accounting.
 
   Lines beginning with @samp{#} are comments, they are intended for a
 human reader and are ignored by @code{rush}.
- 
-  The two statements that follow the comment, @code{command} and
-@code{uid}, define conditions that must be met for this rule to become
-active.  The @code{command} statement introduces a regular expression
-to match with the command line.  In this example, the command line must
-begin with @samp{/sftp-server}, optionally preceded by arbitrary
-directory components. 
 
-  The @code{uid} statement tells that this rule applies only to users
-whose @acronym{UID}s are greater than or equal to 100. 
+  The @code{match} statement, defines condition that must be met for
+this rule to become active.  In this example it requests that the
+UID of the requesting user be greater than or equal to 100, and the
+command line begin with @samp{/sftp-server}, optionally preceded by
+arbitrary directory components.
 
   Subsequent clauses define actions associated with this rule.
 
-  The @code{transform[0]} clause contains instructions on how to
-modify the first argument of the command line (i.e. the command
-name).  These instructions are in the form of @code{sed} replace
-expression (@pxref{Transformations, transformation expression}).  The
-expression in our example instructs GNU Rush to replace the command name with
-@samp{bin/sftp-server}@footnote{In this particular case, the
-@code{set} statement, introduced in GNU Rush version 1.6, is probably more
-appropriate:
-
-@smallexample
-  set[0] bin/sftp-server
-@end smallexample
-
-@xref{set}, for details.
-}.
+  The @code{set} clause contains instructions on how to
+modify the first argument of the command line.  Argument indices start
+at 0, so @samp{[0]} refers to the command name.  The expression in our example
+instructs GNU Rush to replace it with @samp{bin/sftp-server}.
 
   The @code{umask} clause sets the file creation mask.
 
@@ -287,7 +292,7 @@ after installing the chroot.
 @node Configuration File
 @chapter Configuration File
 @flindex rush.rc
-  The configuration file is called @file{rush.rc} and is located in
+  The configuration file @file{rush.rc} is located in
 @file{/usr/local/etc} by default.@footnote{The exact location of the
 configuration file is defined when configuring the package.  See the
 file @file{INSTALL} in the GNU Rush source directory for more information}.
@@ -321,54 +326,74 @@ execution.
 Any of these tests can be disabled using the
 @command{--security-check} option (@pxref{--security-check}).
 
-@menu
-* Syntax::                      
-* Rule::                        
-* Include::                     
-* Debugging::                   
-* Regex::                       
-* Sleep Time::                  
-* Error Messages::
-@end menu
-
-@node Syntax
-@section Syntax
-@cindex syntax, configuration files
-@cindex configuration file syntax
-  Configuration file consists of statements and comments.  
-
-  A @dfn{comment} is any line whose first non-whitespace character is
-@samp{#}.  Empty lines and comments are ignored.
+  As of version @value{VERSION}, @command{rush} supports two distinct
+configuration file formats.
 
-  A @dfn{statement} consists of a keyword and optional argument,
-separated by any amount of whitespace.  Depending on the keyword, the
-statement may treat its argument as a single value or as multiple values.
-For example, the @code{command} instruction takes a single 
-value as its argument, so parsing the statement
+@cindex legacy syntax
+@cindex syntax, legacy
+  The @dfn{legacy} configuration format is the one used in rush
+versions up to 1.9.  It is still supported to facilitate transition of
+existing installations to the new syntax.  Its support will be removed
+in future versions.  The legacy syntax is described in detail in
+@uref{http://www.gnu.org.ua/software/rush/manual/1.x}.
 
-@smallexample
-command ^scp -t /incoming/
-@end smallexample
+  This manual describes new configuration file format.
 
-@noindent
-results in keyword @samp{command} and value @samp{^scp -t /incoming/}.
+@menu
+* Lexical Structure::
+* Syntax::
+* Global::
+* Rule::
+* Include::
+@end menu
 
-If the keyword requires multiple values, its argument is split into
-words using the following algorithm:
+@node Lexical Structure
+@section Lexical Structure of the Configuration File
+  Configuration file consist of tokens separated by arbitrary amount
+of whitespace characters: horizontal spaces and tabs.  Except when
+enclosed in double quotes, the @samp{#} character introduces an inline
+comment: the character itself and any material following it up to the
+end of the physical line is ignored.  Comments are treated as newlines.
+
+@anchor{word}
+@anchor{token}
+The following classes of tokens are recogized.
+
+@table @dfn
+@item Newlines
+A newline character (ASCII 10) terminates a statement.  If immediately
+preceded by a backslash, both backslash and newline are removed and
+the following line is treated as continuation of the current line.
+This allows for splitting exceedingly long statements over several
+physical lines.
+
+@cindex identifiers, configuration
+@item Identifiers
+Identifiers begin with a letter and consist of letters, digits,
+underscores and dashes.  They serve as keywords and variable names.
+
+@item Decimal numbers
+A sequence of decimal digits, optionally preceded by a minus or plus
+sign.
+
+@cindex unquoted strings
+@item Unquoted strings
+An unquoted string is any contiguous sequence of any characters,
+except newlines, whitespace and the following special characters:
+@samp{\}, @samp{"}, @samp{!}, @samp{=}, @samp{<}, @samp{>}, @samp{(},
+@samp{)}, @samp{@{}, @samp{@}}, @samp{[}, @samp{]}, @samp{$},
+@samp{%}, @samp{&}, @samp{|}, @samp{~}, @samp{#}.
 
-@enumerate 1
-@item Any sequence of one or more non-whitespace characters is a word.
-@item Any sequence of characters enclosed in single (@samp{'}) or
-double-quotes (@samp{"}) is a word.
-@item Words are separated by any amount of white space.
-@item If the keyword expects s-expressions (@pxref{s-expression}),
-these are treated as words, even if they contain white space.
-@end enumerate
+@cindex quoted strings
+@item Quoted strings
+A quoted string is a sequence of characters enclosed in
+double-quotes.  Quoted strings are subject to backslash
+interpretation, backreference interpretation and variable
+expansion.
 
-Arguments, obtained as a result of rules (1) and (2) are subject to
-@dfn{backslash interpretation}, during which the following @dfn{escape
-sequences} are replaced with single characters, as described in the
-table below:  
+@cindex backslash interpretation
+During the @dfn{backslash interpretation}, the @dfn{escape sequences}
+are recognized and replaced as per table below:
 
 @float Table, backslash-interpretation
 @caption{Backslash escapes}
@@ -381,325 +406,568 @@ table below:
 @item \r @tab Carriage return character (@acronym{ASCII} 13)
 @item \t @tab Horizontal tabulation character (@acronym{ASCII} 9)
 @item \v @tab Vertical tabulation character (@acronym{ASCII} 11)
+@item \\ @tab Single backslash character
+@item \" @tab Double-quote
+@item \% @tab Percent character
 @end multitable
 @end float
 
-  Any escape sequence not listed in this table is replaced with its
-second character.
+The backslash immediately followed by newline character is removed.
+When followed by any other character except as listed above, both the
+backslash and the character are retained verbatim.
+
+@cindex backreference interpretation
+@anchor{backreference}
+During @dfn{backreference interpretation}, references to parenthesized
+groups in regular expression are replaced with the actual content of
+the corresponding group in the most recently matched string. A
+reference is @samp{%@{@var{n}@}} where @var{n} is a decimal number. If
+@var{n} is one digit, curly braces can be omitted: @samp{%@var{n}}.
+If the @samp{%} character results from previous backslash
+interpretation, no backreference interpretation occurs.
+
+Strings used in the left-hand side of a comparison expression are
+subject to variable expansion.  This is discussed in detail in
+@ref{Variable expansion}.
+
+@item Variable references
+Variable references consist of a @samp{$} sign, followed by the
+positional argument number or variable name, optionally enclosed in
+curly braces.  Positional arguments greater than 9 must be enclosed in
+curly braces. The variable name must follow the rules for valid
+identifiers: it must begin with a letter and consist of letters,
+digits and underscores.  Variable name in curly braces can be followed
+by @samp{-}, @samp{=}, @samp{?}, or @samp{+}, optionally preceded by
+@samp{:} as summarized in the table below:
+
+@float Table, variable references
+@caption{Variable reference}
+@multitable @columnfractions 0.30 .5
+@item Reference @tab Meaning
+@item $@{@var{var}:-@var{word}@} @tab  Use Default Values
+@item $@{@var{var}:=@var{word}@} @tab  Assign Default Values
+@item $@{@var{var}:?@var{word}@} @tab  Display Error if Null or Unset
+@item $@{@var{var}:+@var{word}@} @tab  Use Alternate Value
+@end multitable
+@end float
 
-  Statements are delimited by newline characters.  Length of a
-statement line is not limited.  To improve readability, long
-statements may be split over several lines by using backslash
-(@samp{\}) as a last character on line.  Thus, the following statement:
+Where @var{word} stands for any valid token as described in this
+section.  @xref{Variable expansion}, for a detailed discussion of
+these forms and their meaning.
 
-@smallexample
-usage-error Contact your\
- system administrator
-@end smallexample
+@anchor{operator}
+@item Comparison and boolean operators
+These are:
 
-@noindent
-is equivalent to:
+@float Table, Operators
+@caption{Operators}
+@multitable @columnfractions 0.30 .5
+@item @samp{&&}      @tab Boolean @dfn{and}
+@item @samp{||}      @tab Boolean @dfn{or}
+@item @samp{!}       @tab Boolean negation
+@item @samp{==}      @tab Equality (string or numeric)
+@item @samp{!=}      @tab Inequality (string or numeric)
+@item @samp{<}       @tab Less than
+@item @samp{<=}      @tab Less than or equal to
+@item @samp{>}       @tab Greater than
+@item @samp{>=}      @tab Greater than or equal to
+@item @samp{~}       @tab Regexp matching
+@item @samp{!~}      @tab Negated regexp matching
+@item @samp{in}      @tab Membership in set of strings
+@item @samp{member}  @tab Membership in UNIX group
+@item @samp{=}       @tab Assignment
+@item @samp{=~}      @tab Regular expression substitution
+@end multitable
+@end float
 
-@smallexample
-usage-error Contact your system administrator
-@end smallexample
+@xref{Matching Conditions}, for a detailed discussion.
+@end table
+
+@node Syntax
+@section Syntax
+@cindex syntax, configuration files
+@cindex configuration file syntax
+  The @samp{rush} configuration consists of @dfn{statements}.
+
+  A @dfn{statement} consists of a keyword and optional arguments,
+separated by any amount of whitespace.  Each statement occupies one
+line in the configuration file and is terminated by newline character.
+Extremely long statements may be split across several physical lines
+by ending each line except the last with a backslash followed by a
+newline.
+
+  Statements may be separated by any amount of empty lines or comments.
+
+@cindex syntax version statement
+@cindex @code{rush}, statement
+  The first statement in a configuration file indicates the syntax
+version.  It has the following form:
+
+@example
+rush 2.0
+@end example
+
+  This statement is mandatory.  In its absence, the file will be
+treated as legacy configuration file.
+
+  Statements that follow form logical groups.  Each group begins
+with a @code{rule} or @code{global} statement.
+
+The @code{global} statement introduces global settings.  It affects
+all statements that follow it.
+
+The @code{rule} statement introduces a single @command{rush} rule,
+that defines how to process a particular command.
+
+These statements are described in the sections that follow.
+
+@node Global
+@section The @code{global} statement
+@cindex @code{global}
+  The @code{global} statement defines global settings.  The syntax is:
+
+@example
+  global
+    @var{stmt1}
+    @var{stmt2}
+    ...
+@end example
+
+where dots represent any number of statements.  The following
+subsections discuss the statements that can be used within a
+@code{global} block.
 
 @menu
-* Quoted Strings::
+* Expansion control::
+* Debugging::
+* sleep-time::
+* Error Messages::
+* regexp::
+* include-security::
+* Accounting control::
 @end menu
 
-@node Quoted Strings
-@subsection Notes on Quoted Strings
-@cindex quoted strings
+@node Expansion control
+@subsection Expansion control
 
-  The syntax of GNU Rush configuration file was designed so as to
-implement minimum amount of syntactic mark up.  Most statements
-treat their argument as a single value, even if it contains embedded
-white space.  However, leading and trailing whitespace is always
-removed.  Consider, for example, the following
-statement@footnote{@xref{match}, for information about
-@code{match} statement.}:
+The following statement controls the behavior of @command{rush} when
+an undefined variable is expanded (@pxref{Variable expansion}).
 
-@smallexample
-  match[1] ^/sources/[^ ]+\.git$
-@end smallexample
+@deffn {global} expand-undefined @var{bool}
+If @var{bool} is @samp{true}, expand undefined variables to empty
+value. If it is @samp{false} (the default), issue an error and abort.
 
-@noindent
-Here, the argument is @samp{^/sources/[^ ]+\.git$}.  Note, that you
-must not quote it, because quotation marks would be considered part of
-the argument.
+The following values can be used as a synonim for @samp{true}:
+@samp{yes}, @samp{on}, @samp{t}, @samp{1}.
 
-There are, however, statements that take several arguments.  In these
-statements, arguments that contain embedded white space must be
-quoted.  For example, in the statement below@footnote{@xref{map}, for
-a description of @command{map} statement.} the second argument is a
-single space character.  It is quoted to prevent it from being treated
-as a delimiter:
+The following values can be used as a synonim for @samp{false}:
+@samp{no}, @samp{off}, @samp{nil}, @samp{0}.
+@end deffn
 
-@smallexample
-  map[0] /etc/passwd.rush " " $@{user@} 1 7
-@end smallexample
+@FIXME{Describe the recommended use of $@{VAR:-""@} to prevent errors
+during expansion}.
+
+@node Debugging
+@subsection Debugging
+@cindex debugging
+  The @code{debug} global statement sets the @dfn{debugging level} -- an
+integer value that controls the verbosity of @command{rush}:
 
-Notice also, that arguments to these statements are subject to
-backslash interpretation (@pxref{backslash-interpretation}).
+@deffn {global} debug @var{num}
+Set debugging level to @var{num}.
+@end deffn
 
-The table below lists all statements that take multiple arguments,
-with cross references to more in-depth explanations in the body of the
-manual.
+  The greater @var{num} is, the more verbose is the logging.  The
+debugging information is reported via @code{syslog} at facility
+@samp{authpriv}, priority @samp{debug}.  As of version @value{VERSION},
+the following debugging levels are supported:
 
+@cindex debugging levels
 @table @asis
-@item user
-@xref{Conditions, user}.
-@item group
-@xref{Conditions, group}.
-@item transform @var{pattern} @var{expr}
-@itemx transform[@var{n}] @var{pattern} @var{expr}
-@xref{transform}.  
-@item map
-@xref{map}.
-@item env
-@xref{Environment}.
-@item regexp
-@xref{Regex}.
-@item include-security
-@xref{include-security}.
+@item 1
+A minimum debugging level, and the only one whose messages are logged
+using the priority @samp{notice}.  At this level, @command{rush} only
+logs requests and rules selected to handle them.  For example:
+
+@smallexample
+rush[16821]: Serving request "/usr/libexec/sftp-server"
+for sergiusz by rule sftp-savane
+@end smallexample
+
+@item 2
+List all actions executed when serving requests.
+
+@item 3
+Verbosely describe parsing of the configuration file.
 @end table
 
-@node Rule
-@section Rule
-@cindex @code{rule} statement
-  The @code{rule} statement configures a GNU Rush rule.  This is a
-@dfn{block} statement, which means that all statements located between
-it and the next @code{rule} statement (or end of file, whichever
-occurs first) modify the definition of the rule.
+  More debugging levels may be implemented in future.
 
-@kwindex rule
-  The syntax of the @code{rule} statement is:
+@node sleep-time
+@subsection The @code{sleep-time} statement
 
-@deffn {Configuration} rule @var{tag}
+@deffn {global} sleep-time @var{num}
+Set the time in seconds to sleep before exiting on error.
+This statement is intended as a measure against brute-force attacks.
+Default sleep time is 5 seconds.
 @end deffn
 
-@cindex rule tag
-@cindex tag, rule
-The @var{tag} argument is optional.  If it is given, it supplies a
-@dfn{tag} for the rule, i.e. a (presumably unique) identifier, which
-is used to label this rule.  @command{Rush} uses this tag in its diagnostic
-messages.  For rules without explicit @var{tag}, @command{Rush} supplies a
-default tag, which is constructed by concatenating @samp{#} character
-and the ordinal number of rule in the configuration file, in decimal
-notation.  Rule numbering starts from @samp{1}.
+@node Error Messages
+@subsection Error Messages
+@cindex error messages
 
-The following sub-sections describe statements that can be used
-within a @code{rule}.
+@deffn {global} message @var{class} @var{text}
+Define a textual message which is returned to the remote party if an
+error of the given @var{class} occurs.
+@end deffn
 
-@menu
-* Conditions::                  
-* Transformations::             
-* System Actions::              
-* Environment::                 
-* Fall-through::                
-* Accounting and Forked Mode::  
-* Notification::                
-* Exit::
-* Interactive::
-* Localization::
-@end menu
+Valid values for @var{class} are:
 
-@node Conditions
-@subsection Conditions
-@cindex conditions
-  These statements define conditions that are evaluated when matching
-the rule against the request.  A rule may contain any number of
-conditions.  All conditions are tested in order of their appearance in
-the rule and are tied together using boolean shortcut @samp{and}
-evaluation: if any of them yields false, the rest is not evaluated and
-control is transferred to the subsequent rule. 
+@table @asis
+@cindex @code{usage-error}
+@item usage-error
+This error is reported when @command{rush} has been invoked
+improperly.  The default text is:
 
-@deffn {Rule Config} command @var{regex}
-True, if the current command line matches regular expression
-@var{regex}.  
+@smallexample
+You are not permitted to execute this command.
+@end smallexample
 
-For example:
+@cindex nologin-error
+@item nologin-error
+Define a textual message which is returned to the remote user if
+there is no such user name in the password database.
+
+Default is:
 
 @smallexample
-command ^scp (-v )?-t /incoming/(alpha|ftp)
+You do not have interactive login access to this machine.
 @end smallexample
 
-By default, @acronym{POSIX} extended regular expressions are used.
-This, however can be changed using @code{regex} statement (@pxref{Regex}).
-@end deffn
+@cindex @code{config-error}
+@item config-error
+Define a textual message which is returned to the remote party if the
+@command{rush} configuration file contains errors.
+
+Default is:
 
-@anchor{match}
-@deffn {Rule Config} match[@var{n}] @var{regexp}
-True, if @var{n}th @dfn{word} from the command line matches
-regular expression @var{regexp}.  Notice, that square brackets form
-part of the statement syntax.  The index @var{n} is normally a decimal
-number indicating position of the word in the command line (first word
-being at index 0).  It can be negative, which means that the position
-is counted from the last word.  Several special notations are also
-allowed, e.g. @samp{$} denotes the last word.  For a detailed discussion of
-word-splitting alorithm and allowed notations of @var{n}, @ref{indexing}.  
+@smallexample
+Local configuration error occurred.
+@end smallexample
 
-Second argument @var{regexp} is a regular expression to match the word
-against.  Unless changed by previous @code{regex} statement
-(@pxref{Regex}), @acronym{POSIX} extended regular expression is assumed.
+@cindex @code{system-error}
+@item system-error
+Define a textual message which is returned to the remote party if
+a system error occurs.
 
-For example, the condition below yields true if the last argument is
-an absolute path name:
+Default message is:
 
 @smallexample
-match[$] ^/.*
+A system error occurred while attempting to execute command.
 @end smallexample
+@end table
+
+@node regexp
+@subsection The @code{regexp} statement
+@cindex regular expressions
+@cindex extended regular expressions
+@cindex basic regular expressions
+@FIXME{Remove the Regex anchor when all references have been cleaned up}
+@anchor{Regex}
+The @code{regexp} statement configures the flavor of regular
+expressions for use by subsequent @code{match} and
+@code{set} statements.
+
+@deffn {global} regexp @var{flags} ...
+Configure the type of regular expressions.
 @end deffn
 
-@deffn {Rule Config} argc @var{op} @var{num}
-Compare the number of command line arguments to @var{num}.
-The comparison operator is given by @var{op}, which can be one 
-of the following: @samp{=} (or @samp{==}), @samp{!=}, @samp{<},
-@samp{<=}, @samp{>}, @samp{>=}.
+Each @var{flag} is word specifying some regular expression
+feature.  It can be preceded by @samp{+} to enable this feature (this
+is the default), or by @samp{-} to disable it.  Valid flags are:
+
+@table @samp
+@item extended
+Use @acronym{POSIX} Extended Regular Expression syntax when
+interpreting regex.  This is the default.
+
+@item basic
+Use basic regular expressions.  Equivalent to @samp{-extended}.
+
+@item icase
+@itemx ignore-case
+Do not differentiate case.  Subsequent regex matches will be case
+insensitive.
+@end table
 
-For example, the following condition matches if the number of
-arguments is less than 3:
+For example, the following statement enables @acronym{POSIX} extended,
+case insensitive matching:
 
 @smallexample
-argc < 3
+global
+  regex +extended +icase
 @end smallexample
+
+@node include-security
+@subsection The @code{include-security} statement
+
+Additional configuration can be included to the main configuration
+file using the @code{include} statement (@pxref{Include}).  Before
+inclusion, a number of checks is performed on the file to ensure it
+is safe to rely on it.  These checks are configured using the
+following statement:
+
+@deffn {global} include-security @var{list}
+Configure the security checks for include files.  This statement takes
+a list of arguments, separated by white space.  The following
+arguments are recognized:
+
+@table @asis
+@cindex @code{all}, include security flag
+@item all
+Enable all checks.
+
+@cindex @code{owner}, include security flag
+@item owner
+The file is not owned by root.
+
+@cindex @code{iwgrp}, include security flag
+@cindex @code{groupwritablefile}, include security flag
+@item iwgrp
+@itemx groupwritablefile
+The file is group writable.
+
+@cindex @code{iwoth}, include security flag
+@cindex @code{worlwritablefile}, include security flag
+@item iwoth
+@itemx worldwritablefile
+The file is world writable.
+
+@cindex @code{dir_iwgrp}, include security flag
+@cindex @code{groupwritabledir}, include security flag
+@item dir_iwgrp
+@itemx groupwritabledir
+The file resides in a group writable directory.
+
+@cindex @code{dir_iwoth}, include security flag
+@cindex @code{worldwritabledir}, include security flag
+@item dir_iwoth
+@itemx worldwritabledir
+The file resides in a world writable directory.
+
+@cindex @code{link}, include security flag
+@item link
+The file is a symbolic link to a file residing in a group or world
+writable directory.
+@end table
 @end deffn
 
-@deffn {Rule Config} uid [@var{op}] @var{user-id}
-Compare current @acronym{UID} to @var{user-id}.  The latter may be
-either a numeric UID or a name of an existing user.
+Each of the above keywords may be prefixed by @samp{no}, which
+reverses its meaning.  The special keyword @samp{none} disables all
+checks.  Each keyword adds or removes a particular test to the
+existing check list, which is initialized as described in
+@ref{security checks}.  Thus, the followning statement results in all
+checks, except for the file ownership:
 
-The comparison operator is given by optional @var{op}, which can be one 
-of the following: @samp{=} (@samp{==}), @samp{!=}, @samp{<},
-@samp{<=}, @samp{>}, @samp{>=}.  If @var{op} is not given, equality
-(@samp{==}) is assumed.
+@smallexample
+global
+  include-security noowner
+@end smallexample
 
-Examples:
+In the example below, the check list is first cleared by using the
+@code{none} statement, and then a set of checks is added to it:
 
 @smallexample
-uid smith
+global
+  include-security none owner iwoth iwgrp
 @end smallexample
 
-@end deffn
+@node Accounting control
+@subsection Accounting control statements
 
-@deffn {Rule Config} gid @var{op} @var{group-id}
-Compare current @acronym{GID} to @var{group-id}, which is either a
-numeric value or a name of an existing group.
+The following global statements control file mode and permissions of
+the @dfn{accounting database files}.  For a detailed description of
+this feature, @xref{Accounting Database}.
 
-The comparison operator is given by @var{op}, which can be one
-of the following: @samp{=} (@samp{==}), @samp{!=}, @samp{<},
-@samp{<=}, @samp{>}, @samp{>=}.  If @var{op} is not given, equality
-(@samp{==}) is assumed.
+@deffn {global} acct-umask @var{mask}
+Set umask used when accessing accounting database files.  Default
+value is @samp{022}.
 @end deffn
 
-@deffn {Rule Config} user @var{names}
-Argument is a whitespace-separated list of user names.  This condition
-yields true, if the user name is listed in @var{names}.
-String comparisons are case-sensitive.
+@deffn {global} acct-dir-mode @var{mode}
+Set mode bits for the accounting directory.  The @var{mode} argument
+is the mode in octal.
+@end deffn
+
+@deffn {global} acct-file-mode @var{mode}
+Set mode bits for @file{wtmp} and @file{utmp} files.
 @end deffn
 
-@deffn {Rule Config} group @var{names}
-Argument is a whitespace-separated list of group names.  This condition
-yields true, if the the name of any group the user is a member of
-is listed in @var{names}.  String comparisons are case-sensitive.
+@node Rule
+@section Rule
+@cindex @code{rule}
+  The @code{rule} statement configures a GNU @command{rush} rule.
+This is a @dfn{block} statement, which means that all statements
+located between it and the next @code{rule} statement (or end of file,
+whichever occurs first) modify the definition of that rule.
 
-For example, to match users from groups @samp{admin} and @samp{root}:
+  The syntax of the @code{rule} statement is:
 
-@smallexample
-group admin root
-@end smallexample
+@deffn {Configuration} rule @var{tag}
 @end deffn
 
-  Each condition can be negated by placing exclamation sign between
-the condition keyword and expression.  For example: 
+@cindex rule tag
+@cindex tag, rule
+The @var{tag} argument is optional.  If it is given, it supplies a
+@dfn{tag} for the rule, i.e. a (presumably unique) identifier, which
+is used to label this rule.  @command{Rush} uses this tag in its diagnostic
+messages.  For rules without explicit @var{tag}, @command{Rush} supplies a
+default tag, which is constructed by concatenating @samp{#} character
+and the ordinal number of rule in the configuration file, in decimal
+notation.  Rule numbering starts from @samp{1}.
 
-@table @code
-@item command ^scp
-True, if the command line begins with @samp{scp}.
+Each rule group can contain a number of statements that control what
+kind of requests match that rule and what actions are taken when the
+rule is matched.  Arguments to this statements can refer to command
+line arguments and other parts of the request.
 
-@item command ! ^scp
-True if the command line does not begin with @samp{scp}.
-@end table
+@menu
+* Request::
+* Matching Conditions::
+* Modifying variables::
+* Transformations::
+* System Actions::
+* Environment::
+* Fall-through::
+* Accounting and Forked Mode::
+* Notification::
+* Exit::
+* Interactive::
+* Localization::
+@end menu
 
-@node Transformations
-@subsection Transformations
-@cindex transformations
-  Special actions that modify the original command line are called
-@dfn{transformations}.  GNU Rush supports several kinds of
-transformations: @samp{set}, @samp{transform}, @samp{delete}, 
-@samp{map}.  All of them operate on command line split into
-@dfn{words}.  Additionally, @samp{set} and @samp{transform} can
-operate on the entire command line.
+@node Request
+@subsection The Request
+@cindex request
+@UNREVISED
+
+@menu
+* Positional variables::
+* Request variables::
+* Variable expansion::
+@end menu
+
+@node Positional variables
+@subsubsection Positional variables
 
 @anchor{indexing}
 @cindex word splitting
 @cindex indexing, words in command line
   Rush performs word splitting using the same rules as @command{sh}.
-Transformation actions refer to words by their @dfn{index}.  Three
-kinds of indexes are supported.  First of all, a word may be referred
-to by its ordinal number in the command line.  The command name itself
-has index @samp{0}.  For example, given the command line:
+Configuration statement refer to command line arguments (words) by
+their @dfn{index}, using @dfn{positional variables}.  A positional
+variable can have the following forms:
+
+@example
+ $@var{n}
+ $@{@var{n}@}
+@end example
+
+@noindent
+where @var{n} is the variable index.  The form with curly braces must
+be used if @var{n} is negative (see below) or greater than 9.
+
+Positional indexes start at @samp{0}.  Thus, the variable @samp{$0}
+refers to the command name.  Consider, for example, the following
+command line:
 
 @smallexample
 /bin/scp -t /upload
 @end smallexample
 
-one gets:
+Word splitting phase results in three positional variables being defined:
+
+@multitable @columnfractions 0.3 0.7
+@headitem Variable @tab Value
+@item $0 @tab /bin/scp
+@item $1 @tab -t
+@item $2 @tab /upload
+@end multitable
+
+  These values can also be referred to using negative indexes.  They
+refer to words in the reverse order, as illustrated in the following
+table (notice the use of curly braces):
 
 @multitable @columnfractions 0.3 0.7
-@headitem Index @tab Value
-@item 0 @tab /bin/scp
-@item 1 @tab -t
-@item 2 @tab /upload
+@headitem Variable @tab Value
+@item $@{-3@} @tab /bin/scp
+@item $@{-2@} @tab -t
+@item $@{-1@} @tab /upload
 @end multitable
 
-  Negative indexes can also be used.  They refer to words in the
-reverse order, as illustrated in the following table:
+  Notice also, that negative indexes are 1-based.
+
+One final note about the @samp{$0} variable.  Immediately after word
+splitting it refers to both the executable program name and the 0th
+argument that will be passed to that program (@code{argv[0]}).  Most
+of the time the two values coincide.  However, the rule can modify
+either value, so that they become different.  Whether modified or not,
+the actual name of the program to be run is kept in the request
+variable @samp{$program} (see the following section).
+
+@node Request variables
+@subsubsection Request variables
+
+The following variables can be used to refer to various parts of the
+user request:
 
 @multitable @columnfractions 0.3 0.7
-@headitem Index @tab Value
-@item -3 @tab /bin/scp
-@item -2 @tab -t
-@item -1 @tab /upload
+@headitem Variable   @tab Expansion
+@vindex user
+@item $user          @tab User name
+@vindex group
+@item $group         @tab Name of the user's principal group
+@vindex uid
+@item $uid           @tab UID
+@vindex gid
+@item $gid           @tab GID
+@vindex home
+@item $home          @tab User's home directory