--- /dev/null
+\input texinfo @c -*-texinfo-*-
+@c
+@c $Id: become.texi,v 1.1 1997/09/18 11:16:34 mdw Exp $
+@c
+@c Documentation for `become'
+@c
+@c (c) 1997 EBI
+@c
+
+@c ----- Revision history ---------------------------------------------------
+@c
+@c $Log: become.texi,v $
+@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--pre
+
+@c ----- Copyright matters --------------------------------------------------
+
+@c --- The `Info' version ---
+
+@ifinfo
+
+This file documents Become version @value{version}.
+
+Copyright (c) 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.
+
+@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
+* Shared environments:: Tips for handling shared accounts
+
+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::
+
+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
+* Shared environments:: Tips for handling shared accounts
+@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 -p
+@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, Shared environments, 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 Shared environments, , Removed variables, Environment
+@subsection Handling common environments for shared accounts
+
+FIXME: this needs writing.
+
+
+
+@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 --------------------------------------------------
~mdw / become / commitdiff