bionic (5) rush.rc.5.gz

Provided by: rush_1.8+dfsg-1.1_amd64 bug

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.

SEE ALSO

       rush(1), rushlast(1), rushwho(1).

AUTHORS

       Sergey Poznyakoff

BUG REPORTS

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

       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.