Add new file `texinice.tex' to the distribution.

[become] / manual / become.texi

\input texinfo @c -*-texinfo-*-
@c
@c $Id: become.texi,v 1.3 1998/01/20 14:37:43 mdw Exp $
@c
@c Documentation for `become'
@c
@c (c) 1998 EBI
@c

@c ----- Revision history ---------------------------------------------------
@c
@c $Log: become.texi,v $
@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 Revision 1.2  1998/01/12 16:41:31  mdw
@c Tidying for new release versions.  Fix copyright date.
@c
@c Revision 1.1  1997/09/18 11:16:34  mdw
@c Brand new Texinfo manual, with wider scope than the original LaTeX one.
@c

@c ----- Standard boilerplate -----------------------------------------------

@c %**start of header
@setfilename become
@settitle Become
@setchapternewpage odd
@footnotestyle end
@paragraphindent 0
@iftex
@c @smallbook
@afourpaper
@c @parindent=0pt
@end iftex
@c %**end of header

@c ----- Useful macros ------------------------------------------------------

@set version 1.2

@c ----- Copyright matters --------------------------------------------------

@c --- The `Info' version ---

@ifinfo

This file documents Become version @value{version}.

Copyright (c) 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
preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries a copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled `Copying' and `GNU General Public License' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the European Bioinformatics Institute.

@end ifinfo

@c --- Printed title page ---

@titlepage

@title The Become program
@subtitle Become version @value{version}
@author Mark Wooding (@email{mdw@@ebi.ac.uk})
@page

@vskip 0pt plus 1filll

Copyright @copyright{} 1997 European Bioinformatics Institute.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided also that the
sections entitled `Copying' and `GNU General Public License' are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the European Bioinformatics Institute.

@end titlepage


@c --------------------------------------------------------------------------
@ifinfo
@node Top, Copying, (dir), (dir)
@top Become


Become is a system for managing shared accounts.  It allows users to
`become' other users in order to do useful work.  It can be managed on a
central server (or a small number of central servers), or it can run
standalone.

This file documents Become version @value{version}.

@end ifinfo

@menu
* Copying::                     Your rights to distribute and modify
* Introduction::                A brief introduction to Become
* Becoming someone else::       How to become somebody else
* Administering Become::        How to maintain Become
* Invoking Become::             Reference to Become's command line options

 --- The Detailed Node Listing ---

Becoming someone else

* Terminology::                 Some important terms defined
* Environment::                 Login styles and environment variables
* Group permissions::           How Become handles group permissions
* X authority::                 Problems with X authority files
* Running commands::            Running commands other than a shell

How Become sets up the environment

* New environment variables::   Become adds some useful environment variables
* Login styles::                Choose how Become sets the environment
* Tweaking the environment::    Altering individual environment variables
* Removed variables::           Some environment variables aren't passed on

Login styles

* The preserve style::          Preserve the current environment
* The set-user style::          Set user-specific variables (like @code{su})
* The login style::             Clear the environment (like @code{login})

How Become handles groups

* Primary group selection::     Setting the new primary group
* Subsidiary groups::           Setting subsidiary group memberships

Considerations for X authority

* The user-group method::       A secure method for handling X authority
* Using xauth::                 A less secure method, which might be easier

Become administration

* Configuration files::         Overview of Become's configuration files
* Standalone or networked::     The two main types of Become installations
* The configuration file::      How to define who's allowed to do what
* Networked configuration::     Considerations for networked installations

The configuration file

* 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.
* Complete grammar::            Complete grammar for Become config files

Networked configuration

* Choosing servers::            Which servers Become tries to talk to
* Setting up keys::             How to generate keys for Become
* Random number files::         Become keeps random number state around
* Issuing a new key::           How to issue new keys without disruption

Setting up keys

* Invoking keygen::             How to use the @code{keygen} program

Invoking Become

* Becoming another user::       Options for becoming another user
* Starting Become daemons::     Options for starting Become daemons
* Debugging options::           Options to use when Become goes wrong
@end menu

@c --------------------------------------------------------------------------
@node Copying, Introduction, Top, Top
@unnumbered The GNU General Public License


@include gpl.texi


@c --------------------------------------------------------------------------
@node Introduction, Becoming someone else, Copying, Top
@unnumbered Introduction


It's often useful to be able to share accounts between a number of
users.  For example, a group maintaining an externally visible service
need to be able to start and kill the server process.  Giving such a
shared account a password is a fairly bad plan: such passwords tend not
to get changed very often, and they have a habit of spreading beyond the
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
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.

This coincidentally has another advantage: when `becoming' to a shared
account, a user can retain her@footnote{Or his.  I'll choose one or the
other fairly randomly throughout this manual.} own environment, which
she's carefully crafted and honed over the years, rather then being
presented with some lowest-common-denominator setup which probably
doesn't even use the right shell.

The configuration file for Become can either be distributed to all the
various hosts in a network or a few carefully set up and secure servers
(@pxref{Standalone or networked}).


@c --------------------------------------------------------------------------
@node Becoming someone else, Administering Become, Introduction, Top
@chapter Becoming someone else


The simplest way to become someone else is to say

@example
become @var{user}
@end example

@noindent
Become will check to see whether you're allowed to become @var{user}.  If you
are, it starts a shell process with the user-id set to @var{user}.  Any
commands you type are executed with the privileges of @var{user}.

The full invocation is slightly more complicated:

@example
become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
@end example

Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
order -- the important point is that all of them appear before the
@var{command}, if there is one.

@menu
* Terminology::                 Some important terms defined
* Environment::                 Login styles and environment variables
* Group permissions::           How Become handles group permissions
* X authority::                 Problems with X authority files
* Running commands::            Running commands other than a shell
@end menu



@node Terminology, Environment, Becoming someone else, Becoming someone else
@section Terminology

The following terms get used quite a bit in the following text:

@table @asis
@item request
An invocation of Become, asking permission to become another user.

@item old user
The (real) user id of the process which invoked Become; usually, this will be
your normal user id.

@item target user
The user whom you want to become, named in a request.
@end table



@node Environment, Group permissions, Terminology, Becoming someone else
@section How Become sets up the environment

There are thorny problems with handling the user's environment.  It seems
that (the author's initial assessment notwithstanding) there is no single
best way of handling environment variables.  As a result, Become can do just
about everything you might want it to.  This gets slightly complicated.
Don't worry: it's not as hard as all that.

@menu
* New environment variables::   Become adds some useful environment variables
* Login styles::                Choose how Become sets the environment
* Tweaking the environment::    Altering individual environment variables
* Removed variables::           Some environment variables aren't passed on
@end menu


@node New environment variables, Login styles, Environment, Environment
@subsection Environment variables created by Become

To help you (and, more importantly, your startup scripts) keep track of who
you are, and who you were originally, Become adds some variables to the
environment of any processes it starts.

@table @code
@item BECOME_USER
The name of the target user (i.e., the user you are now).  It might be useful
to test this value in shell startup scripts, for example.

@item BECOME_HOME
The home directory of the target user.  It can be handy to read startup and
other configuration files from here.

@item BECOME_OLD_USER
The name of the user who invoked Become.

@item BECOME_OLD_HOME
The home directory of the `old' user.

@item BECOME_ORIGINAL_USER
This is intended to be the name you logged in with.  If it's unset, Become
sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
unchanged.

@item BECOME_ORIGINAL_HOME
This is intended to be the home directory you logged in with.  If it's unset,
Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
it unchanged.
@end table

Don't even think about relying on these variables as a form of
authentication.  It won't work.  They're provided only to help organise
startup scripts.



@node Login styles, Tweaking the environment, New environment variables, Environment
@subsection Login styles

Originally, Become always tried to preserve your environment.  There's a
rational explanation for this approach, which is given in the description of
the `preserve' style below.  Unfortunately, not everyone liked this
approach.  As a result, there's now a collection of different login styles.

Login styles are selected by giving command line arguments:

@table @code
@item -e
@itemx --preserve
The original style: try to preserve the existing user's environment as much
as possible.

@item -s
@itemx --set-user
Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
the target user rather than the old user.  All other variables are preserved.

@item -l
@itemx --login
Attempts to make the `become' process as much like a real login as possible.
All variables not explicitly preserved are deleted, and a new environment is
built, reflecting the target user.
@end table

The various styles, and the reasons behind them, are described below.

@menu
* The preserve style::          Preserve the current environment
* The set-user style::          Set user-specific variables (like @code{su})
* The login style::             Clear the environment (like @code{login})
@end menu


@node The preserve style, The set-user style, Login styles, Login styles
@subsubsection The `preserve' login style

You've spent many hours (days? weeks, even?) customising and honing your
startup files, learning how to use your shell, and tweaking your favourite
text editor until it's just the way you like it.  So there can be few things
more annoying than logging into a shared account to find out that the shell's
wrong, your editor startup files are ignored, and nothing works quite the way
you'd like it to.  Typically you can't change this without annoying the other
users: the result is a horrible compromise which dissatisfies everyone
equally.

The `preserve' style lets you take your standard environment with you when
you become someone else.  It tries hard not to modify any environment
variables.

Become starts your standard shell.  If you have an environment variable
@code{SHELL} defined, than this is executed.  Otherwise, the shell specified
in your entry in the password file is used.  (You must have permission to
execute whatever shell is chosen as the target user, or you'll just be given
an error message.)

Most programs look at environment variables in preference to looking up
entries in the password database; e.g., they tend to use @code{USER} or
@code{LOGNAME} for the user name, and @code{HOME} for your home directory.
As a result, most programs will continue to find their configuration files in
your home directory.  Also, systems like RCS will use your real name, rather
than the name of the user that you have become.

To make best use of this login style, you may need to adjust your login
scripts to notice when @code{BECOME_USER} is someone else, and read in
appropriate definitions.  For example, a `bash' user might say something like
this in her @file{.bashrc}:

@example
if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
@end example

@noindent
Similarly, a C shell user (either `tcsh' or `csh') might say something like

@example
if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
@end example

(Note that plain Bourne shell users have a slight problem, because the Bourne
shell only reads configuration things on a login, not when a normal
interactive shell is started.)


@node The set-user style, The login style, The preserve style, Login styles
@subsubsection The `set-user' login style

The author sees the main use of Become as allowing a user to acquire the
privileges associated with a shared account without all the problems which
shared accounts usually cause.  To the author's way of thinking, one of the
main problems is that your environment gets replaced by something alien and
wrong.  People disagree with me over this point, and for this reason the
`set-user' style exists.

The objective of `set-user' style is to behave similarly to the standard
@code{su} command.  Unless they've been preserved explicitly (@pxref{Tweaking
the environment}), `set-user' mode sets the following environment variables:

@table @code
@item USER
@itemx LOGNAME
The name of the target user.

@item HOME
The home directory of the target user.

@item SHELL
The target user's default shell
@end table

The result of this is that the shell will read the target user's
configuration files and present you with the environment set up there.

I can't think of this style as being anything other than a migration aid
while users are getting used to the freedom offered by the `preserve' style.


@node The login style,  , The set-user style, Login styles
@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:

@table @code
@item USER
@itemx LOGNAME
The name of the target user.

@item HOME
The home directory of the target user.

@item SHELL
The target user's default shell

@item MAIL
An educated guess at where the target user's mailbox is.
@end table

By default, it runs the target user's shell, informing it that this is a
login by setting the first character of @code{argv[0]} to @samp{-}.

Become makes no entries in the @file{utmp} and @file{wtmp} files.



@node Tweaking the environment, Removed variables, Login styles, Environment
@subsection Tweaking individual environment variables

Become's login styles provide a sort of course-grained control over the
environment.  Sometimes the control isn't fine enough.  Become lets you tweak
individual variables: you can set, delete, or preserve named variables from
modification.

There are three different things you can do with environment variables:

@itemize @bullet
@item
Set a variable called @var{var} to a value @var{value}, by saying

@example
@var{var}=@var{value}
@end example

@noindent
The variable is preserved from automatic deletion by the login-style rules.

@item
Delete a variable called @var{var} from the environment, by saying

@example
@var{var}-
@end example

@item
Preserve a variable @var{var} from being deleted or modified by Become's
login-style rules, but not change its value, by saying

@example
@var{var}!
@end example
@end itemize

Just to try and make this slightly more sensible, here's an example.  Suppose
I want my @code{XAUTHORITY} variable to be set when I become user `fred':

@example
become XAUTHORITY=$HOME/.Xauthority fred
@end example

@noindent
should do the job nicely.  Similarly, if I want to log in as `bob', but don't
want my @code{EDITOR} variable to change:

@example
become --login EDITOR! bob
@end example

@noindent
(Of course, in this example, I'm at the mercy of Bob's shell init files as to
whether his choice of editor overrides mine.)



@node Removed variables,  , Tweaking the environment, Environment
@subsection Variables removed from the environment

Some variables are removed from the environment which Become passes to a
program for security reasons:

@table @code
@item LD_*
@itemx SHLIB_PATH
@itemx LIBPATH
@itemx _RLD_*
These variables are used on various systems as a search path for shared
libraries.  Clearly, by manipulating these search paths, an attacker could
replace a standard shared library with one of his own.

@item IFS
The shell input field separator.  Modifying this variable radically alters
the way shells parse their inputs.  (In particular, consider the case where
@code{IFS} contains @samp{/}.)

@item ENV
@itemx BASH_ENV
Used by some shells: it contains the name of a file to read on every shell
invocation.

@item KRB_CONF
@ignore
I'm not really sure what's going on here, so I'll just have to bluff my way
through.  I think that the following is more-or-less accurate, having browsed
a small amount of Kerberos-related documentation.
@end ignore
Contains the name of a Kerberos configuration file.  By manipulating this
variable, an attacker could persuade a program to believe the wrong
authentication server.
@end table

Also note that the @code{PATH} variable is modified: any items which aren't
absolute pathnames are removed from the path.  This check may become stricter
in future, although getting the balance between security and convenience is
particularly hard here.



@node Group permissions, X authority, Environment, Becoming someone else
@section How Become handles groups

As well as handling changes of user id, Become also changes group ids.
The exact changes Become makes are under user control.

@menu
* Primary group selection::     Setting the new primary group
* Subsidiary groups::           Setting subsidiary group memberships
@end menu


@node Primary group selection, Subsidiary groups, Group permissions, Group permissions
@subsection Choosing a new primary group

By default, the primary group is chosen according to the login style
(@pxref{Login styles}): the `preserve' style retains the current primary
group, while `set-user' and `login' styles choose the target's primary group.

You can override Become's default choice using the @code{--group} (@code{-g}
for short) option:

@example
become --group=@var{group} @dots{}
@end example

The chosen @var{group} may be either a group name or a numeric gid.  The
group must be one of the following:

@itemize @bullet
@item
Your current primary group.
@item
One of your current subsidiary groups.
@item
The target user's primary group.
@item
One of the target user's subsidiary groups.
@end itemize

Become will raise an error if this isn't the case.


@node Subsidiary groups,  , Primary group selection, Group permissions
@subsection Handling subsidiary group memberships

Subsidiary group memberships are a powerful tool for managing permissions
under Unix.  Traditionally, they tend to be tied to particular users.  Become
tries to be sightly more intelligent about group memberships.

Become has a concept of @dfn{group style}, analogous to login style
(@pxref{Login styles}).  The styles are selected by giving command line
arguments:

@table @code
@item -k
@itemx --keep-groups
Retain the existing group memberships; don't add any new groups.

@item -m
@itemx --merge-groups
Merge group memberships of the target user with the exiting memberships.

@item -r
@itemx --replace-groups
Replace the existing group memberships with the target user's memberships.
@end table

Again, the defaults are dependent on the chosen login style.  Both `preserve'
and `set-user' merge group memberships; the `login' style replaces the set of
groups.

Note that you can do perverse things like replace all the subsidiary groups
but retain your primary group (using the @code{--group} option;
@pxref{Primary group selection}) if you like: Become won't try to stop you.



@node X authority, Running commands, Group permissions, Becoming someone else
@section Considerations for X authority

Other users can't read your @file{.Xauthority} file, if you have one.  This
is as it should be: anyone who can read it can connect to your X server and
read or generate events.  However, once you've become another user, you can't
open any X windows; this can be annoying if your favourite editor is X-based.

There are two basic approaches.  Either you can send the shared account a
copy of your display's magic cookie, or you can retain permission to read the
cookie file.

@menu
* The user-group method::       A secure method for 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.

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
readable.  Finally, ensure that your private group is retained when you
become someone else (@pxref{Group permissions}), and that the
@code{XAUTHORITY} variable is set correctly.

The following Bourne shell code in a @file{.xinitrc} should do most of the
work:

@example
XAUTHORITY="$HOME/.Xauthority"
export XAUTHORITY
chgrp mygroup $XAUTHORITY
chmod 640 $XAUTHORITY
@end example

@noindent
In a C shell, this becomes

@example
setenv XAUTHORITY $@{HOME@}/.Xauthority
chgrp mygroup $XAUTHORITY
chmod 640 $XAUTHORITY
@end example

The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
login styles, so this isn't a problem.  You can now become other users, and
your X permissions will follow you around correctly.

It's probably worth noting that the @code{xauth} program annoyingly resets
the permissions on the cookie file every time it writes to it.  This will be
particularly irritating if you use @code{ssh}'s X forwarding capabilities,
because every @code{ssh} connection will reset the permissions.  You can deal
with this problem by putting a line

@example
chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
@end example

@noindent
in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or

@example
if ($?XAUTHORITY) then
  chmod 640 $XAUTHORITY >&/dev/null
else
  chmod 640 $@{HOME@}/.Xauthority >&/dev/null
endif
@end example

@noindent
in @file{.cshrc} for C shell users.



@node Using xauth,  , The user-group method, X authority
@subsection The `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
shared account not to take undue advantage of this situation.

The following (Bourne) shell snippet illustrates how you might send an
authorisation cookie to the shared account, to allow it to connect to your
display:

@example
if test -n "$BECOME_HOME"; then
  XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
  case "$DISPLAY" in
    :0.0) display=`hostname`:0.0 ;;
    *) display="$DISPLAY" ;;
  esac
  xauth extract - $display | \
    become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
  done_xauth_cookie=yes; export done_xauth_cookie
fi
@end example

The equivalent C shell code is

@example
if ($?BECOME_HOME) then
  setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
else if ($?DISPLAY && ! $?done_xauth_cookie) then
  if ($DISPLAY == :0.0) then
    set display="`hostname`:0.0"
  else
    set display="$DISPLAY"
  endif
  xauth extract - $display | \
    become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
endif
@end example

It works as follows:

@itemize @bullet
@item
If the variable @code{BECOME_HOME} is set, then we're probably really someone
else, so point to the shared account's authority file.

@item
Otherwise, check to see whether we have a display, and the authorisation has
not already been sent.  If this is so, resolve a local display name into a
remote one (just in case) and then send it to the shared account.
@end itemize



@node Running commands,  , X authority, Becoming someone else
@section Executing specific commands

As well as starting shells, Become can run single commands.  This can be
useful in two ways:

@itemize @bullet
@item
It enables Become to be used in scripts.

@item
It allows access to shared accounts to be controlled on the basis of the
command to be run.
@end itemize

To run a command as another user, say:

@example
become @var{user} @var{command} [@var{argument}@dots{}]
@end example

If the request is granted, Become runs @var{command}, passing it any
arguments following the command name.  Become doesn't run a shell, so there's
no extra escaping which needs to be done.

If you really want to run a shell command as another user, you can use the
@code{-c} option:

@example
become @var{user} -c @var{shell-command}
@end example

This is exactly equivalent to

@example
become @var{user} /bin/sh -c @var{shell-command}
@end example

in every way.  In particular, you must have permission to run @file{/bin/sh}
as @var{user} for it to work: Become doesn't attempt to interpret the shell
command in any way.  Also note that Become always uses the Bourne shell,
regardless of your current shell preference, or @var{user}'s default shell.
(This is done to provide a stable programming interface which works
irrespective of changes to the shared account's configuration.)


@c --------------------------------------------------------------------------
@node Administering Become, Invoking Become, Becoming someone else, Top
@chapter Become administration


This chapter will explain how Become is administrated and maintained.

@menu
* Configuration files::         Overview of Become's configuration files
* Standalone or networked::     The two main types of Become installations
* The configuration file::      How to define who's allowed to do what
* Networked configuration::     Considerations for networked installations
@end menu



@node Configuration files, Standalone or networked, Administering Become, Administering Become
@section Configuration files

Become keeps its configuration and administrative files in a directory
usually named @file{/etc/become}, although this can be changed with the
@code{--with-etcdir} option to the configuration script when you build
Become.

Not all of the files are needed on all machines.

@table @file
@item become.conf
The main configuration file, containing a description of which users are
allowed to become which other users, where, and what they're allowed to run
when they get there.  Only needed on servers or standalone machines.

@item become.server
A list of servers to contact.  Only needed on client machines.

@item become.key
The encryption key to use when sending requests to servers.  Needed on
clients and servers, but not on standalone machines.

@item become.pid
The process id of the server.  Created automatically by Become's server when
in starts up.

@item become.random
Contains state information for Become's random number generator.  Created
automatically if it doesn't exist.
@end table


@node Standalone or networked, The configuration file, Configuration files, Administering Become
@section Installation types


Become can be installed in two different ways, depending on how you want to
administer it:

@itemize @bullet
@item
In a @dfn{standalone} installation, each Become request is dealt with
locally: the program reads the configuration file, and decides whether it
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
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
difficult when you have lots of machines.

@item
In a @dfn{network} installation, any Become requests are sent on to a
collection of servers.  The servers analyse the request and send a reply back
which either authorises or forbids access.

A networked installation clearly depends on the servers' reliability.  The
client reacts only to the first reply it receives, so as long as there is one
server running, everything should continue as normal.

A networked installation is useful when you have a large number of client
machines, particularly ones which may not be awake all the time.  The full
configuration file only needs to be installed on a small number of servers;
the clients require only a list of server machines to contact, and an
encryption key to use.
@end itemize



@node The configuration file, Networked configuration, Standalone or networked, Administering Become
@section The configuration file

The main configuration file, usually called @file{/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.

@menu
* 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.
* Complete grammar::            Complete grammar for Become config files
@end menu


@node Basic syntax, Classes, The configuration file, The configuration file
@subsection Basic configuration file syntax

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

Comments begin with a @samp{#} 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 (@samp{"}).  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.

In general, ...



@node Classes, Predefined classes, Basic syntax, The configuration file
@subsection Classes

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

@example
user @var{name} = @var{class-expr} ;
command @var{name} = @var{class-expr} ;
host @var{name} = @var{class-expr} ;
@end example

A @var{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) @samp{,}, @samp{-}, @samp{|} and @samp{&}, 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.



@node Predefined classes, Allow statements, Classes, The configuration file
@subsection Predefined classes

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

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

@example
user MUNDANES = all - SYSHACKS;
@end example

@noindent
The @code{none} class isn't particularly useful in itself.  It's there for
completeness.

Become also defines some other classes:

@itemize @bullet
@item
For each username @var{user}, Become adds a class called @samp{@var{user}}
which matches just that user.

@item
For each group name @var{group}, Become creates a class called
@samp{@var{group}} which matches any user who is a member of that group.

@item For each netgroup @var{netgroup}, Become creates two classes:
@samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
@samp{h_@var{netgroup}} which matches any host listed in the netgroup.
@end itemize

If a name is used for both a user @emph{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 @code{get*ent} calls
@emph{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 wonn'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:

@example
allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
@end example

(The @var{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.


@node Other statements, Example configuration file, Allow statements, The configuration file
@subsection Other statements

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

@example
port @var{port} ;
keyfile @var{key-file} ;
@end example

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


@node Example configuration file, Complete grammar, Other statements, The configuration file
@subsection An example configuration file

@example
#
# become.conf
#
# Example configuration file
#

allow wheel -> "root";

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

user HTTP = "jim", "bob";
allow HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
@end example


@node Complete grammar,  , Example configuration file, The configuration file
@subsection Complete grammar for configuration files

@format
@var{file} ::= @var{file} @var{statement}

@var{statement} ::= @var{class-def}
        | @var{allow-spec}
        | @var{port-spec}
        | @var{key-spec}

@var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
        | @samp{command} @var{name} = @var{class-expr} @samp{;}
        | @samp{host} @var{name} = @var{class-expr} @samp{;}

@var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
                @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}

@var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
        | @var{empty}

@var{opt-user-spec} ::= @var{class-expr}
        | @var{empty}

@var{opt-command-spec} ::= @samp{:} @var{class-expr}
        | @var{empty}

@var{port-spec} ::= @samp{port} @var{integer} @samp{;}
        | @samp{port} @var{string} @samp{;}

@var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}

@var{class-expr} ::= @var{class-diff-expr}
        | @var{class-expr} @samp{,} @var{class-diff-expr}

@var{class-diff-expr} ::= @var{class-isect-expr}
        | @var{class-diff-expr} @samp{-} @var{class-union-expr}

@var{class-union-expr} ::= @var{class-isect-expr}
        | @var{class-union-expr} @samp{|} @var{class-isect-expr}

@var{class-isect-expr} ::= @var{class-primary}
        | @var{class-isect-expr} @samp{&} @var{class-primary}

@var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
        | @var{string}
        | @var{integer}

@var{integer} ::= one or more digits (@samp{0}--@samp{9})

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

@var{string} ::= @samp{"} @var{string-chars} @samp{"}

@var{string-chars} ::= @var{string-chars} @var{string-char}
        | @var{empty}

@var{string-char} ::= a @samp{\} followed by any character
        | any character other than @samp{"}, @samp{\} or newline

@var{empty} ::=
@end format


@node Networked configuration,  , The configuration file, Administering Become
@section Networked configuration

If you're planning to use Become in a standalone way, you can skip this
section.

@menu
* Choosing servers::            Which servers Become tries to talk to
* Setting up keys::             How to generate keys for Become
* Random number files::         Become keeps random number state around
* Issuing a new key::           How to issue new keys without disruption
@end menu


@node Choosing servers, Setting up keys, Networked configuration, Networked configuration
@subsection Choosing servers

Become notices that it's meant to send requests to a server if it finds a
@file{become.server} file.  This file contains entries of the form

@example
@var{host} [: @var{port}]
@end example

If the @var{port} is omitted, Become chooses a port by looking at the
services database for a service which matches the name by which Become was
invoked: normally this will be @samp{become}.

Become sends a request to all of the servers and believes the first valid
reply it receives.  Since servers ignore requests they believe to be invalid,
this enables you to change Become's key without disrupting service
(@pxref{Issuing a new key}).

If you're using NIS, you should try to ensure that Become servers runs only
on NIS servers; the NIS master is probably a good choice.

Become isn't particularly processor-intensive, and doesn't seem to require
very much memory.


@node Setting up keys, Random number files, Choosing servers, Networked configuration
@subsection Setting up keys

Communication between Become clients and the server is encrypted to ensure
that it's not feasible to gain unauthorised privilege by subverting the
network.  Become uses simple symmetric cryptography -- it's not necessary to
use complicated public key techniques in this case.

Each client machine, and the server, must have a copy of the same key.  The
key is usually stored in @file{/etc/become/become.key}.  Become's keys are
128 bits long.

The key file can be generated using the @code{keygen} program, supplied.  The
command

@example
keygen --bits=128 --output=/etc/become/become.key
@end example

@noindent
generates a 128-bit key and writes it to @file{/etc/become/become.key} in a
format which Become can read.

The @code{keygen} program works by measuring the time between keystrokes.  It
also tries to obtain some randomness from the environment, and mixes all of
this noise together before it outputs the key file.

Having generated a key, it must be distributed to all of the other hosts
which will use this server.  The author recommends using the @code{scp}
program, distributed with the @code{SSH} (Secure Shell) package, for doing
this.

Being able to read a key file enables a user to assume root privileges.  The
author recommends that only the super-user be able to read key files.

@menu
* Invoking keygen::             How to use the @code{keygen} program
@end menu


@node Invoking keygen,  , Setting up keys, Setting up keys
@subsubsection Invoking @code{keygen}

@example
keygen [@var{option}@dots{}]
@end example

By default, @code{keygen} generates a 128-bit key, and writes it to standard
output in a hexadecimal format.  This behaviour can be modified by passing
options:

@table @code
@item -h
@itemx --help
Write a summary of @code{keygen}'s usage instructions to standard output and
exits.

@item -b @var{bits}
@itemx --bits=@var{bits}
Generate a @var{bits}-bit key, instead of the default 128 bits.

@item -o @var{file}
@itemx --output=@var{file}
Write the key to @var{file} instead of standard output.

@item -f @var{format}
@itemx --format=@var{format}
Set the format in which @code{keygen} outputs the generated key.  If the
@var{format} is @samp{hex} (or @samp{tx}), the key is output in Become's
hexadecimal format; @samp{binary} writes the key as a raw binary dump; and
@samp{base64} writes the key using the Base64 encoding.
@end table



@node Random number files, Issuing a new key, Setting up keys, Networked configuration
@subsection Random number files

Become uses random numbers to generate session keys when it's communicating
with a server.  When it's finished, it stores the state of its random number
generator in a file, usually @code{/etc/become/become.random}.  If this file
doesn't exist, Become creates it automatically, using noise collected from
the environment.  It's probably not worth your while creating randomness
files by hand.


@node Issuing a new key,  , Random number files, Networked configuration
@subsection Issuing a new key

When you're sending out a new key, you run a risk of disrupting service.  The
server reads a new key; the clients still have the old one.

The author's recommendation is to run two servers.  Update the key on one.
Then send the new key to all of the clients.  Finally, update the key on the
other server.  Because of the way Become works, a client will always get a
response from one of the servers, depending on whether the new key has
reached it yet.

A similar method is handy if Become's protocol ever changes.  (This is quite
likely at the moment.  The current protocol doesn't include any version
information, and the MAC isn't as good as it could be.)


@c --------------------------------------------------------------------------
@node Invoking Become,  , Administering Become, Top
@chapter Invoking Become


This chapter provides an exhaustive description of Become's command line
options, organised in a reference-manual sort of way.

@menu
* Becoming another user::       Options for becoming another user
* Starting Become daemons::     Options for starting Become daemons
* Debugging options::           Options to use when Become goes wrong
@end menu



@node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
@section Becoming another user

@subsection Synopsis

@example
become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
@end example

Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
order you like; the important thing is that all of them appear before the
command, if any.


@subsection Usage

The @var{option}s appropriate for this mode are as follows:

@table @code
@item -h
@itemx --help
Display a (fairly verbose) help message describing the various command line
options and exits successfully.

@item -u
@itemx --usage
Display a terse summary of the command line options and exits successfully.

@item -v
@itemx
Display's Become's version number and exits successfully.

@item -e
@item --preserve-environment
Selects the `preserve' login style (@pxref{The preserve style}).  All
environment variables are preserved.  The default command is the current
user's own shell.  The default primary group becomes the current primary
group; the default group style is set to `merge'.

@item -s
@itemx --su
@itemx --set-user
Selects the `set-user' login style (@pxref{The set-user style}).  Most
environment variables are preserved, but @code{USER}, @code{LOGNAME},
@code{HOME} and other user-specific variables are altered to reflect the
target user's configuration.  The default command is the target user's shell.
The default primary group becomes the target user's primary group; the
default group style is set to `merge'.

@item -l
@itemx --login
Selects the `login' login style (@pxref{The login style}).  The environment
is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
The default command is the target user's shell.  The default primary group
becomes the target user's primary group; the default group style is set to
`replace'.

@item -g @var{group}
@itemx --group=@var{group}
Selects @var{group} as the primary group; it may be either a group name or a
numeric group id.  Note that @var{group} must be the primary group or
a subsidiary group of either the current user or the target user.

@item -k
@itemx --keep-groups
Selects the `keep' group style (@pxref{Subsidiary groups}).  The current set
of subsidiary group memberships are passed on unchanged.

@item -m
@itemx --merge-groups
Selects the `merge' group style (@pxref{Subsidiary groups}).  The current set
of subsidiary group memberships are merged with the subsidiary groups of the
target user.

@item -r
@itemx --replace-groups
Selects the `replace' group style (@pxref{Subsidiary groups}).  The target
user's subsidiary group memberships are passed on; the current subsidiary
groups are discarded.

@item -c @var{shell-cmd}
@itemx --command=@var{shell-cmd}
Sets the @var{command} and @var{argument}s to invoke
@code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
instead of just @code{exec}ing a program.  Note that permissions are checked
for executing the Bourne shell @code{/bin/sh}; the contents of the
@var{shell-cmd} are not inspected.
@end table

The @var{env-var} arguments fine-tune the environment passed to the command.
Each @var{env-var} setting must be one of the following:

@table @code
@item @var{var}=@var{value}
Assign the variable named @var{var} the value @var{value}.  Protect the
variable @var{var} from modifications by the login style.

@item @var{var}!
Protect the variable @var{var} from modifications by the login style, but
don't change its value.

@item @var{var}-
Remove the variable @var{var} from the environment; do not pass it on.
@end table

The @var{user} specifies the user as whom the @var{command} should be
executed (i.e., the @dfn{target user}).  It may be a user name or a numeric
user id.

The @var{command} specifies a command to execute.  If @var{command} does not
contain a path, it is looked for using the current @code{PATH} environment
variable.  The resulting pathname is canonified if necessary, to produce an
absolute pathname.  Note that symbolic links are @emph{not} resolved -- this
prevents an attack whereby a user could invoke a program, passing it an
unusual @code{argv[0]} which might cause unusual behaviour.

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
passed as @code{argv[1]} upwards.

If no @var{command} is given, a shell is invoked; the particulars of the
shell are determined by the login style (see above).

The @var{command} is executed as follows:

@itemize @bullet
@item
The subsidiary groups are chosen as determined by the group style.
@item
The real and effective gids are set.
@item
The real and effective uids are set.
@item
The @var{command} is called using the standard @code{execve} system call.
@end itemize



@node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
@section Starting Become daemons

@subsection Synopsis

@example
become --daemon [@var{option}@dots{}]
@end example


@subsection Usage

The following options are appropriate to this mode:

@table @code
@item -h
@itemx --help
Display a (fairly verbose) help message describing the various command line
options and exits successfully.

@item -u
@itemx --usage
Display a terse summary of the command line options and exits successfully.

@item -v
@itemx
Display's Become's version number and exits successfully.

@item -d
@itemx --daemon
Start a Become server, instead of processing a request.  Become will read its
command line options, read in the configuration file (and verify that it's
correct) and then fork into the background to wait for incoming requests.
Become relinquishes all setuid privileges (by setting all uids to the real
uid) when it enters daemon mode.  It is therefore only really useful to run a
daemon as the superuser.

@item -p @var{port}
@itemx --port=@var{port}
Listen for requests on @var{port}.  This option is overridden by the
@code{port} option in the configuration file.

@item -f @var{file}
@itemx --config-file=@var{file}
Read configuration from @var{file}, instead of the default (usually
@file{/etc/become/become.conf}).
@end table

The syntax of the configuration file is described in @ref{The configuration
file}.


@node Debugging options,  , Starting Become daemons, Invoking Become
@section Debugging options

Some options are only useful when trying to find out why Become is
misbehaving.  Of course, this never happens, so here are the options which
you won't need to use:

@table @code
@item -T[@var{file}]
@itemx --trace[=@var{file}]
Write trace information to @var{file} (or to standard output, if no
@var{file} is specified).  You must be able to create the file and open it
for writing.

@item -L[@var{feature}...]
@itemx --trace-level[=@var{feature}]
Selects which features Become ought to trace.  Each feature is allocated a
letter; simply string together the letters for the features you want to
debug.  The letters @samp{D} and @samp{A} stand respectively for `default'
and `all' features; you can subtract from them by saying, for example,
@samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
The exact list of features supported at any one time can be listed by giving
the @code{--trace-level} option without an argument.

@item -I @var{user}
@itemx --impersonate=@var{user}
Pretend to be @var{user} instead of yourself when the request is checked.
This option can only be used if it wasn't disabled at compile-time and if
Become is not running setuid.  Even so, Become will only inform you of the
outcome; it will not execute any commands.
@end table



@c --------------------------------------------------------------------------

@c --- No index yet ---
@c
@c @node Concept index,  , Invoking Become, Top
@c @unnumbered Concept index
@c @printindex cp
@c 
@c @contents

@bye

@c ----- That's all, folks --------------------------------------------------