Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
RUSH.RC(5)		      Rush User	Reference		    RUSH.RC(5)

       rush.rc - configuration rules for remote	user shell

       The  file  /etc/rush.rc	contains a set of rules	that the rush(8) 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 com-
       ments and are ignored as	well.

       Except for comments and empty lines, each  line	of  the	 configuration
       file  consists  of  the	keyword	 and optional value, and constitutes a
       statement.  Exceedingly long lines may be split across multiple	physi-
       cal lines, by ending each line with a backslash immediately followed by
       a newline.  Statements fall into	two major classes: section and regular
       statements.   A section statement serves	as a container for one or more
       regular statements that pursue the same goal, thus playing the role  of
       a  chapter in a book.  A	regular	statement modifies a certain aspect of
       the program's behavior.

       The overall file	structure is as	follows:

	 rush 2.0

	   keyword value

	 rule A
	   keyword value

	 rule B
	   keyword value

       A configuration file must begin with a rush  statement  indicating  the
       version	of the syntax this file	uses.  Current versions	of rush	imple-
       ment syntax version 2.0.	 In the	absence	of the initial rush statement,
       the program will	treat the configuration	file as	written	in legacy con-
       figuration syntax  (see
       for details).

       There  are two section statements: global and rule.  The	global section
       contains	statements configuring the behavior of the program in general.
       There can be as many global statements in the configuration as you con-
       sider necessary,	each of	them affecting the material  up	 to  the  next
       global statement, or end	of the file, whichever occurs first.

       Examples	of statements that can be used in a global section are:	debug,
       which sets the debug verbosity level, message, which  configures	 error
       messages, etc.  See the global section for the full list.

       One  or	more rule statements constitute	the core of the	configuration.
       Each rule statement provides a recipe for serving a specific  class  of
       input  commands.	 When rush is invoked with a specific command, it will
       scan the	configuration file looking for a rule  that  matches  the  re-
       quested	command	 line.	 If  such a rule is found, it will be applied.
       Commands	that don't match any rule will be rejected.

       A rule statement	may be followed	by a tag,  an  arbitrary  sequence  of
       non-whitespace  characters  serving as a	label for this rule.  This se-
       quence will be used in diagnostic messages to identify this  rule.   In
       the  absence  of	 user-supplied tag, the	default	one will be generated,
       consisting of the # symbol followed by the ordinal number of  the  rule
       in the configuration file (started with 1).

       To  match  a  particular	 command,  each	 rule should contain the match
       statement.  Its argument	is a conditional expression that  can  contain
       comparison  and	boolean	operators.  The	operands can refer to the com-
       mand line using shell-like variables: $command to refer to  the	entire
       command	line,  $#, referring to	the number of arguments	in the command
       line (the command itself	being counted as one  of  the  arguments),  $0
       meaning the command name, and $1, $2, etc., referring to	the particular
       command line arguments (arguments past the ninth	one  can  be  accessed
       as, e.g.	 ${10}).  For example, the following rule:

	   match $command == "ls"

       will match only the ls command without arguments.

       The  ~ (tilde) operator denotes regular expression matching.  For exam-
       ple, the	following rule matches ls command,  optionally	preceded  with
       any path	prefix:

	   match $0 ~ "^(.*/)?ls$"

       Match  expressions can contain terms of arbitrary complexity.  Consider
       the following example:

	   match $0 ~ "^(.*/)?ls$" && $# == 2 \
		 && $1 !~ "^(/|/etc)$"

       This rule will match any	ls command having exactly one argument,	unless
       that  argument  is / or /etc.  Notice the use of	the !~ operator	to de-
       note the	negated	regular	expression matching, and the use of  backslash
       to split	a single expression across two physical	lines.

       Variables  are referenced using the same	syntax as in shell.  For exam-
       ple, ${1:-/bin} expands to the value of the first parameter, if	it  is
       supplied, or to the string "/bin" otherwise.  For details. see the sec-

       Although	important, the match statement is  not	mandatory  in  a  rule
       statement.   If	it  is	absent,	 the rule will match any command line.
       This is normally	used in	fall-through rules.  A fall-through  rule  ap-
       plies  modifications  to	 the command environment.  After applying such
       rule, the scanning resumes at the rule that  follows  it.  Fall-through
       rules are marked	with the fall-through statement.

       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 follow-
       ing  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 re-
       fer 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-de-
       fined  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	alpha-
       betical character or underscore and contain only	 letters,  digits  and
       underscores.  References	to user-defined	variables follow the same syn-
       tax as for built-in ones.

       The following example uses temporary variable temp to  swap  two	 argu-

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

       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

       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

       Whereas delete and unset	remove arguments at given positions,  the  re-
       mopt  statement allows you to remove specific command line options from
       the command line.  This is useful to ensure no potentially harmful  op-
       tions  can be passed by the user.  The statement	takes one or two argu-
       ments.  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	state-
       ment 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 ar-
       guments 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

       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


	 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

       A  statement  consists  of  a  keyword  and arguments, separated	by any
       amount of whitespace.  Arguments	can be one of the following:

	      Identifiers begin	with a letter and consist of letters,  digits,
	      underscores  and	dashes.	  They	serve as keywords and variable

       Decimal numbers
	      A	sequence of decimal digits, optionally preceded	by a minus  or
	      plus sign.

       Unquoted	strings
	      An unquoted string is any	contiguous sequence of any characters,
	      except newlines, whitespace and the  following  special  charac-
	      ters: \, ", !, =,	<, >, (, ), {, }, [, ],	$, %, &, |, ~, #.

       Quoted strings
	      A	 quoted	string is a sequence of	characters enclosed in double-
	      quotes.  Quoted strings are subject to backslash interpretation,
	      backreference interpretation and variable	expansion.

	      During backslash interpretation, the escape sequences are	recog-
	      nized and	replaced as per	table below:

		      Sequence	  Replaced with
		      \a	  Audible bell character (ASCII	7)
		      \b	  Backspace character (ASCII 8)
		      \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.
		      \%	  Percent sign

	      In addition, the sequence	\newline is removed from  the  string.
	      This allows to split long	strings	over several physical lines.

	      During the backreference interpretation, references to parenthe-
	      sized groups in regular expression are replaced with the	actual
	      content  of the corresponding group in the most recently matched
	      string.  A reference is %{N} where N is a	decimal	number.	 If  N
	      is one digit, curly braces can be	omitted: %N If the % character
	      resulted from previous backslash interpretation,	no  backrefer-
	      ence interpretation occurs.

	      Strings  used  in	 the left-hand side of a comparison expression
	      are subject to variable expansion.  This is discussed later.

	      The construct %{N} is replaced with the substring	 that  matched
	      the Nth parenthesized subgroup in	a most recently	performed reg-
	      ular expression match.  If N is one digit, curly braces  can  be

       Variable	references
	      Variable	references  consist of a $ sign, followed by the posi-
	      tional argument number or	variable name, optionally enclosed  in
	      curly  braces.   Positional arguments greater than 9 must	be en-
	      closed in	curly braces.  The variable name must follow the rules
	      for  valid  identifiers: it must begin with a letter and consist
	      of letters, digits and  underscores.   Variable  name  in	 curly
	      braces  can be followed by -, =, ?, or +,	optionally preceded by
	      :	as summarized in the table below:

		      Reference		    Meaning
		      ${VAR:-WORD}	    Use	Default	Values
		      ${VAR:=WORD}	    Assign Default Values
		      ${VAR:?WORD}	    Display Error if Null or Unset
		      ${VAR:+WORD}	    Use	Alternate Value

	      where WORD stands	for any	valid token as described in this  sec-
	      tion.   See the section REFERENCE: VARIABLE EXPANSION, for a de-
	      tailed discussion	of these forms and their meaning.

       Comparison and boolean operators

		      &&		    Boolean AND
		      ||		    Boolean OR
		      !			    Boolean negation
		      ==		    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
		      in		    Membership in set of strings
		      group		    Membership in UNIX group
		      =			    Assignment
		      =~		    Regular expression substitution

       Most statements in the configuration file  undergo  variable  expansion
       prior to	their use.  During variable expansion, references to variables
       in the string are replaced with their actual values.  A variable	refer-
       ence has	two basic forms:


       where  V	 is  either the	name of	the variable (request, environment, or
       user-defined), or the index of the positional variable.	 The  notation
       in  curly braces	serves several purposes.  First, it is obligatory if V
       is an index of the positional variable that is negative or greater than
       9.   Secondly,  it  should be used if the variable reference is immedi-
       ately followed by an alphanumeric symbol, which will otherwise be  con-
       sidered	part  of it (as	in ${home}dir).	 Finally, this form allows for
       specifying the action to	take if	the variable is	undefined  or  expands
       to an empty value.

       The following special forms are recognized:

	      Use Default Values.  If VARIABLE is unset	or null, the expansion
	      of WORD is substituted.  Otherwise, the  value  of  VARIABLE  is

	      Assign Default Values.  If VARIABLE is unset or null, the	expan-
	      sion of WORD is assigned to the variable.	 The value of VARIABLE
	      is then substituted.

	      Display  Error  if Null or Unset.	 If VARIABLE is	null or	unset,
	      the expansion of WORD (or	a message to that effect  if  WORD  is
	      not  present)  is	output to the current logging channel.	Other-
	      wise, the	value of VARIABLE is substituted.

	      Use Alternate Value.  If VARIABLE	is null	or unset,  nothing  is
	      substituted, otherwise the expansion of WORD is substituted.

       There  are  three  global statements, two of which can contain multiple

       rush 2.0
	      Declares the version of the syntax this  configuration  file  is
	      written  in.  This must be the first statement in	the configura-
	      tion file.  If this statement is missing,	the configuration file
	      will  be treated as legacy configuration file from previous ver-
	      sions of GNU rush.  For the discussion of	the legacy  configura-
	      tion   file,   please   refer   to

       global Defines global settings.

       rule [TAG]
	      Contains a set of	rules for a certain  class  of	input  command

       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 en-
       countered 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 val-
	      ues.  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:

		  This error is	reported when rush has	been  invoked  improp-
		  erly.	 The default text is:

		  "You are not permitted to execute this command."

		  A message which is returned if there is no such user name in
		  the password database.  Defaults to:

		  "You are not permitted to execute this command."

		  Define a textual message which is returned if	the configura-
		  tion file contained errors.  Default is:

		  "Local configuration error occurred."

		  Define a textual message which is returned if	a system error
		  occurs.  Default is:

		  "A system error occurred while attempting  to	 execute  com-

       regexp FLAG [FLAG...]
	      Configure	 the  type of regular expressions to be	used by	subse-
	      quent 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:

		  Use POSIX Extended Regular Expression	syntax when interpret-
		  ing regex.  This is the default.

	   basic  Use basic regular expressions.  Equivalent to	-extended.

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

       include-security	FLAG [FLAG...]
	      Configure	 the  security	checks for include files.  Valid flags

	   all	  Enable all checks.

	   owner  The file must	be owned by root.

	   iwgrp or groupwritablefile
		  Forbid group writable	files.

	   iwoth or worldwritablefile
		  Forbid world writable	files.

	   dir_iwgrp or	groupwritabledir
		  Forbid files that reside in group writable directories.

	   dir_iwoth or	worldwritabledir
		  Forbid files that reside in world writable directories.

	   link	  Forbid symbolic links	to files residing in  group  or	 world
		  writable directories.

       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.   De-
	      fault 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.

       Defines a rule.	This is	a block	statement, which means that all	state-
       ments  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 de-
       fault one, which	is constructed by concatenating	the  #	character  and
       the  ordinal number of rule in the configuration	file, in decimal nota-
       tion.  Rule numbering starts from 1.

       A rule can contain the following	statements:

       match EXPR
	      Defines conditions that decide whether the rule matches the par-
	      ticular  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	refer-
	      ence.  The rhs is	a string or number.  Prior to evaluating  sim-
	      ple  expression,	its LHS	undergoes variable expansion.  In con-
	      trast, 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  us-
	      ing 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

       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:


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

       As in sed, you can give several replace expressions, separated by semi-

       The supported FLAGS are:

       g      Apply the	replacement to all matches to the REGEXP, not just the

       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  im-
       plementation  in	 this regard, so the interaction is defined to be: ig-
       nore 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	expan-
	      sion 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 let-
	      ter, optionally followed by a  colon  if	that  option  takes  a
	      mandatory	argument, or by	two colons if it takes an optional ar-

       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.

	      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 permis-
	      sions 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 charac-
	      ters.  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	white-
	      space  characters	 (spaces  and/or tabulations).	Otherwise, ex-
	      actly 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	 argu-
	      ment.  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 as-
	      signed to	the variable.  Otherwise, if DEFAULT is	 supplied,  it
	      is  assigned  to	the variable.  Otherwise, the variable remains

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

       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	match-
	      ing  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  sub-
	      ject 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

       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  nu-
	      meric 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 re-
	      placed 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 argu-
	      ment 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

	   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 (negative = high priority)

       If some limit cannot be set, execution of the rule aborts.  In particu-
       lar, 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 si-
       multaneously 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 sub-
       section 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 con-
	      figuration.  Any modifications to	the request found in the fall-
	      through  rule  take  effect immediately, which means that	subse-
	      quent rules will see modified command line and environment.  Ex-
	      ecution  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 sub-
	      sequent 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  subpro-
       cess,  and  remains in memory supervising its execution.	 Once the com-
       mand terminates,	rush exits.

       One advantage of	the forked mode	is that	it allows you to keep account-
       ing,  i.e.   to note who	is doing what and to keep a history of invoca-
       tions.  The accounting, in turn,	can be used to limit simultaneous exe-
       cutions	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 sock-
       ets, after completing user request.  It is  done	 using	the  following

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

       Allowed formats for URL are:

	      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	estab-
       lishing	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 (-) acknowledg-
       ment, optionally	followed by a message of explanation,  and  terminated
       with a CRLF.

       If  positive acknowledgment is received,	rush sends a single line, con-
       sisting 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  ac-
       cess  to	interactive shells.  GNU rush contains provisions for such us-
       age.  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  val-
	      ues),  this  statement  marks the	rule it	appears	in as interac-
	      tive.  This rule will match only if rush is invoked without com-
	      mand line	arguments.

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

       An example

	 rule login
	   interactive true
	   group rshell
	   map program /etc/ : ${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/  This map file	consists of two	fields,	 sepa-
       rated  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.

       The following statement allow you to  provide  translations  (localiza-
       tions) 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 en-
	      vironment	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"

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

       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	crite-
       ria  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.

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

       Sergey Poznyakoff

       Report bugs to <>.

       Copyright (C) 2016-2019 Sergey Poznyakoff
       License GPLv3+: GNU GPL version 3 or later <
       This is free software: you are free  to	change	and  redistribute  it.
       There is	NO WARRANTY, to	the extent permitted by	law.

RUSH.RC				 July 1, 2019			    RUSH.RC(5)


Want to link to this manual page? Use this URL:

home | help