set

A rule can modify the command line and environment in which it will be executed. The set statement is provided for altering the command line or its parts. It takes three arguments: the variable name or index, the operator and the value. For example, the statement:

set command = "/bin/sftp-server -u 002"

replaces the entire command line. To replace particular arguments, use the [N] syntax, where N is the index of the argument in the command line. For example, to set the first argument:

set [1] = "/tmp"

The part to the right of the equals sign can contain a transformation, i.e. a string followed by the ~ operand and a s-expression of the form s/regexp/replacement/[flags]. Parenthesized groups in regexp can be referred to in replacement using the backreference construct \N, where N is the 1-based ordinal number of the group. For example, the following statement sets the second argument to the directory part of the first one:

set [2] = "$1" ~ "s/(.*)\\//\\1/"

Two points are worth noticing. First, the left operand of ~ undergoes variable expansion. Secondly, the right-hand side operand is quoted and therefore each backslash in it has to be escaped.

The special operator =~ is used if the resulted value is assigned to the same variable that served as its argument. For example, the two statements below are equivalent:

set [1] =~ "s/(.*)\\//\\1/"
set [1] = "$1" ~ "s/(.*)\\//\\1/"

Parenthesized groups matched by the most recent set statement remain available for use in the statements that follow it in the rule. To refer to the group from the recent matching, use the following construct: %N. For example, the following two statements set the first argument to the directory part, and second argument to the base name of the original $1 value:

set [1] =~ "s/(.*)\\/(.*)/\\1/"
set [2] = %2

The set statement operates not only on positional arguments and built-in variables, but also on arbitrary user-defined variables. A user-defined variable springs into existence when it first appears as a left-hand side argument to the set statement. The name of the variable must follow the usual rules for variable names: it must begin with an alphabetical character or underscore and contain only letters, digits and underscores. References to user-defined variables follow the same syntax as for built-in ones.

The following example uses temporary variable temp to swap two arguments:

set temp = $1
set [1] = $2
set [2] = $temp

unset

Variable definitions can be removed using the unset statement. It takes variable name or positional argument index as its argument:

unset temp

When index is given, the corresponding positional argument is removed and all arguments to the right of it are shifted one position left to occupy the released slot. For example, given the command line

scp -d -v -t /incoming

the statement

unset 1

will reduce it to

scp -v -t /incoming

delete

The delete statement provides a generalization of unset for positional arguments. It takes one or two argument indexes as arguments. When used with one index, it provides the same functionality as unset. When two indices are given, it deletes all arguments between those indices (inclusive). For example, the statement

delete 1 2

will change the command line from the above example to

scp -t /incoming

Using negative indices, one can indicate arguments counting from right to left. Thus, the following will delete all arguments starting from the third:

delete 3 -1

remopt

Whereas delete and unset remove arguments at given positions, the remopt statement allows you to remove specific command line options from the command line. This is useful to ensure no potentially harmful options can be passed by the user. The statement takes one or two arguments. First argument supplies the short option letter. For example, the following removes all occurrences of the -A option:

remopt A

If there is a long-option equivalent, it can be supplied as the second argument. For example, if --all is an alias for -A, the above statement would be rewritten as:

remopt A all

Notice, that the initial dash or double-dash is omitted from both the short and long option designation.

When looking for long option in the command line, remopt will recognize its possible abbreviations. In the example above, eventual occurrences of --al will be removed as well.

If the option takes an argument, follow the first argument by a colon. For example, to remove occurrences of the options -r along with its arguments write

remopt r:

The long option equivalent can be specified as well, e.g.:

remopt r: root

This will recognize all possible ways of option usage in the command line, such as: -r ARG, -rARG, --root=ARG, or --root ARG. -afr ARG In each case, both the option and its argument will be removed, so that the modified command line will remain valid. Short option appearing in a cluster will be recognized, .e.g -afr ARG will be replaced by -af. Finally, if the option takes an optional argument, follow its short letter by two colons, as in:

remopt r:: root

insert

Arguments can also be inserted at arbitrary positions. The insert statement is provided for this purpose. Its syntax is similar to set:

insert [N] = value

and

insert [N] = value ~ s/regex/replace/

where N is the position where to insert the new argument. All arguments starting from Nth will be shifted one position to the right, and the value will be stored in the Nth slot. In the second form, the value to be inserted is computed by applying the replacement expression to value.

global

Introduces global settings. This statement is followed by one or more substatements. Global settings end at the nearest rule statement that follows. They remain in effect until the next global statement is encountered which alters them.

The following statements may appear in this section.

expand-undefined BOOL

Controls how undefined variables are expanded. If BOOL is true, references to undefined variables are replaced with empty values. If it is false (the default), an error message is issued and program terminates.

Any of the following values can be used as a synonym for true: yes, on, t, 1.

The following values can be used as synonyms for false: no, off, nil, 0.

debug NUM

Set debugging level. The bigger NUM is, the more verbose is the logging. The debugging information is reported via syslog at facility authpriv, priority debug.

sleep-time 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.

message CLASS TEXT

Define a textual message which is returned to the remote party if an error of the given CLASS occurs. Valid classes are:

regexp FLAG [FLAG...]

Configure the type of regular expressions to be used by subsequent match, set, and insert statements. Each FLAG is a word specifying a regular expression feature. It can be preceded by a plus sing to enable this feature (this is the default), or by the minus sign to disable it. Valid flags are:

include-security FLAG [FLAG...]

Configure the security checks for include files. Valid flags are:

Each of the above keywords can be prefixed by no, which reverses its meaning. The special keyword none disables all checks.

acct-umask MASK

Set umask used when accessing accounting database files. Default value is 022.

acct-dir-mode MODE

Set mode bits for the accounting directory. The argument is the mode in octal.

acct-file-mode MODE

Set mode bits for the wtmp and utmp files.

rule

Defines a rule. This is a block statement, which means that all statements located between it and the next rule statement (or end of file, whichever occurs first) modify the definition of that rule.

The syntax is:

rule TAG

Optional TAG argument supplies the identifier for that rule. It is used in diagnostic messages. If tag is missing, rush will supply a default one, which is constructed by concatenating the # character and the ordinal number of rule in the configuration file, in decimal notation. Rule numbering starts from 1.

A rule can contain the following statements:

match EXPR

Defines conditions that decide whether the rule matches the particular request. The EXPR argument is a comparison expression. It can be a simple comparison expression or a boolean expression involving several other expressions.

A simple expression is either a comparison or a membership test. A comparison has the general syntax

lhs op rhs


    

where lhs and rhs are operands and op is the operation. The lhs is either a string (quoted or unquoted), or a variable reference. The rhs is a string or number. Prior to evaluating simple expression, its LHS undergoes variable expansion. In contrast, the RHS operand is always treated verbatim.

The comparison operator OP is one of the following:

	==	Equality (string or numeric)
	!=	Inequality (string or numeric)
	<	Less than
	<=	Less than or equal to
	>	Greater than
	>=	Greater than or equal to
	~	Regexp matching
	!~	Negated regexp matching

Two membership tests are available. The in test has the form

LHS in ( STRING ... )


    

and evaluates to true if LHS matches one of the strings in parentheses. LHS undergoes variable expansion and backreference interpretation prior to comparison.

The group test has the following syntax:

group GRP


    

It returns true if the requesting user is a member of the group GRP. Several groups can be given in parentheses:

group (GRP ...)


    

in which case the test return true if the user is a member of at least one of the mentioned groups.

Compound boolean expression combine one or more expressions using logical operators

	&&	Boolean AND
	||	Boolean OR
	!	Boolean negation

set NAME = VALUE

Sets the variable NAME to VALUE, which undergoes backreference interpretation and variable expansion.

set [N] = VALUE

Sets the command line argument N to VALUE

set NAME = VALUE ~ S-EXPR

Applies the sed(1)-like search-and-replace expression S-EXPR to VALUE and assigns the result to the variable NAME. Both VALUE and S-EXPR are subject to variable expansion and backreference interpretation.

set [N] = VALUE ~ S-EXPR

Similar to the above, but assigns the result to the Nth command line argument.

set NAME =~ S-EXPR

This is a shortcut for

set NAME = $NAME ~ S-EXPR


    

i.e. it applies the search-and-replace expression S-EXPR to the current value of the variable NAME and stores the resulting string as its new value.

set [N] =~ S-EXPR

A shortcut for

set [N] = $N ~ S-EXPR


    

The S-EXPR, is a sed replace expression of the form:

s/REGEXP/REPLACE/[FLAGS]

where REGEXP is a regular expression, REPLACE is a replacement for each part of the input that matches REGEXP and optional FLAGS are flag letters that control the substitution. Both REGEXP and REPLACE are described in sed(1).

As in sed, you can give several replace expressions, separated by semicolons.

The supported FLAGS are:

g

Apply the replacement to all matches to the REGEXP, not just the first.

i

Use case-insensitive matching.

x

REGEXP is an extended regular expression.

NUMBER

Only replace the NUMBERth match of the REGEXP.

Notice, that the POSIX standard does not specify what should happen when you mix the g and NUMBER modifiers. Rush follows the GNU sed implementation in this regard, so the interaction is defined to be: ignore matches before the NUMBERth, and then match and replace all matches from the NUMBERth on.

Also notice, that usually S-EXPR is a quoted string, and as such it is subject to backslash interpretation. It is therefore important to properly escape backslashes, especially in the REPLACE part. E.g.

set bindir = $program ~ "s/(.*)\\//\\1/"

insert [N] = VALUE

Shift command line arguments starting from the Nth one position to the right and store VALUE in the Nth slot. VALUE is subject to variable expansion and backreference interpretation.

insert [N] = VALUE ~ S-EXPR

Shift command line arguments starting from the Nth one position to the right, apply S-EXPR to VALUE and store the result in the Nth slot. Both S-EXPR and VALUE are subject to variable expansion and backreference interpretation.

unset NAME

Unset the variable NAME.

unset N

Unset the positional argument N (an integer number greater than 0), shifting the remaining arguments one position left. This is the same as delete N.

remopt SOPT

Remove from the command line all occurrences of the short option described by SOPT. The SOPT argument is the short option letter, optionally followed by a colon if that option takes a mandatory argument, or by two colons if it takes an optional argument.

remopt SOPT LOPT

Same as the above. LOPT supplies the long option equivalent for the short option described by SOPT.

delete N

Delete Nth argument.

delete I J

Delete arguments between I and J, inclusive.

map NAME FILE DELIM KEY KN VN

This statement uses file lookup to find a new value for the variable NAME. The FILE argument supplies the name of the map file. It must begin with / or ~/. Before use, the file permissions and ownership are checked using the criteria supplied in the include-security statement (see the global section).

The map file consists of records, separated by newline characters. Each record, in turn, consists of fields, separated by characters listed in the DELIM argument. If it contains a space character, then fields may be delimited by any amount of whitespace characters (spaces and/or tabulations). Otherwise, exactly one character delimits fields. Fields within a record are numbered starting from 1.

The map action operates as follows. First, variable expansion and backreference interpretation is performed on the KEY argument. The result will be used as actual lookup key. Then, FILE is scanned for a record whose KNth field matches the lookup key. If such a record is found, the value of its VNth field is assigned to the variable. Otherwise, if DEFAULT is supplied, it is assigned to the variable. Otherwise, the variable remains unchanged.

map [N] FILE DELIM KEY KN VN DEFAULT

Same as above, but the result of the lookup is assigned to Nth argument.

The following statements modify command execution environment:

clrenv

Clear the environment.

keepenv NAME ...

Retain the listed variables. This statement should be used in conjunction with clrenv.

Argument is a whitespace delimited list of variables to retain. Each element in the list can be either a variable name, or a shell-style globbing pattern, in which case all variables matching that pattern will be retained, or a variable name followed by an equals sign and a value, in which case it will be retained only if its actual value equals the supplied one. For example, to retain only variables with names beginning with 'LC_':

keepenv "LC_*"


    

setenv NAME = VALUE

Set the environment variable NAME. The VALUE argument is subject to variable expansion and backreference interpretation.

For example, to modify the 'PATH' value:

setenv PATH = "$PATH:/opt/bin"


    

unsetenv NAME ...

Unset environment variables. See keepenv for a discussion of arguments.

evalenv STRING

Performs backslash interpretation, backreference interpretation and variable expansion on STRING and discards the result. This statement is similar to the shell's "colon" statement.

The following statements are system actions. They provide interface to the operating system.

umask MASK

Set the umask. The MASK must be an octal value not greater than 0777. The default umask is 022.

newgrp GROUP-ID

Change the current group ID to GROUP-ID, which is either a numeric value or a name of an existing group.

newgroup GROUP-ID

Alias to the above.

chroot DIR

Change the root directory to DIR. The argument is subject to tilde and variable expansions and backreference interpretation. During tilde expansion, a tilde at the start of string is replaced with the absolute pathname of the user's home directory.

chdir DIR

Change to the directory DIR. The argument is subject to tilde and variable expansions and backreference interpretation. If both chdir and chroot are specified, chroot is applied first.

limits RES

Impose limits on system resources, as defined by RES. The argument consists of commands, optionally separated by any amount of whitespace. A command is a single command letter followed by a number, that specifies the limit. The command letters are case-insensitive and coincide with those used by the shell ulimit utility:

If some limit cannot be set, execution of the rule aborts. In particular, the L limit can be regarded as a condition, rather than an action. Setting limit L5 succeeds only if no more than 5 rush instances are simultaneously running for the same user. This can be used to limit the number of simultaneously open sessions.

The use of L resource automatically enables forked mode. See the subsection Accounting and forked mode for details.

fall-through or fallthrough

Declare a fall-through rule. After evaluating such a rule, rush continues rule matching process from the next rule in the configuration. Any modifications to the request found in the fall-through rule take effect immediately, which means that subsequent rules will see modified command line and environment. Execution of any other actions found in the fall-through rule is delayed until a matching rule is found.

Fall-through rules are often used to set default values for subsequent rules.

Accounting and forked mode

GNU rush is able to operate in two modes, which we call default and forked. When operating in the default mode, the process image of rush itself is overwritten by the command being executed. Thus, when it comes to launching the requested command, the running instance of rush ceases to exist.

There is also another operation mode, which we call forked mode. When running in this mode, rush executes the requested command in a subprocess, and remains in memory supervising its execution. Once the command terminates, rush exits.

One advantage of the forked mode is that it allows you to keep accounting, i.e. to note who is doing what and to keep a history of invocations. The accounting, in turn, can be used to limit simultaneous executions of commands, as requested by the L command to limit statement (see above).

acct BOOL

Turn accounting mode on or off, depending on BOOL. The argument can be one of the following: yes, on, t, true, or 1, to enable accounting, and no, off, nil, false, 0, to disable it.

fork BOOL

Enable or disable forked mode. See acct for a description of BOOL. Enabling accounting turns the fork mode as well. This statement is mainly designed as a way of disabling the forked mode for a given rule.

Post-process notification

Rush can be configured to send a notification over INET or UNIX sockets, after completing user request. It is done using the following statement:

post-socket URL

Notify URL about completing the user request. This statement implies forked mode.

Allowed formats for URL are:

inet://HOSTNAME[:PORT]

Connect to remote host HOSTNAME using TCP/IP. HOSTNAME is the host name or IP address of the remote machine. Optional PORT specifies the port number to connect to. It can be either a decimal port number or a service name from /etc/services. If PORT is absent, tcpmux (port 1) is assumed.

unix://FILENAME or local://FILENAME

Connect to a UNIX socket FILENAME.

The notification protocol is based on TCPMUX (RFC 1078). After establishing connection, rush sends the rule tag followed by a CRLF pair. The rule tag acts as a service name. The remote party replies with a single character indicating positive (+) or negative (-) acknowledgment, optionally followed by a message of explanation, and terminated with a CRLF.

If positive acknowledgment is received, rush sends a single line, consisting of the user name and the executed command line, separated by a single space character. The line is terminated with a CRLF.

After sending this line, rush closes the connection.

The post-process notification feature can be used to schedule execution of some actions after certain rules.

Exit rule

exit FD TEXT

Write textual message TEXT to file descriptor FD.

exit TEXT

Write textual message TEXT to standard error. Similar to

exit 2 TEXT


    

In both cases the TEXT argument can be either a quoted string, or an identifier.

If it is a quoted string, it is subject to backreference interpretation and variable expansion.

If TEXT is an identifier, it must be the name of a predefined error message (see the list in the discussion of the message statement in global section, above).

Interactive access

Sometimes it may be necessary to allow some group of users limited access to interactive shells. GNU rush contains provisions for such usage. When it is invoked without '-c' it assumes interactive usage. In this case only rules explicitly marked as interactive are considered, the rest of rules is ignored.

interactive BOOL

If BOOL is true (see the acct statement above for allowed values), this statement marks the rule it appears in as interactive. This rule will match only if rush is invoked without command line arguments.

Unless command line transformations are applied, interactive rule finishes by executing /bin/sh. The first word in the command line (argv[0]) is normally set to the base name of the command being executed prefixed by a minus character.

An example

rule login


  interactive true


  group rshell


  map program /etc/rush.shell : ${user} 1 2


  set [0] = ${program} ~ "s|^.*/||;s,^,-r,"
rule nologin


  interactive true


  exit You don't have interactive access to this machine.

The login rule will match interactive user requests if the user is a member of the group rshell. It looks up the shell to use for this in the file /etc/rush.shell. This map file consists of two fields, separated by a colon. If the shell is found, its base name, prefixed with -r, will be used as argv[0] (this indicates a restricted login shell). Otherwise, the trap rule nologin will be matched, which will output the given diagnostics message and terminate rush.

Localization

The following statement allow you to provide translations (localizations) for the messages in your rush configuration:

locale NAME

Set the locale name. To specify empty locale, use "" as NAME (recall that empty locale name means to use the value of the environment variable 'LC_ALL' as locale name).

locale-dir NAME

Set the name of the locale directory.

text-domain NAME

Set the textual domain name.

An example:

rule l10n


  locale "pl_PL"


  text-domain "rush-config"


  fall-through

include

The include statement forces inclusion of the named file in that file location:

include FILE

The statement is evaluated when parsing the configuration file, which means that FILE undergoes only tilde expansion: the two characters ~/ appearing at the beginning of file name are replaced with the full path name of the current user's home directory.

If FILE is a directory, that directory is searched for a file whose name coincides with the current user name. If such a file is found, it is included.

In any case, if the named file does not exist, no error is reported, and parsing of the configuration file continues.

Before including the file rush checks if it is secure, using the criteria set in the include-security statement. See its description in the global section, above.

The include statement can be used only within a rule. The included file may not contain rule and global statements.