\input texinfo @c -*-texinfo-*-
@c
-@c $Id: become.texi,v 1.3 1998/01/20 14:37:43 mdw Exp $
+@c $Id: become.texi,v 1.4 1998/04/23 13:16:14 mdw Exp $
@c
@c Documentation for `become'
@c
@c ----- Revision history ---------------------------------------------------
@c
@c $Log: become.texi,v $
+@c Revision 1.4 1998/04/23 13:16:14 mdw
+@c Include `texinice' to produce decent printed output. Add documentation
+@c for new `bcquery' program. Various fixes, including spelling mistakes,
+@c and some factual inaccuracies.
+@c
@c Revision 1.3 1998/01/20 14:37:43 mdw
@c Fix typo. Short form of `--preserve' should be `-e', not `-p'.
@c
@c ----- Standard boilerplate -----------------------------------------------
@c %**start of header
-@setfilename become
+@setfilename become.info
@settitle Become
@setchapternewpage odd
@footnotestyle end
@paragraphindent 0
@iftex
-@c @smallbook
+@input texinice.tex
@afourpaper
@c @parindent=0pt
@end iftex
@c ----- Useful macros ------------------------------------------------------
-@set version 1.2
+@set version 1.3
@c ----- Copyright matters --------------------------------------------------
@title The Become program
@subtitle Become version @value{version}
-@author Mark Wooding (@email{mdw@@ebi.ac.uk})
+@author Mark Wooding @email{mdw@@ebi.ac.uk}
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 1997 European Bioinformatics Institute.
+Copyright @copyright{} 1998 European Bioinformatics Institute.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
Considerations for X authority
-* The user-group method:: A secure method for handling X authority
+* The user-group method:: A fairly secure way of handling X authority
* Using xauth:: A less secure method, which might be easier
Become administration
The configuration file
+* Requests and rules:: How the configuration file works
* Basic syntax:: Quick overview of Become's syntax
* Classes:: Defining classes of things
* Predefined classes:: Become predefines some (maybe) useful classes
* Allow statements:: Allow users to become other users
* Other statements:: Some other useful statements
* Example configuration file:: An example, showing a few features.
+* Checking and querying:: Checking and querying configuration files
* Complete grammar:: Complete grammar for Become config files
+Checking and querying the configuration file
+
+* Verifying config files:: Checking a configuration file is correct
+* Querying config files:: Asking questions about privileges
+* Output formats:: Different ways of formatting output
+* Restricting output:: Being selective about what gets output
+* bcquery reference:: Complete command line reference
+
Networked configuration
* Choosing servers:: Which servers Become tries to talk to
@node Copying, Introduction, Top, Top
@unnumbered The GNU General Public License
-
@include gpl.texi
group of legitimate users.
The Become program presented here offers a solution to the problems of
-shared accounts. It allows the system adminstrator to define which
+shared accounts. It allows the system administrator to define which
users are allowed access to which accounts, on which hosts, and to
execute which commands. Such shared accounts can then, in general, have
their passwords removed.
@subsubsection The `login' login style
The `login' style causes Become to attempt to emulate a full login. Become
-will empty the environment of any variables which aren't explicitly preserved
-(@pxref{Tweaking the environment}). It will then set the following
-variables:
+will empty the environment of almost variables which aren't explicitly
+preserved (@pxref{Tweaking the environment}). However, the following
+variables are retained:
+
+@itemize @bullet
+@item
+TERM
+@item
+DISPLAY
+@item
+TZ
+@end itemize
+
+@noindent
+It will set the following variables:
@table @code
@item USER
copy of your display's magic cookie, or you can retain permission to read the
cookie file.
+Be aware that allowing a shared account to connect to your X display is a
+security risk.
+
@menu
-* The user-group method:: A secure method for handling X authority
+* The user-group method:: A fairly secure way of handling X authority
* Using xauth:: A less secure method, which might be easier
@end menu
@node The user-group method, Using xauth, X authority, X authority
@subsection The user-group method for handling X authority
-This method is completely secure only if your site uses the `user-group'
-system. In this system, each user is allocated a group containing only that
-user. Usually this is made the user's default primary group, although that's
-not necessary here.
+This method is secure only if your site uses the `user-group' system. In
+this system, each user is allocated a group containing only that user.
+Usually this is made the user's default primary group, although that's not
+necessary here.
When you start a new X session, ensure that your cookie file is owned by you
and your private group. Change the file's permissions so that it's group
become someone else (@pxref{Group permissions}), and that the
@code{XAUTHORITY} variable is set correctly.
+Note that Unix's security mechanisms aren't designed to prevent processes
+owned by the same user from interfering with each other. This method does
+not provide complete security.
+
The following Bourne shell code in a @file{.xinitrc} should do most of the
work:
in @file{.cshrc} for C shell users.
-
@node Using xauth, , The user-group method, X authority
-@subsection The `xauth' method for handling X authority
+@subsection The @code{xauth} method for handling X authority
This method sends your X cookie to the shared account. It's therefore
intrinsically dangerous: you must be able to trust the other users of the
should grant or deny permission.
Standalone installations don't depend on servers being available, or even on
-the existance of a network. They're useful for small sites, or sites with a
+the existence of a network. They're useful for small sites, or sites with a
small number of users. The disadvantages are that reading the configuration
file takes a while, so the program doesn't feel as responsive as it should,
and ensuring that all the hosts' configuration files are synchronised becomes
Become daemons, if you're using a networked installation.
@menu
+* Requests and rules:: How the configuration file works
* Basic syntax:: Quick overview of Become's syntax
* Classes:: Defining classes of things
* Predefined classes:: Become predefines some (maybe) useful classes
* Allow statements:: Allow users to become other users
* Other statements:: Some other useful statements
* Example configuration file:: An example, showing a few features.
+* Checking and querying:: Checking and querying configuration files
* Complete grammar:: Complete grammar for Become config files
@end menu
-@node Basic syntax, Classes, The configuration file, The configuration file
+@node Requests and rules, Basic syntax, The configuration file, The configuration file
+@subsection Requests and rules
+
+Become looks at four pieces of information when it's analysing a request:
+
+@itemize @bullet
+@item
+the user's current identity;
+@item
+the identity the user wishes to assume;
+@item
+the host which generated the request; and
+@item
+the command the user wishes to run.
+@end itemize
+
+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 @emph{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:
+
+@itemize @bullet
+@item
+the user's current identity is in the rule's `from' list;
+@item
+the target user's identity is in the rule's `to' list;
+@item
+the host is in the rule's host list; and
+@item
+the command to be run is in the rule's command list.
+@end itemize
+
+A request is honoured if there is a rule which matches the request.
+
+
+@node Basic syntax, Classes, Requests and rules, The configuration file
@subsection Basic configuration file syntax
The configuration file consists of a sequence of statements, each terminated
Names begin with an alphabetic character or an underscore, and consist of
letters, digits and underscores.
-In general, ...
-
-
@node Classes, Predefined classes, Basic syntax, The configuration file
@subsection Classes
@end example
@noindent
-The @code{none} class isn't particularly useful in itself. It's there for
-completeness.
+The @code{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:
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 wonn't
+systems allow netgroup databases to be stored in local files, Become won't
read them because there's no defined interface for enumerating netgroups.
@node Allow statements, Other statements, Predefined classes, The configuration file
@subsection Allow statements
-Defining classes is just a means to an end. The end is to specify which
-users are allowed to do what, where, and as whom. This is done with an
-@code{allow} statement:
+The @code{allow} statement defines the rules Become uses when deciding
+whether to grant a request; see @ref{Requests and rules}.
@example
allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
@var{key-file}, which must be a quoted string.
-@node Example configuration file, Complete grammar, Other statements, The configuration file
+@node Example configuration file, Checking and querying, Other statements, The configuration file
@subsection An example configuration file
@example
allow NEWS -> "news";
user HTTP = "jim", "bob";
-allow HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
+allow ["www.somewhere.com"]
+ HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
+@end example
+
+
+@node Checking and querying, Complete grammar, Example configuration file, The configuration file
+@subsection 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 @code{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.
+
+@menu
+* Verifying config files:: Checking a configuration file is correct
+* Querying config files:: Asking questions about privileges
+* Output formats:: Different ways of formatting output
+* Restricting output:: Being selective about what gets output
+* bcquery reference:: Complete command line reference
+@end menu
+
+@node Verifying config files, Querying config files, Checking and querying, Checking and querying
+@subsubsection Verifying configuration files
+
+A common use of @code{bcquery} is to ensure that a configuration file is
+actually valid. The command
+
+@example
+bcquery [-file @var{file}] -check
@end example
+@noindent
+verifies that a configuration file conforms to Become's expectations. If
+there are any errors in @var{file}, they are reported, and @code{bcquery}
+will return a nonzero exit code.
+
+If no @var{file} is specified, @code{bcquery} will read the configuration
+file which Become itself reads by default, usually
+@code{/etc/become/become.conf}.
+
+
+@node Querying config files, Output formats, Verifying config files, Checking and querying
+@subsubsection Querying configuration files
-@node Complete grammar, , Example configuration file, The configuration file
+The @code{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.
+
+@example
+bcquery [-file @var{file}] @var{query}
+@end example
+
+The following simple queries are supported:
+
+@table @asis
+@item @code{-from} @var{user}
+Matches any rule containing @var{user} in its `from' list.
+@item @code{-to} @var{user}
+Matches any rule containing @var{user} in its `to' list.
+@item @code{-host} @var{host}
+Matches any rule containing @var{host} in its host list.
+@item @code{-command} @var{cmd}
+Matches any rule containing @var{cmd} in its `command' list.
+@end table
+
+@noindent
+Simple queries can be combined using the following operators:
+
+@table @asis
+@item @var{query-a} @code{-or} @var{query-b}
+Matches a rule matched by either @var{query-a} or @var{query-b}.
+@item @var{query-a} @code{-and} @var{query-b}
+Matches a rule matched by both @var{query-a} and @var{query-b}.
+@item @code{-not} @var{query}
+Matches a rule which is not matched by @var{query}.
+@item @code{(} @var{query} @code{)}
+Matches a rule matched by @var{query} (overrides default precedence).
+@end table
+
+The @code{-and}, @code{-or} and @code{-not} operators may be written
+@code{&}, @code{|} and @code{!} respectively, if you prefer, and the
+@code{-and} operator is optional. These characters (and the parentheses
+@code{(} and @code{)}) may need to be quoted to prevent interpretation by the
+shell.
+
+Some examples may explain what's going on:
+
+@table @samp
+@item bcquery -from hacker
+Displays all rules applying to user `hacker'.
+@item bcquery -host somehost -to root
+Displays rules allowing people to become root on @code{somehost}.
+@end table
+
+
+@node Output formats, Restricting output, Querying config files, Checking and querying
+@subsubsection Output formats
+
+The @code{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
+(@pxref{Example configuration file}) is shown below:
+
+@example
+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
+@end example
+
+@noindent
+The `columns' format can only show simple lists. A more complex class
+definition will show up as @samp{<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
+(@pxref{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 @code{-columns} or @code{-rows}
+options, which is useful if you're trying to parse the output of
+@code{bcquery} with a script.
+
+
+@node Restricting output, bcquery reference, Output formats, Checking and querying
+@subsubsection 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 @code{-output} option.
+
+Each list is given a letter; the `from' list is called @samp{f}, the `to'
+list @samp{t}, the host list @samp{h} and the command list @samp{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 @samp{+} or @samp{-} characters. If you start
+with a @samp{+} or @samp{-}, then the last-set selection (or the initial
+default of all-lists-enabled) is modified.
+
+For example, @samp{-output ftc} shows only the `from', `to' and `command'
+lists. This could be written @samp{-output -h} too, to turn the hosts list
+off.
+
+This option is mainly useful with the `columns' output format (@pxref{Output
+formats}) to save scripts having to select columns out themselves.
+
+
+@node bcquery reference, , Restricting output, Checking and querying
+@subsubsection @code{bcquery} options summary
+
+@example
+bcquery [@var{option}@dots{}] [@var{query}]
+@end example
+
+The @var{option}s available are:
+
+@table @asis
+@item @code{-help}
+Displays a summary of the available options, and exits.
+
+@item @code{-file} @var{file}
+Read @var{file}, rather than the compiled-in default (usually
+@file{/etc/become/become.conf}).
+
+@item @code{-dump}
+Don't read a configuration file. Instead, display the query tree parsed from
+the command line. This is a debugging feature.
+
+@item @code{-check}
+Don't attempt to output any rules. Instead, just check the configuration
+file for validity.
+
+@item @code{-output} @var{spec}
+Selects which columns are to be displayed for each matching rule.
+For full details, see @ref{Restricting output}.
+
+@item @code{-columns}
+@itemx @code{-rows}
+Forces `columns' or `rows' output format. @xref{Output formats}.
+
+@item @code{-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).
+
+@item @code{-from} @var{user}
+@itemx @code{-to} @var{user}
+@itemx @code{-host} @var{hostname}
+@itemx @code{-command} @var{cmd}
+Simple queries for selecting rules. @xref{Querying config files}.
+
+@item @code{-and}
+@itemx @code{-or}
+@itemx @code{-not}
+Operators for combining queries into something useful. @xref{Querying config
+files}.
+@end table
+
+
+@node Complete grammar, , Checking and querying, The configuration file
@subsection Complete grammar for configuration files
@format
@end format
+
@node Networked configuration, , The configuration file, Administering Become
@section Networked configuration
The @var{command} name is used both as the command to execute and passed to
the command as @code{argv[0]}. It is not possible to specify an alternative
-calue to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
+value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
passed as @code{argv[1]} upwards.
If no @var{command} is given, a shell is invoked; the particulars of the
@item -f @var{file}
@itemx --config-file=@var{file}
-Read configuration from @var{file}, instead of the default (usually
-@file{/etc/become/become.conf}).
+Read configuration from @var{file}, instead of the default (set at
+compile time, usually @file{/etc/become/become.conf}).
@end table
The syntax of the configuration file is described in @ref{The configuration
@c @unnumbered Concept index
@c @printindex cp
@c
-@c @contents
+@contents
@bye
~mdw / become / commitdiff