1 \input texinfo @c -*-texinfo-*-
3 @c $Id: become.texi,v 1.1 1997/09/18 11:16:34 mdw Exp $
5 @c Documentation for `become'
10 @c ----- Revision history ---------------------------------------------------
12 @c $Log: become.texi,v $
13 @c Revision 1.1 1997/09/18 11:16:34 mdw
14 @c Brand new Texinfo manual, with wider scope than the original LaTeX one.
17 @c ----- Standard boilerplate -----------------------------------------------
22 @setchapternewpage odd
32 @c ----- Useful macros ------------------------------------------------------
36 @c ----- Copyright matters --------------------------------------------------
38 @c --- The `Info' version ---
42 This file documents Become version @value{version}.
44 Copyright (c) 1997 European Bioinformatics Institute.
46 Permission is granted to make and distribute verbatim copies of this
47 manual provided the copyright notice and this permission notice are
48 preserved on all copies.
51 Permission is granted to process this file through TeX and print the
52 results, provided the printed document carries a copying permission
53 notice identical to this one except for the removal of this paragraph
54 (this paragraph not being relevant to the printed manual).
57 Permission is granted to copy and distribute modified versions of this
58 manual under the conditions for verbatim copying, provided also that the
59 sections entitled `Copying' and `GNU General Public License' are
60 included exactly as in the original, and provided that the entire
61 resulting derived work is distributed under the terms of a permission
62 notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions,
66 except that this permission notice may be stated in a translation
67 approved by the European Bioinformatics Institute.
71 @c --- Printed title page ---
75 @title The Become program
76 @subtitle Become version @value{version}
77 @author Mark Wooding (@email{mdw@@ebi.ac.uk})
80 @vskip 0pt plus 1filll
82 Copyright @copyright{} 1997 European Bioinformatics Institute.
84 Permission is granted to make and distribute verbatim copies of this
85 manual provided the copyright notice and this permission notice are
86 preserved on all copies.
88 Permission is granted to copy and distribute modified versions of this
89 manual under the conditions for verbatim copying, provided also that the
90 sections entitled `Copying' and `GNU General Public License' are
91 included exactly as in the original, and provided that the entire
92 resulting derived work is distributed under the terms of a permission
93 notice identical to this one.
95 Permission is granted to copy and distribute translations of this manual
96 into another language, under the above conditions for modified versions,
97 except that this permission notice may be stated in a translation
98 approved by the European Bioinformatics Institute.
103 @c --------------------------------------------------------------------------
105 @node Top, Copying, (dir), (dir)
109 Become is a system for managing shared accounts. It allows users to
110 `become' other users in order to do useful work. It can be managed on a
111 central server (or a small number of central servers), or it can run
114 This file documents Become version @value{version}.
119 * Copying:: Your rights to distribute and modify
120 * Introduction:: A brief introduction to Become
121 * Becoming someone else:: How to become somebody else
122 * Administering Become:: How to maintain Become
123 * Invoking Become:: Reference to Become's command line options
125 --- The Detailed Node Listing ---
127 Becoming someone else
129 * Terminology:: Some important terms defined
130 * Environment:: Login styles and environment variables
131 * Group permissions:: How Become handles group permissions
132 * X authority:: Problems with X authority files
133 * Running commands:: Running commands other than a shell
135 How Become sets up the environment
137 * New environment variables:: Become adds some useful environment variables
138 * Login styles:: Choose how Become sets the environment
139 * Tweaking the environment:: Altering individual environment variables
140 * Removed variables:: Some environment variables aren't passed on
141 * Shared environments:: Tips for handling shared accounts
145 * The preserve style:: Preserve the current environment
146 * The set-user style:: Set user-specific variables (like @code{su})
147 * The login style:: Clear the environment (like @code{login})
149 How Become handles groups
151 * Primary group selection:: Setting the new primary group
152 * Subsidiary groups:: Setting subsidiary group memberships
154 Considerations for X authority
156 * The user-group method:: A secure method for handling X authority
157 * Using xauth:: A less secure method, which might be easier
159 Become administration
161 * Configuration files:: Overview of Become's configuration files
162 * Standalone or networked:: The two main types of Become installations
163 * The configuration file:: How to define who's allowed to do what
164 * Networked configuration::
166 The configuration file
168 * Basic syntax:: Quick overview of Become's syntax
169 * Classes:: Defining classes of things
170 * Predefined classes:: Become predefines some (maybe) useful classes
171 * Allow statements:: Allow users to become other users
172 * Other statements:: Some other useful statements
173 * Example configuration file:: An example, showing a few features.
174 * Complete grammar:: Complete grammar for Become config files
176 Networked configuration
178 * Choosing servers:: Which servers Become tries to talk to
179 * Setting up keys:: How to generate keys for Become
180 * Random number files:: Become keeps random number state around
181 * Issuing a new key:: How to issue new keys without disruption
185 * Invoking keygen:: How to use the @code{keygen} program
189 * Becoming another user:: Options for becoming another user
190 * Starting Become daemons:: Options for starting Become daemons
191 * Debugging options:: Options to use when Become goes wrong
194 @c --------------------------------------------------------------------------
195 @node Copying, Introduction, Top, Top
196 @unnumbered The GNU General Public License
202 @c --------------------------------------------------------------------------
203 @node Introduction, Becoming someone else, Copying, Top
204 @unnumbered Introduction
207 It's often useful to be able to share accounts between a number of
208 users. For example, a group maintaining an externally visible service
209 need to be able to start and kill the server process. Giving such a
210 shared account a password is a fairly bad plan: such passwords tend not
211 to get changed very often, and they have a habit of spreading beyond the
212 group of legitimate users.
214 The Become program presented here offers a solution to the problems of
215 shared accounts. It allows the system adminstrator to define which
216 users are allowed access to which accounts, on which hosts, and to
217 execute which commands. Such shared accounts can then, in general, have
218 their passwords removed.
220 This coincidentally has another advantage: when `becoming' to a shared
221 account, a user can retain her@footnote{Or his. I'll choose one or the
222 other fairly randomly throughout this manual.} own environment, which
223 she's carefully crafted and honed over the years, rather then being
224 presented with some lowest-common-denominator setup which probably
225 doesn't even use the right shell.
227 The configuration file for Become can either be distributed to all the
228 various hosts in a network or a few carefully set up and secure servers
229 (@pxref{Standalone or networked}).
232 @c --------------------------------------------------------------------------
233 @node Becoming someone else, Administering Become, Introduction, Top
234 @chapter Becoming someone else
237 The simplest way to become someone else is to say
244 Become will check to see whether you're allowed to become @var{user}. If you
245 are, it starts a shell process with the user-id set to @var{user}. Any
246 commands you type are executed with the privileges of @var{user}.
248 The full invocation is slightly more complicated:
251 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
254 Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
255 order -- the important point is that all of them appear before the
256 @var{command}, if there is one.
259 * Terminology:: Some important terms defined
260 * Environment:: Login styles and environment variables
261 * Group permissions:: How Become handles group permissions
262 * X authority:: Problems with X authority files
263 * Running commands:: Running commands other than a shell
268 @node Terminology, Environment, Becoming someone else, Becoming someone else
271 The following terms get used quite a bit in the following text:
275 An invocation of Become, asking permission to become another user.
278 The (real) user id of the process which invoked Become; usually, this will be
282 The user whom you want to become, named in a request.
287 @node Environment, Group permissions, Terminology, Becoming someone else
288 @section How Become sets up the environment
290 There are thorny problems with handling the user's environment. It seems
291 that (the author's initial assessment notwithstanding) there is no single
292 best way of handling environment variables. As a result, Become can do just
293 about everything you might want it to. This gets slightly complicated.
294 Don't worry: it's not as hard as all that.
297 * New environment variables:: Become adds some useful environment variables
298 * Login styles:: Choose how Become sets the environment
299 * Tweaking the environment:: Altering individual environment variables
300 * Removed variables:: Some environment variables aren't passed on
301 * Shared environments:: Tips for handling shared accounts
305 @node New environment variables, Login styles, Environment, Environment
306 @subsection Environment variables created by Become
308 To help you (and, more importantly, your startup scripts) keep track of who
309 you are, and who you were originally, Become adds some variables to the
310 environment of any processes it starts.
314 The name of the target user (i.e., the user you are now). It might be useful
315 to test this value in shell startup scripts, for example.
318 The home directory of the target user. It can be handy to read startup and
319 other configuration files from here.
321 @item BECOME_OLD_USER
322 The name of the user who invoked Become.
324 @item BECOME_OLD_HOME
325 The home directory of the `old' user.
327 @item BECOME_ORIGINAL_USER
328 This is intended to be the name you logged in with. If it's unset, Become
329 sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
332 @item BECOME_ORIGINAL_HOME
333 This is intended to be the home directory you logged in with. If it's unset,
334 Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
338 Don't even think about relying on these variables as a form of
339 authentication. It won't work. They're provided only to help organise
344 @node Login styles, Tweaking the environment, New environment variables, Environment
345 @subsection Login styles
347 Originally, Become always tried to preserve your environment. There's a
348 rational explanation for this approach, which is given in the description of
349 the `preserve' style below. Unfortunately, not everyone liked this
350 approach. As a result, there's now a collection of different login styles.
352 Login styles are selected by giving command line arguments:
357 The original style: try to preserve the existing user's environment as much
362 Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
363 the target user rather than the old user. All other variables are preserved.
367 Attempts to make the `become' process as much like a real login as possible.
368 All variables not explicitly preserved are deleted, and a new environment is
369 built, reflecting the target user.
372 The various styles, and the reasons behind them, are described below.
375 * The preserve style:: Preserve the current environment
376 * The set-user style:: Set user-specific variables (like @code{su})
377 * The login style:: Clear the environment (like @code{login})
381 @node The preserve style, The set-user style, Login styles, Login styles
382 @subsubsection The `preserve' login style
384 You've spent many hours (days? weeks, even?) customising and honing your
385 startup files, learning how to use your shell, and tweaking your favourite
386 text editor until it's just the way you like it. So there can be few things
387 more annoying than logging into a shared account to find out that the shell's
388 wrong, your editor startup files are ignored, and nothing works quite the way
389 you'd like it to. Typically you can't change this without annoying the other
390 users: the result is a horrible compromise which dissatisfies everyone
393 The `preserve' style lets you take your standard environment with you when
394 you become someone else. It tries hard not to modify any environment
397 Become starts your standard shell. If you have an environment variable
398 @code{SHELL} defined, than this is executed. Otherwise, the shell specified
399 in your entry in the password file is used. (You must have permission to
400 execute whatever shell is chosen as the target user, or you'll just be given
403 Most programs look at environment variables in preference to looking up
404 entries in the password database; e.g., they tend to use @code{USER} or
405 @code{LOGNAME} for the user name, and @code{HOME} for your home directory.
406 As a result, most programs will continue to find their configuration files in
407 your home directory. Also, systems like RCS will use your real name, rather
408 than the name of the user that you have become.
410 To make best use of this login style, you may need to adjust your login
411 scripts to notice when @code{BECOME_USER} is someone else, and read in
412 appropriate definitions. For example, a `bash' user might say something like
413 this in her @file{.bashrc}:
416 if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
420 Similarly, a C shell user (either `tcsh' or `csh') might say something like
423 if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
426 (Note that plain Bourne shell users have a slight problem, because the Bourne
427 shell only reads configuration things on a login, not when a normal
428 interactive shell is started.)
431 @node The set-user style, The login style, The preserve style, Login styles
432 @subsubsection The `set-user' login style
434 The author sees the main use of Become as allowing a user to acquire the
435 privileges associated with a shared account without all the problems which
436 shared accounts usually cause. To the author's way of thinking, one of the
437 main problems is that your environment gets replaced by something alien and
438 wrong. People disagree with me over this point, and for this reason the
439 `set-user' style exists.
441 The objective of `set-user' style is to behave similarly to the standard
442 @code{su} command. Unless they've been preserved explicitly (@pxref{Tweaking
443 the environment}), `set-user' mode sets the following environment variables:
448 The name of the target user.
451 The home directory of the target user.
454 The target user's default shell
457 The result of this is that the shell will read the target user's
458 configuration files and present you with the environment set up there.
460 I can't think of this style as being anything other than a migration aid
461 while users are getting used to the freedom offered by the `preserve' style.
464 @node The login style, , The set-user style, Login styles
465 @subsubsection The `login' login style
467 The `login' style causes Become to attempt to emulate a full login. Become
468 will empty the environment of any variables which aren't explicitly preserved
469 (@pxref{Tweaking the environment}). It will then set the following
475 The name of the target user.
478 The home directory of the target user.
481 The target user's default shell
484 An educated guess at where the target user's mailbox is.
487 By default, it runs the target user's shell, informing it that this is a
488 login by setting the first character of @code{argv[0]} to @samp{-}.
490 Become makes no entries in the @file{utmp} and @file{wtmp} files.
494 @node Tweaking the environment, Removed variables, Login styles, Environment
495 @subsection Tweaking individual environment variables
497 Become's login styles provide a sort of course-grained control over the
498 environment. Sometimes the control isn't fine enough. Become lets you tweak
499 individual variables: you can set, delete, or preserve named variables from
502 There are three different things you can do with environment variables:
506 Set a variable called @var{var} to a value @var{value}, by saying
509 @var{var}=@var{value}
513 The variable is preserved from automatic deletion by the login-style rules.
516 Delete a variable called @var{var} from the environment, by saying
523 Preserve a variable @var{var} from being deleted or modified by Become's
524 login-style rules, but not change its value, by saying
531 Just to try and make this slightly more sensible, here's an example. Suppose
532 I want my @code{XAUTHORITY} variable to be set when I become user `fred':
535 become XAUTHORITY=$HOME/.Xauthority fred
539 should do the job nicely. Similarly, if I want to log in as `bob', but don't
540 want my @code{EDITOR} variable to change:
543 become --login EDITOR! bob
547 (Of course, in this example, I'm at the mercy of Bob's shell init files as to
548 whether his choice of editor overrides mine.)
552 @node Removed variables, Shared environments, Tweaking the environment, Environment
553 @subsection Variables removed from the environment
555 Some variables are removed from the environment which Become passes to a
556 program for security reasons:
563 These variables are used on various systems as a search path for shared
564 libraries. Clearly, by manipulating these search paths, an attacker could
565 replace a standard shared library with one of his own.
568 The shell input field separator. Modifying this variable radically alters
569 the way shells parse their inputs. (In particular, consider the case where
570 @code{IFS} contains @samp{/}.)
574 Used by some shells: it contains the name of a file to read on every shell
579 I'm not really sure what's going on here, so I'll just have to bluff my way
580 through. I think that the following is more-or-less accurate, having browsed
581 a small amount of Kerberos-related documentation.
583 Contains the name of a Kerberos configuration file. By manipulating this
584 variable, an attacker could persuade a program to believe the wrong
585 authentication server.
588 Also note that the @code{PATH} variable is modified: any items which aren't
589 absolute pathnames are removed from the path. This check may become stricter
590 in future, although getting the balance between security and convenience is
591 particularly hard here.
595 @node Shared environments, , Removed variables, Environment
596 @subsection Handling common environments for shared accounts
598 FIXME: this needs writing.
602 @node Group permissions, X authority, Environment, Becoming someone else
603 @section How Become handles groups
605 As well as handling changes of user id, Become also changes group ids.
606 The exact changes Become makes are under user control.
609 * Primary group selection:: Setting the new primary group
610 * Subsidiary groups:: Setting subsidiary group memberships
614 @node Primary group selection, Subsidiary groups, Group permissions, Group permissions
615 @subsection Choosing a new primary group
617 By default, the primary group is chosen according to the login style
618 (@pxref{Login styles}): the `preserve' style retains the current primary
619 group, while `set-user' and `login' styles choose the target's primary group.
621 You can override Become's default choice using the @code{--group} (@code{-g}
625 become --group=@var{group} @dots{}
628 The chosen @var{group} may be either a group name or a numeric gid. The
629 group must be one of the following:
633 Your current primary group.
635 One of your current subsidiary groups.
637 The target user's primary group.
639 One of the target user's subsidiary groups.
642 Become will raise an error if this isn't the case.
645 @node Subsidiary groups, , Primary group selection, Group permissions
646 @subsection Handling subsidiary group memberships
648 Subsidiary group memberships are a powerful tool for managing permissions
649 under Unix. Traditionally, they tend to be tied to particular users. Become
650 tries to be sightly more intelligent about group memberships.
652 Become has a concept of @dfn{group style}, analogous to login style
653 (@pxref{Login styles}). The styles are selected by giving command line
659 Retain the existing group memberships; don't add any new groups.
662 @itemx --merge-groups
663 Merge group memberships of the target user with the exiting memberships.
666 @itemx --replace-groups
667 Replace the existing group memberships with the target user's memberships.
670 Again, the defaults are dependent on the chosen login style. Both `preserve'
671 and `set-user' merge group memberships; the `login' style replaces the set of
674 Note that you can do perverse things like replace all the subsidiary groups
675 but retain your primary group (using the @code{--group} option;
676 @pxref{Primary group selection}) if you like: Become won't try to stop you.
680 @node X authority, Running commands, Group permissions, Becoming someone else
681 @section Considerations for X authority
683 Other users can't read your @file{.Xauthority} file, if you have one. This
684 is as it should be: anyone who can read it can connect to your X server and
685 read or generate events. However, once you've become another user, you can't
686 open any X windows; this can be annoying if your favourite editor is X-based.
688 There are two basic approaches. Either you can send the shared account a
689 copy of your display's magic cookie, or you can retain permission to read the
693 * The user-group method:: A secure method for handling X authority
694 * Using xauth:: A less secure method, which might be easier
698 @node The user-group method, Using xauth, X authority, X authority
699 @subsection The user-group method for handling X authority
701 This method is completely secure only if your site uses the `user-group'
702 system. In this system, each user is allocated a group containing only that
703 user. Usually this is made the user's default primary group, although that's
706 When you start a new X session, ensure that your cookie file is owned by you
707 and your private group. Change the file's permissions so that it's group
708 readable. Finally, ensure that your private group is retained when you
709 become someone else (@pxref{Group permissions}), and that the
710 @code{XAUTHORITY} variable is set correctly.
712 The following Bourne shell code in a @file{.xinitrc} should do most of the
716 XAUTHORITY="$HOME/.Xauthority"
718 chgrp mygroup $XAUTHORITY
719 chmod 640 $XAUTHORITY
723 In a C shell, this becomes
726 setenv XAUTHORITY $@{HOME@}/.Xauthority
727 chgrp mygroup $XAUTHORITY
728 chmod 640 $XAUTHORITY
731 The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
732 login styles, so this isn't a problem. You can now become other users, and
733 your X permissions will follow you around correctly.
735 It's probably worth noting that the @code{xauth} program annoyingly resets
736 the permissions on the cookie file every time it writes to it. This will be
737 particularly irritating if you use @code{ssh}'s X forwarding capabilities,
738 because every @code{ssh} connection will reset the permissions. You can deal
739 with this problem by putting a line
742 chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
746 in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or
749 if ($?XAUTHORITY) then
750 chmod 640 $XAUTHORITY >&/dev/null
752 chmod 640 $@{HOME@}/.Xauthority >&/dev/null
757 in @file{.cshrc} for C shell users.
761 @node Using xauth, , The user-group method, X authority
762 @subsection The `xauth' method for handling X authority
764 This method sends your X cookie to the shared account. It's therefore
765 intrinsically dangerous: you must be able to trust the other users of the
766 shared account not to take undue advantage of this situation.
768 The following (Bourne) shell snippet illustrates how you might send an
769 authorisation cookie to the shared account, to allow it to connect to your
773 if test -n "$BECOME_HOME"; then
774 XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
775 elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
777 :0.0) display=`hostname`:0.0 ;;
778 *) display="$DISPLAY" ;;
780 xauth extract - $display | \
781 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
782 done_xauth_cookie=yes; export done_xauth_cookie
786 The equivalent C shell code is
789 if ($?BECOME_HOME) then
790 setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
791 else if ($?DISPLAY && ! $?done_xauth_cookie) then
792 if ($DISPLAY == :0.0) then
793 set display="`hostname`:0.0"
795 set display="$DISPLAY"
797 xauth extract - $display | \
798 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
806 If the variable @code{BECOME_HOME} is set, then we're probably really someone
807 else, so point to the shared account's authority file.
810 Otherwise, check to see whether we have a display, and the authorisation has
811 not already been sent. If this is so, resolve a local display name into a
812 remote one (just in case) and then send it to the shared account.
817 @node Running commands, , X authority, Becoming someone else
818 @section Executing specific commands
820 As well as starting shells, Become can run single commands. This can be
825 It enables Become to be used in scripts.
828 It allows access to shared accounts to be controlled on the basis of the
832 To run a command as another user, say:
835 become @var{user} @var{command} [@var{argument}@dots{}]
838 If the request is granted, Become runs @var{command}, passing it any
839 arguments following the command name. Become doesn't run a shell, so there's
840 no extra escaping which needs to be done.
842 If you really want to run a shell command as another user, you can use the
846 become @var{user} -c @var{shell-command}
849 This is exactly equivalent to
852 become @var{user} /bin/sh -c @var{shell-command}
855 in every way. In particular, you must have permission to run @file{/bin/sh}
856 as @var{user} for it to work: Become doesn't attempt to interpret the shell
857 command in any way. Also note that Become always uses the Bourne shell,
858 regardless of your current shell preference, or @var{user}'s default shell.
859 (This is done to provide a stable programming interface which works
860 irrespective of changes to the shared account's configuration.)
863 @c --------------------------------------------------------------------------
864 @node Administering Become, Invoking Become, Becoming someone else, Top
865 @chapter Become administration
868 This chapter will explain how Become is administrated and maintained.
871 * Configuration files:: Overview of Become's configuration files
872 * Standalone or networked:: The two main types of Become installations
873 * The configuration file:: How to define who's allowed to do what
874 * Networked configuration:: Considerations for networked installations
879 @node Configuration files, Standalone or networked, Administering Become, Administering Become
880 @section Configuration files
882 Become keeps its configuration and administrative files in a directory
883 usually named @file{/etc/become}, although this can be changed with the
884 @code{--with-etcdir} option to the configuration script when you build
887 Not all of the files are needed on all machines.
891 The main configuration file, containing a description of which users are
892 allowed to become which other users, where, and what they're allowed to run
893 when they get there. Only needed on servers or standalone machines.
896 A list of servers to contact. Only needed on client machines.
899 The encryption key to use when sending requests to servers. Needed on
900 clients and servers, but not on standalone machines.
903 The process id of the server. Created automatically by Become's server when
907 Contains state information for Become's random number generator. Created
908 automatically if it doesn't exist.
912 @node Standalone or networked, The configuration file, Configuration files, Administering Become
913 @section Installation types
916 Become can be installed in two different ways, depending on how you want to
921 In a @dfn{standalone} installation, each Become request is dealt with
922 locally: the program reads the configuration file, and decides whether it
923 should grant or deny permission.
925 Standalone installations don't depend on servers being available, or even on
926 the existance of a network. They're useful for small sites, or sites with a
927 small number of users. The disadvantages are that reading the configuration
928 file takes a while, so the program doesn't feel as responsive as it should,
929 and ensuring that all the hosts' configuration files are synchronised becomes
930 difficult when you have lots of machines.
933 In a @dfn{network} installation, any Become requests are sent on to a
934 collection of servers. The servers analyse the request and send a reply back
935 which either authorises or forbids access.
937 A networked installation clearly depends on the servers' reliability. The
938 client reacts only to the first reply it receives, so as long as there is one
939 server running, everything should continue as normal.
941 A networked installation is useful when you have a large number of client
942 machines, particularly ones which may not be awake all the time. The full
943 configuration file only needs to be installed on a small number of servers;
944 the clients require only a list of server machines to contact, and an
945 encryption key to use.
950 @node The configuration file, Networked configuration, Standalone or networked, Administering Become
951 @section The configuration file
953 The main configuration file, usually called @file{/etc/become/become.conf},
954 contains all the rules which Become uses to decide whether to grant or deny
955 requests. It may also contain additional information for the benefit of
956 Become daemons, if you're using a networked installation.
959 * Basic syntax:: Quick overview of Become's syntax
960 * Classes:: Defining classes of things
961 * Predefined classes:: Become predefines some (maybe) useful classes
962 * Allow statements:: Allow users to become other users
963 * Other statements:: Some other useful statements
964 * Example configuration file:: An example, showing a few features.
965 * Complete grammar:: Complete grammar for Become config files
969 @node Basic syntax, Classes, The configuration file, The configuration file
970 @subsection Basic configuration file syntax
972 The configuration file consists of a sequence of statements, each terminated
975 Comments begin with a @samp{#} character, and continue to the end of the
976 line. This is the only time newlines behave specially: newlines behave just
977 like any other whitespace characters within statements.
979 Strings are enclosed in double-quote characters (@samp{"}). Within a string,
980 a backslash causes the following character to be treated literally, whatever
981 it may be (including quotes, backslashes and newlines).
983 Names begin with an alphabetic character or an underscore, and consist of
984 letters, digits and underscores.
990 @node Classes, Predefined classes, Basic syntax, The configuration file
993 A @dfn{class} in Become is a set of users, hosts or commands. You can define
994 and name your own classes using statements of the form:
997 user @var{name} = @var{class-expr} ;
998 command @var{name} = @var{class-expr} ;
999 host @var{name} = @var{class-expr} ;
1002 A @var{class-expr} is an expression defining a class. You can build a
1003 complex class out of simple classes using the operators (in ascending
1004 precedence order) @samp{,}, @samp{-}, @samp{|} and @samp{&}, which represent
1005 the set options `union', `subtraction', `union' (again!), and `intersection'.
1006 Subexpressions can be parenthesised to override the default precedence.
1007 Once a class name has been defined, as shown above, it can be used in
1008 subsequent class expressions.
1010 A single user may be designated by either a user name (in quotes) or an
1011 integer uid. Commands and hosts may be designated by quoted strings which
1012 may contain wildcards. Host strings are matched against both numeric (dotted
1013 quad) IP addresses and the reverse-resolved hostname. Command strings are
1014 matched against the absolute pathname of the command the user wants to
1019 @node Predefined classes, Allow statements, Classes, The configuration file
1020 @subsection Predefined classes
1022 In an attempt to make life a bit easier, Become creates a collection of
1025 The standard classes @code{all} and @code{none} match anything and nothing
1026 respectively. The @code{all} class is useful in some contexts: it gives you
1027 a way of saying `everything except@dots{}', for example:
1030 user MUNDANES = all - SYSHACKS;
1034 The @code{none} class isn't particularly useful in itself. It's there for
1037 Become also defines some other classes:
1041 For each username @var{user}, Become adds a class called @samp{@var{user}}
1042 which matches just that user.
1045 For each group name @var{group}, Become creates a class called
1046 @samp{@var{group}} which matches any user who is a member of that group.
1048 @item For each netgroup @var{netgroup}, Become creates two classes:
1049 @samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
1050 @samp{h_@var{netgroup}} which matches any host listed in the netgroup.
1053 If a name is used for both a user @emph{and} a group, then corresponding
1054 class ends up containing the user together with all of the group members.
1055 For this reason, it's probably better to use the predefined classes for
1056 groups rather than individual users -- use quoted user names for individual
1059 Note that users and groups are read using the standard @code{get*ent} calls
1060 @emph{and} directly from the NIS server (if there is one). The idea here is
1061 that a Become server can be run on a machine which allows restricted logins.
1062 It still needs to know about all the users known to the outside world.
1064 Netgroups are read only from the NIS servers. In particular, although GNU
1065 systems allow netgroup databases to be stored in local files, Become wonn't
1066 read them because there's no defined interface for enumerating netgroups.
1069 @node Allow statements, Other statements, Predefined classes, The configuration file
1070 @subsection Allow statements
1072 Defining classes is just a means to an end. The end is to specify which
1073 users are allowed to do what, where, and as whom. This is done with an
1074 @code{allow} statement:
1077 allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
1080 (The @var{host-class} is optional, but must be enclosed in square brackets if
1083 The four classes in an allow statement are called, respectively, the `host',
1084 the `to-user', the `from-user' and the `command'. Any of the four classes
1085 may be omitted, and an omitted class defaults to `all'.
1087 When a request is received, Become checks the fields in the request against
1088 the classes in each allow statement of the configuration file. If a
1089 statement matches, the request is granted; if there are no full matches,
1090 the request is denied.
1093 @node Other statements, Example configuration file, Allow statements, The configuration file
1094 @subsection Other statements
1096 Two other statement types are defined. They only have an effect on Become in
1101 keyfile @var{key-file} ;
1105 The @code{port} statement specifies the port to which the server should
1106 listen; the @var{port} may be be an integer or a quoted service name. The
1107 @code{keyfile} statement instructs Become to use the key from the file named
1108 @var{key-file}, which must be a quoted string.
1111 @node Example configuration file, Complete grammar, Other statements, The configuration file
1112 @subsection An example configuration file
1118 # Example configuration file
1121 allow wheel -> "root";
1123 user NEWS = "fred", "jim";
1124 allow NEWS -> "news";
1126 user HTTP = "jim", "bob";
1127 allow HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
1131 @node Complete grammar, , Example configuration file, The configuration file
1132 @subsection Complete grammar for configuration files
1135 @var{file} ::= @var{file} @var{statement}
1137 @var{statement} ::= @var{class-def}
1142 @var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
1143 | @samp{command} @var{name} = @var{class-expr} @samp{;}
1144 | @samp{host} @var{name} = @var{class-expr} @samp{;}
1146 @var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
1147 @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}
1149 @var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
1152 @var{opt-user-spec} ::= @var{class-expr}
1155 @var{opt-command-spec} ::= @samp{:} @var{class-expr}
1158 @var{port-spec} ::= @samp{port} @var{integer} @samp{;}
1159 | @samp{port} @var{string} @samp{;}
1161 @var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}
1163 @var{class-expr} ::= @var{class-diff-expr}
1164 | @var{class-expr} @samp{,} @var{class-diff-expr}
1166 @var{class-diff-expr} ::= @var{class-isect-expr}
1167 | @var{class-diff-expr} @samp{-} @var{class-union-expr}
1169 @var{class-union-expr} ::= @var{class-isect-expr}
1170 | @var{class-union-expr} @samp{|} @var{class-isect-expr}
1172 @var{class-isect-expr} ::= @var{class-primary}
1173 | @var{class-isect-expr} @samp{&} @var{class-primary}
1175 @var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
1179 @var{integer} ::= one or more digits (@samp{0}--@samp{9})
1181 @var{name} ::= an alphabetic character or underscore, followed by zero or
1182 more alphanumeric characters or underscores
1184 @var{string} ::= @samp{"} @var{string-chars} @samp{"}
1186 @var{string-chars} ::= @var{string-chars} @var{string-char}
1189 @var{string-char} ::= a @samp{\} followed by any character
1190 | any character other than @samp{"}, @samp{\} or newline
1196 @node Networked configuration, , The configuration file, Administering Become
1197 @section Networked configuration
1199 If you're planning to use Become in a standalone way, you can skip this
1203 * Choosing servers:: Which servers Become tries to talk to
1204 * Setting up keys:: How to generate keys for Become
1205 * Random number files:: Become keeps random number state around
1206 * Issuing a new key:: How to issue new keys without disruption
1210 @node Choosing servers, Setting up keys, Networked configuration, Networked configuration
1211 @subsection Choosing servers
1213 Become notices that it's meant to send requests to a server if it finds a
1214 @file{become.server} file. This file contains entries of the form
1217 @var{host} [: @var{port}]
1220 If the @var{port} is omitted, Become chooses a port by looking at the
1221 services database for a service which matches the name by which Become was
1222 invoked: normally this will be @samp{become}.
1224 Become sends a request to all of the servers and believes the first valid
1225 reply it receives. Since servers ignore requests they believe to be invalid,
1226 this enables you to change Become's key without disrupting service
1227 (@pxref{Issuing a new key}).
1229 If you're using NIS, you should try to ensure that Become servers runs only
1230 on NIS servers; the NIS master is probably a good choice.
1232 Become isn't particularly processor-intensive, and doesn't seem to require
1236 @node Setting up keys, Random number files, Choosing servers, Networked configuration
1237 @subsection Setting up keys
1239 Communication between Become clients and the server is encrypted to ensure
1240 that it's not feasible to gain unauthorised privilege by subverting the
1241 network. Become uses simple symmetric cryptography -- it's not necessary to
1242 use complicated public key techniques in this case.
1244 Each client machine, and the server, must have a copy of the same key. The
1245 key is usually stored in @file{/etc/become/become.key}. Become's keys are
1248 The key file can be generated using the @code{keygen} program, supplied. The
1252 keygen --bits=128 --output=/etc/become/become.key
1256 generates a 128-bit key and writes it to @file{/etc/become/become.key} in a
1257 format which Become can read.
1259 The @code{keygen} program works by measuring the time between keystrokes. It
1260 also tries to obtain some randomness from the environment, and mixes all of
1261 this noise together before it outputs the key file.
1263 Having generated a key, it must be distributed to all of the other hosts
1264 which will use this server. The author recommends using the @code{scp}
1265 program, distributed with the @code{SSH} (Secure Shell) package, for doing
1268 Being able to read a key file enables a user to assume root privileges. The
1269 author recommends that only the super-user be able to read key files.
1272 * Invoking keygen:: How to use the @code{keygen} program
1276 @node Invoking keygen, , Setting up keys, Setting up keys
1277 @subsubsection Invoking @code{keygen}
1280 keygen [@var{option}@dots{}]
1283 By default, @code{keygen} generates a 128-bit key, and writes it to standard
1284 output in a hexadecimal format. This behaviour can be modified by passing
1290 Write a summary of @code{keygen}'s usage instructions to standard output and
1294 @itemx --bits=@var{bits}
1295 Generate a @var{bits}-bit key, instead of the default 128 bits.
1298 @itemx --output=@var{file}
1299 Write the key to @var{file} instead of standard output.
1301 @item -f @var{format}
1302 @itemx --format=@var{format}
1303 Set the format in which @code{keygen} outputs the generated key. If the
1304 @var{format} is @samp{hex} (or @samp{tx}), the key is output in Become's
1305 hexadecimal format; @samp{binary} writes the key as a raw binary dump; and
1306 @samp{base64} writes the key using the Base64 encoding.
1311 @node Random number files, Issuing a new key, Setting up keys, Networked configuration
1312 @subsection Random number files
1314 Become uses random numbers to generate session keys when it's communicating
1315 with a server. When it's finished, it stores the state of its random number
1316 generator in a file, usually @code{/etc/become/become.random}. If this file
1317 doesn't exist, Become creates it automatically, using noise collected from
1318 the environment. It's probably not worth your while creating randomness
1322 @node Issuing a new key, , Random number files, Networked configuration
1323 @subsection Issuing a new key
1325 When you're sending out a new key, you run a risk of disrupting service. The
1326 server reads a new key; the clients still have the old one.
1328 The author's recommendation is to run two servers. Update the key on one.
1329 Then send the new key to all of the clients. Finally, update the key on the
1330 other server. Because of the way Become works, a client will always get a
1331 response from one of the servers, depending on whether the new key has
1334 A similar method is handy if Become's protocol ever changes. (This is quite
1335 likely at the moment. The current protocol doesn't include any version
1336 information, and the MAC isn't as good as it could be.)
1339 @c --------------------------------------------------------------------------
1340 @node Invoking Become, , Administering Become, Top
1341 @chapter Invoking Become
1344 This chapter provides an exhaustive description of Become's command line
1345 options, organised in a reference-manual sort of way.
1348 * Becoming another user:: Options for becoming another user
1349 * Starting Become daemons:: Options for starting Become daemons
1350 * Debugging options:: Options to use when Become goes wrong
1355 @node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
1356 @section Becoming another user
1358 @subsection Synopsis
1361 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
1364 Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
1365 order you like; the important thing is that all of them appear before the
1371 The @var{option}s appropriate for this mode are as follows:
1376 Display a (fairly verbose) help message describing the various command line
1377 options and exits successfully.
1381 Display a terse summary of the command line options and exits successfully.
1385 Display's Become's version number and exits successfully.
1388 @item --preserve-environment
1389 Selects the `preserve' login style (@pxref{The preserve style}). All
1390 environment variables are preserved. The default command is the current
1391 user's own shell. The default primary group becomes the current primary
1392 group; the default group style is set to `merge'.
1397 Selects the `set-user' login style (@pxref{The set-user style}). Most
1398 environment variables are preserved, but @code{USER}, @code{LOGNAME},
1399 @code{HOME} and other user-specific variables are altered to reflect the
1400 target user's configuration. The default command is the target user's shell.
1401 The default primary group becomes the target user's primary group; the
1402 default group style is set to `merge'.
1406 Selects the `login' login style (@pxref{The login style}). The environment
1407 is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
1408 The default command is the target user's shell. The default primary group
1409 becomes the target user's primary group; the default group style is set to
1412 @item -g @var{group}
1413 @itemx --group=@var{group}
1414 Selects @var{group} as the primary group; it may be either a group name or a
1415 numeric group id. Note that @var{group} must be the primary group or
1416 a subsidiary group of either the current user or the target user.
1419 @itemx --keep-groups
1420 Selects the `keep' group style (@pxref{Subsidiary groups}). The current set
1421 of subsidiary group memberships are passed on unchanged.
1424 @itemx --merge-groups
1425 Selects the `merge' group style (@pxref{Subsidiary groups}). The current set
1426 of subsidiary group memberships are merged with the subsidiary groups of the
1430 @itemx --replace-groups
1431 Selects the `replace' group style (@pxref{Subsidiary groups}). The target
1432 user's subsidiary group memberships are passed on; the current subsidiary
1433 groups are discarded.
1435 @item -c @var{shell-cmd}
1436 @itemx --command=@var{shell-cmd}
1437 Sets the @var{command} and @var{argument}s to invoke
1438 @code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
1439 instead of just @code{exec}ing a program. Note that permissions are checked
1440 for executing the Bourne shell @code{/bin/sh}; the contents of the
1441 @var{shell-cmd} are not inspected.
1444 The @var{env-var} arguments fine-tune the environment passed to the command.
1445 Each @var{env-var} setting must be one of the following:
1448 @item @var{var}=@var{value}
1449 Assign the variable named @var{var} the value @var{value}. Protect the
1450 variable @var{var} from modifications by the login style.
1453 Protect the variable @var{var} from modifications by the login style, but
1454 don't change its value.
1457 Remove the variable @var{var} from the environment; do not pass it on.
1460 The @var{user} specifies the user as whom the @var{command} should be
1461 executed (i.e., the @dfn{target user}). It may be a user name or a numeric
1464 The @var{command} specifies a command to execute. If @var{command} does not
1465 contain a path, it is looked for using the current @code{PATH} environment
1466 variable. The resulting pathname is canonified if necessary, to produce an
1467 absolute pathname. Note that symbolic links are @emph{not} resolved -- this
1468 prevents an attack whereby a user could invoke a program, passing it an
1469 unusual @code{argv[0]} which might cause unusual behaviour.
1471 The @var{command} name is used both as the command to execute and passed to
1472 the command as @code{argv[0]}. It is not possible to specify an alternative
1473 calue to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
1474 passed as @code{argv[1]} upwards.
1476 If no @var{command} is given, a shell is invoked; the particulars of the
1477 shell are determined by the login style (see above).
1479 The @var{command} is executed as follows:
1483 The subsidiary groups are chosen as determined by the group style.
1485 The real and effective gids are set.
1487 The real and effective uids are set.
1489 The @var{command} is called using the standard @code{execve} system call.
1494 @node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
1495 @section Starting Become daemons
1497 @subsection Synopsis
1500 become --daemon [@var{option}@dots{}]
1506 The following options are appropriate to this mode:
1511 Display a (fairly verbose) help message describing the various command line
1512 options and exits successfully.
1516 Display a terse summary of the command line options and exits successfully.
1520 Display's Become's version number and exits successfully.
1524 Start a Become server, instead of processing a request. Become will read its
1525 command line options, read in the configuration file (and verify that it's
1526 correct) and then fork into the background to wait for incoming requests.
1527 Become relinquishes all setuid privileges (by setting all uids to the real
1528 uid) when it enters daemon mode. It is therefore only really useful to run a
1529 daemon as the superuser.
1532 @itemx --port=@var{port}
1533 Listen for requests on @var{port}. This option is overridden by the
1534 @code{port} option in the configuration file.
1537 @itemx --config-file=@var{file}
1538 Read configuration from @var{file}, instead of the default (usually
1539 @file{/etc/become/become.conf}).
1542 The syntax of the configuration file is described in @ref{The configuration
1546 @node Debugging options, , Starting Become daemons, Invoking Become
1547 @section Debugging options
1549 Some options are only useful when trying to find out why Become is
1550 misbehaving. Of course, this never happens, so here are the options which
1551 you won't need to use:
1554 @item -T[@var{file}]
1555 @itemx --trace[=@var{file}]
1556 Write trace information to @var{file} (or to standard output, if no
1557 @var{file} is specified). You must be able to create the file and open it
1560 @item -L[@var{feature}...]
1561 @itemx --trace-level[=@var{feature}]
1562 Selects which features Become ought to trace. Each feature is allocated a
1563 letter; simply string together the letters for the features you want to
1564 debug. The letters @samp{D} and @samp{A} stand respectively for `default'
1565 and `all' features; you can subtract from them by saying, for example,
1566 @samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
1567 The exact list of features supported at any one time can be listed by giving
1568 the @code{--trace-level} option without an argument.
1571 @itemx --impersonate=@var{user}
1572 Pretend to be @var{user} instead of yourself when the request is checked.
1573 This option can only be used if it wasn't disabled at compile-time and if
1574 Become is not running setuid. Even so, Become will only inform you of the
1575 outcome; it will not execute any commands.
1580 @c --------------------------------------------------------------------------
1582 @c --- No index yet ---
1584 @c @node Concept index, , Invoking Become, Top
1585 @c @unnumbered Concept index
1592 @c ----- That's all, folks --------------------------------------------------