[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 The configuration file

The main configuration file, usually called `/etc/become/become.conf', contains all the rules which Become uses to decide whether to grant or deny requests. It may also contain additional information for the benefit of Become daemons, if you're using a networked installation.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.1 Requests and rules

Become looks at four pieces of information when it's analysing a request:

Each of these pieces of information is looked at when Become decides whether to honour a request.

The configuration file's main purpose is to describe the conditions under which Become should honour a request. These conditions are described by a number of rules. A rule consists of two lists of users (called `from' and `to'), a list of hosts, and a list of commands. A rule matches a request if:

A request is honoured if there is a rule which matches the request.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.2 Basic configuration file syntax

The configuration file consists of a sequence of statements, each terminated by a semicolon.

Comments begin with a `#' character, and continue to the end of the line. This is the only time newlines behave specially: newlines behave just like any other whitespace characters within statements.

Strings are enclosed in double-quote characters (`"'). Within a string, a backslash causes the following character to be treated literally, whatever it may be (including quotes, backslashes and newlines).

Names begin with an alphabetic character or an underscore, and consist of letters, digits and underscores.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.3 Classes

A class in Become is a set of users, hosts or commands. You can define and name your own classes using statements of the form:

 
user name = class-expr ;
command name = class-expr ;
host name = class-expr ;

A class-expr is an expression defining a class. You can build a complex class out of simple classes using the operators (in ascending precedence order) `,', `-', `|' and `&', which represent the set options `union', `subtraction', `union' (again!), and `intersection'. Subexpressions can be parenthesised to override the default precedence. Once a class name has been defined, as shown above, it can be used in subsequent class expressions.

A single user may be designated by either a user name (in quotes) or an integer uid. Commands and hosts may be designated by quoted strings which may contain wildcards. Host strings are matched against both numeric (dotted quad) IP addresses and the reverse-resolved hostname. Command strings are matched against the absolute pathname of the command the user wants to execute.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.4 Predefined classes

In an attempt to make life a bit easier, Become creates a collection of predefined classes.

The standard classes all and none match anything and nothing respectively. The all class is useful in some contexts: it gives you a way of saying `everything except…', for example:

 
user MUNDANES = all - SYSHACKS;

The none class is provided because it's needed internally anyway and someone might come up with a use for it.

Become also defines some other classes:

If a name is used for both a user and a group, then corresponding class ends up containing the user together with all of the group members. For this reason, it's probably better to use the predefined classes for groups rather than individual users - use quoted user names for individual users.

Note that users and groups are read using the standard get*ent calls and directly from the NIS server (if there is one). The idea here is that a Become server can be run on a machine which allows restricted logins. It still needs to know about all the users known to the outside world.

Netgroups are read only from the NIS servers. In particular, although GNU systems allow netgroup databases to be stored in local files, Become won't read them because there's no defined interface for enumerating netgroups.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.5 Allow statements

The allow statement defines the rules Become uses when deciding whether to grant a request; see Requests and rules.

 
allow [[host-class]] [user-class] -> [user-class] [ : command-class]

(The host-class is optional, but must be enclosed in square brackets if present.)

The four classes in an allow statement are called, respectively, the `host', the `to-user', the `from-user' and the `command'. Any of the four classes may be omitted, and an omitted class defaults to `all'.

When a request is received, Become checks the fields in the request against the classes in each allow statement of the configuration file. If a statement matches, the request is granted; if there are no full matches, the request is denied.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.6 Other statements

Two other statement types are defined. They only have an effect on Become in daemon mode:

 
port port ;
keyfile key-file ;

The port statement specifies the port to which the server should listen; the port may be be an integer or a quoted service name. The keyfile statement instructs Become to use the key from the file named key-file, which must be a quoted string.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.7 An example configuration file

 
#
# become.conf
#
# Example configuration file
#

allow wheel -> "root";

user NEWS = "fred", "jim";
allow NEWS -> "news";

user HTTP = "jim", "bob";
allow ["www.somewhere.com"]
        HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8 Checking and querying the configuration file

At a reasonably sized site, Become configuration files can get rather large, and becomes tricky to work out exactly who's allowed to do what and where.

The bcquery tool provided allows Become configuration files to be verified and queried. It can be used to ensure that a file is syntactically correct before it is deployed, or to enquire about privileges granted.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8.1 Verifying configuration files

A common use of bcquery is to ensure that a configuration file is actually valid. The command

 
bcquery [-file file] -check

verifies that a configuration file conforms to Become's expectations. If there are any errors in file, they are reported, and bcquery will return a nonzero exit code.

If no file is specified, bcquery will read the configuration file which Become itself reads by default, usually /etc/become/become.conf.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8.2 Querying configuration files

The bcquery program will list all rules which match a selected request pattern. For example, you can display all rules which allow a particular user to change identity, or all rules which allow people to assume root privileges on a particular host.

 
bcquery [-file file] query

The following simple queries are supported:

-from user

Matches any rule containing user in its `from' list.

-to user

Matches any rule containing user in its `to' list.

-host host

Matches any rule containing host in its host list.

-command cmd

Matches any rule containing cmd in its `command' list.

Simple queries can be combined using the following operators:

query-a -or query-b

Matches a rule matched by either query-a or query-b.

query-a -and query-b

Matches a rule matched by both query-a and query-b.

-not query

Matches a rule which is not matched by query.

( query )

Matches a rule matched by query (overrides default precedence).

The -and, -or and -not operators may be written &, | and ! respectively, if you prefer, and the -and operator is optional. These characters (and the parentheses ( and )) may need to be quoted to prevent interpretation by the shell.

Some examples may explain what's going on:

`bcquery -from hacker'

Displays all rules applying to user `hacker'.

`bcquery -host somehost -to root'

Displays rules allowing people to become root on somehost.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8.3 Output formats

The bcquery program has two distinct output formats: `rows' and `columns'.

The `columns' format is probably the simpler to understand, and certainly the easier to read. Each matching record is displayed with the lists of users, hosts and commands in columns. A query on the example configuration file (see section An example configuration file) is shown below:

 
FROM            TO              HOST                     COMMAND

frankie         root            ALL                      ALL
selina

fred            news            ALL                      ALL
jim

jim             httpd           www.somewhere.com        /bin/kill
bob                                                      /etc/init.d/httpd

The `columns' format can only show simple lists. A more complex class definition will show up as `<complex>' in a `columns' format listing.

The `rows' format is capable of displaying classes in their full generality, but is harder to parse and read. It displays each list in the form of an expression, in more or less the same syntax as a class definition (see section Classes).

The default behaviour is to use `columns' format where possible, or `rows' format if some of the lists are too complex to be represented in columns. You can select a format explicitly using the -columns or -rows options, which is useful if you're trying to parse the output of bcquery with a script.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8.4 Restricting output

It's also possible to suppress bits of information about each matched rule. For example, you can show only the `from' list, or just the `to' and `host' lists. This is done with the -output option.

Each list is given a letter; the `from' list is called `f', the `to' list `t', the host list `h' and the command list `c'. You can select which lists are displayed by giving the corresponding letters (the order isn't important). You can also turn individual lists on or off by preceding the characters with `+' or `-' characters. If you start with a `+' or `-', then the last-set selection (or the initial default of all-lists-enabled) is modified.

For example, `-output ftc' shows only the `from', `to' and `command' lists. This could be written `-output -h' too, to turn the hosts list off.

This option is mainly useful with the `columns' output format (see section Output formats) to save scripts having to select columns out themselves.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.8.5 bcquery options summary

 
bcquery [option…] [query]

The options available are:

-help

Displays a summary of the available options, and exits.

-file file

Read file, rather than the compiled-in default (usually `/etc/become/become.conf').

-dump

Don't read a configuration file. Instead, display the query tree parsed from the command line. This is a debugging feature.

-check

Don't attempt to output any rules. Instead, just check the configuration file for validity.

-output spec

Selects which columns are to be displayed for each matching rule. For full details, see Restricting output.

-columns
-rows

Forces `columns' or `rows' output format. See section Output formats.

-nohead

Suppress the header line at the top of the output in `columns' mode. Makes the output more amenable to automatic processing (but harder to read).

-from user
-to user
-host hostname
-command cmd

Simple queries for selecting rules. See section Querying configuration files.

-and
-or
-not

Operators for combining queries into something useful. See section Querying configuration files.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3.9 Complete grammar for configuration files

 
file ::= file statement

statement ::= class-def
        | allow-spec
        | port-spec
        | key-spec

class-def ::= `user' name = class-expr `;'
        | `command' name = class-expr `;'
        | `host' name = class-expr `;'

allow-spec ::= `allow' opt-host-spec opt-user-spec
                `->' opt-user-spec opt-command-spec `;'

opt-host-spec ::= `[' class-expr `]'
        | empty

opt-user-spec ::= class-expr
        | empty

opt-command-spec ::= `:' class-expr
        | empty

port-spec ::= `port' integer `;'
        | `port' string `;'

key-spec ::= `keyfile' string `;'

class-expr ::= class-diff-expr
        | class-expr `,' class-diff-expr

class-diff-expr ::= class-isect-expr
        | class-diff-expr `-' class-union-expr

class-union-expr ::= class-isect-expr
        | class-union-expr `|' class-isect-expr

class-isect-expr ::= class-primary
        | class-isect-expr `&' class-primary

class-primary ::= `(' class-expr `)'
        | string
        | integer

integer ::= one or more digits (`0'--`9')

name ::= an alphabetic character or underscore, followed by zero or
                more alphanumeric characters or underscores

string ::= `"' string-chars `"'

string-chars ::= string-chars string-char
        | empty

string-char ::= a `\' followed by any character
        | any character other than `"', `\' or newline

empty ::=

[ < ] [ > ]   [ << ] [ Up ] [ >> ]

This document was generated by Mark Wooding on March, 14 2006 using texi2html 1.76.