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

       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.