Ubuntu Manpage: rush.rc - configuration rules for rush.

NAME

       rush.rc - configuration rules for rush.

DESCRIPTION

The file /etc/rush.rc contains a set of rules that the rush (1) shell uses in order to
determine whether the user is allowed to execute the requested command and to set up the
environment for its execution.

Empty lines are ignored. Lines beginning with a pound sign are comments and are ignored
as well.

A 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.

If the keyword requires multiple values, its argument is split into words using the
following algorithm:

1. Any sequence of one or more non-whitespace characters is a word.

2. Any sequence of characters enclosed in single or double quotes is a word.

3. Words are separated by any amount of white space.

4. If the keyword expects s-expressions these are treated as words, even if they
contain white space.

Arguments obtained as a result of rules (1) and (2) are subject to backslash
interpretation, during which the following escape sequences are replaced with single
characters:

Sequence Replaced with
\a Audible bell character (ASCII 7)
\b Backspace character (ASCII 8)
\e Escape character (ASCII 27)
\f Form-feed character (ASCII 12)
\n Newline character (ASCII 10)
\r Carriage return character (ASCII 13)
\t Horizontal tabulation character (ASCII 9)
\v Vertical tabulation character (ASCII 11)
\\ A single backslash
\" A double-quote.

Any escape sequence not listed in this table is replaced with its second character.

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 as a last character on line.

GLOBAL STATEMENTS

include FILE
Include the content of the named FILE.

If FILE starts with ~/, these two characters are replaced with the full path name
of current user 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.

include-security ARG...
Configures the security checks that a file must pass in order to be included in the
configuration by the include statement. The arguments are a whitespace-separated
list of check names. The following check names are available:

all Enable all checks.

owner The file must be owned by root.

iwgrp, groupwritablefile
Reject group-writable files.

iwoth, worldwritablefile
Reject world-writable files.

dir_iwgrp, groupwritabledir
Reject files that reside in a group writable directory.

dir_iwoth, worldwritabledir
Reject files that reside in a world writable directory.

link The file may not be is a symbolic link to a file residing in a group or
world writable directory.

debug NUMBER
Sets the debugging level. The greater is the NUMBER, the more verbose is the
logging. The debugging information is reported via syslog(3) using authpriv,
priority debug.

Currently, three debugging levels are implemented:

1 A minimum debugging level, and the only one whose messages are logged using
the priority notice. At this level, rush only logs requests and rules
selected to handle them.

2 List all actions executed when serving requests.

3 Verbosely describe parsing of the configuration file.

regex FLAGS
Defines what kind of regular expressions will be used in subsequent command, match,
and transform statements.

Each flag is a word specifying some regular expression feature. It can be preceded
by + to enable this feature (this is the default), or by - to disable it. Valid
flags are:

extended
Use POSIX Extended Regular Expression syntax. This is the default.

basic Use basic regular expressions. Equivalent to -extended.

icase Do not differentiate case. Subsequent regex matches will be case
insensitive.

usage-error TEXT
Define a textual message which is returned to the remote party if a usage error
occurs. The default is

You are not permitted to execute this command.

nologin-error TEXT
Define a textual message which is returned to the remote user if there is no such
user name in the password database. The default is:

You do not have interactive login access to this machine.

config-error TEXT
Define a textual message which is returned to the remote party if a system error
occurs. The default is:

A system error occurred while attempting to execute command.

RULES

Statements are grouped into rules. A rule begins with the following construct

rule TAG
The TAG argument is optional. If it is given, it supplies a a (presumably unique)
identifier, which will be used to label this rule. Every diagnostic regarding this
rule will be marked with this tag. For rules without explicit tag, default tags
will be supplied, constructed by concatenating a pound character and the ordinal
number of rule in the configuration file, in decimal notation (rule numbering
starts from 1).

The statements that can be used within a rule fall into several distinct categories.

Conditionals
A conditional statement evaluates to a boolean value. All conditionals are tested in
order of their appearance in the rule and are tied together using boolean shortcut AND
evaluation: if any of them yields false, the rest of statements is skipped and next rule
is tried.

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
These statements transform the command line.

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:

N Index of the word in command line.

FILE Name of the map file. It must be an absolute file name (i.e. it must start
with / or ~/fR.

DELIM A string containing allowed field delimiters.

PATTERN
The value of the lookup key. Before using, it is expanded as described
above.

KN Number of the key field in FILE. Fields are numbered starting from 1.

VN Number of the value field.

DFL If supplied, this value is used as a replacement value, when the key was not
found in @var{file}.
The map file consists of records, separated by newline characters. Each record consists
of fields, separated by delimiters given the DELIM argument. If DELIM contains a space
character, then fields may be delimited by any amount of whitespace characters (spaces
and/or tabulations). Otherwise, exactly one delimiter delimits fields.

Fields are numbered starting from 1.

System Actions
System actions provide interface to the operating system.

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:

- (a dash)
Clear the environment. If used, this must be the very first argument.

-NAME Unset the environment variable NAME.

-NAME=VAL
Unset the environment variable NAME only if its value is VAL.

NAME Retain the environment variable NAME.

NAME=VALUE
Set the environment variable NAME to the given VALUE.

NAME+=VALUE
Retain the variable NAME and append VALUE to its value. If no such variable
is present in the environment, it is created and VALUE is assigned to it.
However, if VALUE starts with a punctuation character, this character is
removed from it before the assignment. This is convenient for using this
construct with environment variables like PATH, e.g.:
PATH+=:/sbin

NAME=+VALUE
Retain variable VALUE and add VALUE to the beginning of its value. If no
such variable is defined in the environment, it is created and VALUE is
assigned to it. However, if VALUE ends with a punctuation character, this
character is removed from it before assignment.

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
GNU Rush is able to operate in two modes, called 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.

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
The following configuration directives control 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.

AUTHORS

       Sergey Poznyakoff

BUG REPORTS

       Report bugs to <bug-rush@gnu.org.ua>.

COPYRIGHT

       Copyright © 2016 Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
       This is free software: you are free to change and redistribute it.  There is NO  WARRANTY,
       to the extent permitted by law.