Conditionals¶

command REGEX

True, if the current command line matches regular expression REGEX. By default, POSIX extended regular expressions are used. This, however can be changed using the regex (see below).

match[N] IREGEX

True, if the Nth word from the command line matches regular expression REGEX. Notice, that square brackets form part of the statement syntax. A special symbol $ can be used instead of N to denote the last word.

The command line is split into words using the same rules as used in /bin/sh.

argc OP NUM

Compare the number of command line arguments to NUM. The comparison operator OP can be one of the following: = (or ==), !=, <, <=, >, >=.

uid [OP] UID

Compare the UID of the user who started rush to UID. The latter may be either a numeric UID or a name of an existing user. The comparison operator OP has the same values as discussed above. If absent, == is assumed.

gid [OP] GID

Compare the GID of the user who started rush to GID. It can be either a numeric value or a name of an existing group. The comparison operator OP has the same values as discussed above. If absent, == is assumed.

user NAMES

Argument is a whitespace-separated list of user names. This condition yields true, if the user name matches one of the listed names. String comparisons are case-sensitive.

group 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 matches one of listed names. String comparisons are case-sensitive.

Transformations¶

set PATTERN

Replaces entire command line with the expansion of PATTERN.

set[N] PATTERN

Replaces the Nth word in the command line with the expansion of PATTERN. Notice, that square brackets are part of the statement syntax.

delete[N]

Deletes the Nth word.

delete N M

Deletes words between N and M, inclusive.

transform EXPR

Apply a sed(1) expression EXPR to entire command line. For example, the statement below adds a -t option after the command name:

transform s/^[^[:space:]]+/& -t/

transform PATTERN EXPR

Applies the sed(1) expression EXPR to the expansion of PATTERN and replaces entire command line with the result.

transform[N] EXPR

Applies expression EXPR to the Nth word from the command line. Notice, that square brackets are part of the statement syntax.

transform[N] PATTERN EXPR

Applies the expression EXPR to the expansion of PATTERN and replaces N word in the command line with the result.

E.g. to replace the 0th argument with the base name of the command prefixed with a dash:

transform[0] ${^} s,.*/,-,

map[N] FILE DELIM PATTERN KN VN DFL

Expand the PATTERN and scan the disk file FILE for the record whose KNth word matches the expansion (words are delimited with characters from DELIM). If found, replace the Nth command line word with the VNth word from the record.

The arguments are:

Fields are numbered starting from 1.

System Actions¶

umask MASK

Set the umask. The argument is an octal value not greater than 0777. The default umask is 022.

newgrp GID

Changes the current group ID to GID, which is either a numeric value or a name of an existing group. The keyword can also be spelled as newgroup.

chroot DIR

Change the root directory to DIR. This directory will be used for file names beginning with /. A tilde at the start of DIR is replaced with the user's home directory.

chdir DIR

Change to the directory DIR. The argument is subject to tilde-expansion as in chroot, above. If both chdir and chroot are specified, then chroot is executed first.

limits RES

Imposes limits on system resources. 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.

	Command	The limit it sets
	A	max address space (KB)
	C	max core file size (KB)
	D	max data size (KB)
	F	maximum file size (KB)
	M	max locked-in-memory address space (KB)
	N	max number of open files
	R	max resident set size (KB)
	S	max stack size (KB)
	T	max CPU time (MIN)
	U	max number of processes
	L	max number of logins for this user (see below)
	P	process priority -20..20
    

If some limit cannot be set, execution of the rule aborts.

The use of the L resource automatically enables forked mode.

Environment¶

env ARG...

Modifies the execution environment. Arguments are a list of specifiers separated by any amount of whitespace. Each specifier can contain references to variables from the inherited environment. The reference syntax is the same as in sh(1).

The following specifiers are allowed:

PATH+=:/sbin

Fall-Through¶

fall-through

Declares a fall-through rule -- a special rule that does not execute the requested command. Instead, when rush encounters a matching fall-through rule, it evaluates it and continues scanning its configuration for the next matching rule. Any transformations and environment modifications 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 usual rule is found.

E.g.:

rule default
    umask 002
    env - HOME USERNAME PATH
    fall-through

Interactive Access¶

interactive

Marks the rule it appears in as interactive.

When rush is invoked without -c option (interactive usage), it will consider only rules marked with interactive keywords. This allows for providing interactive shell access.

The default interactive rule terminates by invoking /bin/sh.

The command name argument (argv[0]) is set to the basename of the program being executed prefixed with a dash.

Example:

rule login
    interactive
    group shell
    set[0] /bin/bash

Accounting and Forked Mode¶

In forked mode, rush executes the requested command in a subprocess, and remains in memory supervising its execution. Once the command terminates, the main rush process exits too.

fork BOOL

Enable or disable forked mode. The values yes, on, t, true, 1 stand for true, and no, off, nil, false, or 0 stand for false.

The main advantage of the forked mode is that it allows one to run 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 in the limit statement (see above).

acct BOOL

Turn accounting mode on or off, depending on BOOL.

Notice, that there is no need in explicit acct on command, if you use the limit statement with L command, as this enables accounting implicitly.

Most often, accounting should affect all rules and therefore it is normally used in a fall-through rule at the beginning of the configuration file, e.g.:

rule default
    acct on
    fall-through 

Notification¶

post-socket URL

After completing the command, notify the socket at URL about the fact. This statement implies forked mode.

Valid formats for URL are:

inet://HOST[:PORT]

Connect to remote HOST using TCP/IP. HOST 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 absent, TCPMUX (port 1) is assumed.

unix://FILENAME, or local://FILENAME

Connect to a UNIX socket.

The GNU Rush notification protocol is based on TCPMUX.

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 plus or minus character, indicating positive or negative acknowledgment, immediately followed by an optional 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.

Exit¶

exit FD MESSAGE

Write textual message to a file descriptor, given by the optional argument FD. If FD is absent, the descriptor 2 (standard error) is used.

The MESSAGE argument is subject to backslash interpretation.

Localization¶

locale NAME

Sets the locale name.

locale-dir DIR

Sets the name of the locale directory.

text-domain NAME

Sets the textual domain name.