1 \input texinfo @c -*-texinfo-*-
3 @c $Id: become.texi,v 1.9 2004/04/17 10:54:21 mdw Exp $
5 @c Documentation for `become'
10 @c ----- Standard boilerplate -----------------------------------------------
13 @setfilename become.info
15 @setchapternewpage odd
25 @dircategory Administration tools
27 * Become: (become). Shared account administration tool
30 @c ----- Useful macros ------------------------------------------------------
34 @c ----- Copyright matters --------------------------------------------------
36 @c --- The `Info' version ---
40 This file documents Become version @value{version}.
42 Copyright (c) 1998 European Bioinformatics Institute.
44 Permission is granted to make and distribute verbatim copies of this
45 manual provided the copyright notice and this permission notice are
46 preserved on all copies.
49 Permission is granted to process this file through TeX and print the
50 results, provided the printed document carries a copying permission
51 notice identical to this one except for the removal of this paragraph
52 (this paragraph not being relevant to the printed manual).
55 Permission is granted to copy and distribute modified versions of this
56 manual under the conditions for verbatim copying, provided also that the
57 sections entitled `Copying' and `GNU General Public License' are
58 included exactly as in the original, and provided that the entire
59 resulting derived work is distributed under the terms of a permission
60 notice identical to this one.
62 Permission is granted to copy and distribute translations of this manual
63 into another language, under the above conditions for modified versions,
64 except that this permission notice may be stated in a translation
65 approved by the European Bioinformatics Institute.
69 @c --- Printed title page ---
73 @title The Become program
74 @subtitle Become version @value{version}
75 @author Mark Wooding @email{mdw@@ebi.ac.uk}
78 @vskip 0pt plus 1filll
80 Copyright @copyright{} 1998 European Bioinformatics Institute.
82 Permission is granted to make and distribute verbatim copies of this
83 manual provided the copyright notice and this permission notice are
84 preserved on all copies.
86 Permission is granted to copy and distribute modified versions of this
87 manual under the conditions for verbatim copying, provided also that the
88 sections entitled `Copying' and `GNU General Public License' are
89 included exactly as in the original, and provided that the entire
90 resulting derived work is distributed under the terms of a permission
91 notice identical to this one.
93 Permission is granted to copy and distribute translations of this manual
94 into another language, under the above conditions for modified versions,
95 except that this permission notice may be stated in a translation
96 approved by the European Bioinformatics Institute.
101 @c --------------------------------------------------------------------------
103 @node Top, Copying, (dir), (dir)
107 Become is a system for managing shared accounts. It allows users to
108 `become' other users in order to do useful work. It can be managed on a
109 central server (or a small number of central servers), or it can run
112 This file documents Become version @value{version}.
117 * Copying:: Your rights to distribute and modify
118 * Introduction:: A brief introduction to Become
119 * Becoming someone else:: How to become somebody else
120 * Administering Become:: How to maintain Become
121 * Invoking Become:: Reference to Become's command line options
124 --- The Detailed Node Listing ---
126 Becoming someone else
128 * Terminology:: Some important terms defined
129 * Environment:: Login styles and environment variables
130 * Group permissions:: How Become handles group permissions
131 * X authority:: Problems with X authority files
132 * Running commands:: Running commands other than a shell
134 How Become sets up the environment
136 * New environment variables:: Become adds some useful environment variables
137 * Login styles:: Choose how Become sets the environment
138 * Tweaking the environment:: Altering individual environment variables
139 * Removed variables:: Some environment variables aren't passed on
143 * The preserve style:: Preserve the current environment
144 * The set-user style:: Set user-specific variables (like @code{su})
145 * The login style:: Clear the environment (like @code{login})
147 How Become handles groups
149 * Primary group selection:: Setting the new primary group
150 * Subsidiary groups:: Setting subsidiary group memberships
152 Considerations for X authority
154 * The user-group method:: A fairly secure way of handling X authority
155 * Using xauth:: A less secure method, which might be easier
157 Become administration
159 * Configuration files:: Overview of Become's configuration files
160 * Standalone or networked:: The two main types of Become installations
161 * The configuration file:: How to define who's allowed to do what
162 * Networked configuration:: Considerations for networked installations
164 The configuration file
166 * Requests and rules:: How the configuration file works
167 * Basic syntax:: Quick overview of Become's syntax
168 * Classes:: Defining classes of things
169 * Predefined classes:: Become predefines some (maybe) useful classes
170 * Allow statements:: Allow users to become other users
171 * Other statements:: Some other useful statements
172 * Example configuration file:: An example, showing a few features.
173 * Checking and querying:: Checking and querying configuration files
174 * Complete grammar:: Complete grammar for Become config files
176 Checking and querying the configuration file
178 * Verifying config files:: Checking a configuration file is correct
179 * Querying config files:: Asking questions about privileges
180 * Output formats:: Different ways of formatting output
181 * Restricting output:: Being selective about what gets output
182 * bcquery reference:: Complete command line reference
184 Networked configuration
186 * Choosing servers:: Which servers Become tries to talk to
187 * Setting up keys:: How to generate keys for Become
188 * Issuing a new key:: How to issue new keys without disruption
192 * Becoming another user:: Options for becoming another user
193 * Starting Become daemons:: Options for starting Become daemons
194 * Debugging options:: Options to use when Become goes wrong
199 @c --------------------------------------------------------------------------
200 @node Copying, Introduction, Top, Top
201 @unnumbered The GNU General Public License
206 @c --------------------------------------------------------------------------
207 @node Introduction, Becoming someone else, Copying, Top
208 @unnumbered Introduction
211 It's often useful to be able to share accounts between a number of
212 users. For example, a group maintaining an externally visible service
213 need to be able to start and kill the server process. Giving such a
214 shared account a password is a fairly bad plan: such passwords tend not
215 to get changed very often, and they have a habit of spreading beyond the
216 group of legitimate users.
218 The Become program presented here offers a solution to the problems of
219 shared accounts. It allows the system administrator to define which
220 users are allowed access to which accounts, on which hosts, and to
221 execute which commands. Such shared accounts can then, in general, have
222 their passwords removed.
224 This coincidentally has another advantage: when `becoming' to a shared
225 account, a user can retain her@footnote{Or his. I'll choose one or the
226 other fairly randomly throughout this manual.} own environment, which
227 she's carefully crafted and honed over the years, rather then being
228 presented with some lowest-common-denominator setup which probably
229 doesn't even use the right shell.
231 The configuration file for Become can either be distributed to all the
232 various hosts in a network or a few carefully set up and secure servers
233 (@pxref{Standalone or networked}).
236 @c --------------------------------------------------------------------------
237 @node Becoming someone else, Administering Become, Introduction, Top
238 @chapter Becoming someone else
241 The simplest way to become someone else is to say
248 Become will check to see whether you're allowed to become @var{user}. If you
249 are, it starts a shell process with the user-id set to @var{user}. Any
250 commands you type are executed with the privileges of @var{user}.
252 The full invocation is slightly more complicated:
255 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
258 Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
259 order -- the important point is that all of them appear before the
260 @var{command}, if there is one.
263 * Terminology:: Some important terms defined
264 * Environment:: Login styles and environment variables
265 * Group permissions:: How Become handles group permissions
266 * X authority:: Problems with X authority files
267 * Running commands:: Running commands other than a shell
272 @node Terminology, Environment, Becoming someone else, Becoming someone else
275 The following terms get used quite a bit in the following text:
279 An invocation of Become, asking permission to become another user.
282 The (real) user id of the process which invoked Become; usually, this will be
286 The user whom you want to become, named in a request.
291 @node Environment, Group permissions, Terminology, Becoming someone else
292 @section How Become sets up the environment
294 There are thorny problems with handling the user's environment. It seems
295 that (the author's initial assessment notwithstanding) there is no single
296 best way of handling environment variables. As a result, Become can do just
297 about everything you might want it to. This gets slightly complicated.
298 Don't worry: it's not as hard as all that.
301 * New environment variables:: Become adds some useful environment variables
302 * Login styles:: Choose how Become sets the environment
303 * Tweaking the environment:: Altering individual environment variables
304 * Removed variables:: Some environment variables aren't passed on
308 @node New environment variables, Login styles, Environment, Environment
309 @subsection Environment variables created by Become
311 To help you (and, more importantly, your startup scripts) keep track of who
312 you are, and who you were originally, Become adds some variables to the
313 environment of any processes it starts.
317 The name of the target user (i.e., the user you are now). It might be useful
318 to test this value in shell startup scripts, for example.
321 The home directory of the target user. It can be handy to read startup and
322 other configuration files from here.
324 @item BECOME_OLD_USER
325 The name of the user who invoked Become.
327 @item BECOME_OLD_HOME
328 The home directory of the `old' user.
330 @item BECOME_ORIGINAL_USER
331 This is intended to be the name you logged in with. If it's unset, Become
332 sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
335 @item BECOME_ORIGINAL_HOME
336 This is intended to be the home directory you logged in with. If it's unset,
337 Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
341 Don't even think about relying on these variables as a form of
342 authentication. It won't work. They're provided only to help organise
347 @node Login styles, Tweaking the environment, New environment variables, Environment
348 @subsection Login styles
350 Originally, Become always tried to preserve your environment. There's a
351 rational explanation for this approach, which is given in the description of
352 the `preserve' style below. Unfortunately, not everyone liked this
353 approach. As a result, there's now a collection of different login styles.
355 Login styles are selected by giving command line arguments:
360 The original style: try to preserve the existing user's environment as much
365 Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
366 the target user rather than the old user. All other variables are preserved.
370 Attempts to make the `become' process as much like a real login as possible.
371 All variables not explicitly preserved are deleted, and a new environment is
372 built, reflecting the target user.
375 The various styles, and the reasons behind them, are described below.
378 * The preserve style:: Preserve the current environment
379 * The set-user style:: Set user-specific variables (like @code{su})
380 * The login style:: Clear the environment (like @code{login})
384 @node The preserve style, The set-user style, Login styles, Login styles
385 @subsubsection The `preserve' login style
387 You've spent many hours (days? weeks, even?) customising and honing your
388 startup files, learning how to use your shell, and tweaking your favourite
389 text editor until it's just the way you like it. So there can be few things
390 more annoying than logging into a shared account to find out that the shell's
391 wrong, your editor startup files are ignored, and nothing works quite the way
392 you'd like it to. Typically you can't change this without annoying the other
393 users: the result is a horrible compromise which dissatisfies everyone
396 The `preserve' style lets you take your standard environment with you when
397 you become someone else. It tries hard not to modify any environment
400 Become starts your standard shell. If you have an environment variable
401 @code{SHELL} defined, than this is executed. Otherwise, the shell specified
402 in your entry in the password file is used. (You must have permission to
403 execute whatever shell is chosen as the target user, or you'll just be given
406 Most programs look at environment variables in preference to looking up
407 entries in the password database; e.g., they tend to use @code{USER} or
408 @code{LOGNAME} for the user name, and @code{HOME} for your home directory.
409 As a result, most programs will continue to find their configuration files in
410 your home directory. Also, systems like RCS will use your real name, rather
411 than the name of the user that you have become.
413 To make best use of this login style, you may need to adjust your login
414 scripts to notice when @code{BECOME_USER} is someone else, and read in
415 appropriate definitions. For example, a `bash' user might say something like
416 this in her @file{.bashrc}:
419 if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
423 Similarly, a C shell user (either `tcsh' or `csh') might say something like
426 if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
429 (Note that plain Bourne shell users have a slight problem, because the Bourne
430 shell only reads configuration things on a login, not when a normal
431 interactive shell is started.)
434 @node The set-user style, The login style, The preserve style, Login styles
435 @subsubsection The `set-user' login style
437 The author sees the main use of Become as allowing a user to acquire the
438 privileges associated with a shared account without all the problems which
439 shared accounts usually cause. To the author's way of thinking, one of the
440 main problems is that your environment gets replaced by something alien and
441 wrong. People disagree with me over this point, and for this reason the
442 `set-user' style exists.
444 The objective of `set-user' style is to behave similarly to the standard
445 @code{su} command. Unless they've been preserved explicitly (@pxref{Tweaking
446 the environment}), `set-user' mode sets the following environment variables:
451 The name of the target user.
454 The home directory of the target user.
457 The target user's default shell
460 The result of this is that the shell will read the target user's
461 configuration files and present you with the environment set up there.
463 I can't think of this style as being anything other than a migration aid
464 while users are getting used to the freedom offered by the `preserve' style.
467 @node The login style, , The set-user style, Login styles
468 @subsubsection The `login' login style
470 The `login' style causes Become to attempt to emulate a full login. Become
471 will empty the environment of almost variables which aren't explicitly
472 preserved (@pxref{Tweaking the environment}). However, the following
473 variables are retained:
485 It will set the following variables:
490 The name of the target user.
493 The home directory of the target user.
496 The target user's default shell
499 An educated guess at where the target user's mailbox is.
502 By default, it runs the target user's shell, informing it that this is a
503 login by setting the first character of @code{argv[0]} to @samp{-}.
505 Become makes no entries in the @file{utmp} and @file{wtmp} files.
509 @node Tweaking the environment, Removed variables, Login styles, Environment
510 @subsection Tweaking individual environment variables
512 Become's login styles provide a sort of course-grained control over the
513 environment. Sometimes the control isn't fine enough. Become lets you tweak
514 individual variables: you can set, delete, or preserve named variables from
517 There are three different things you can do with environment variables:
521 Set a variable called @var{var} to a value @var{value}, by saying
524 @var{var}=@var{value}
528 The variable is preserved from automatic deletion by the login-style rules.
531 Delete a variable called @var{var} from the environment, by saying
538 Preserve a variable @var{var} from being deleted or modified by Become's
539 login-style rules, but not change its value, by saying
546 Just to try and make this slightly more sensible, here's an example. Suppose
547 I want my @code{XAUTHORITY} variable to be set when I become user `fred':
550 become XAUTHORITY=$HOME/.Xauthority fred
554 should do the job nicely. Similarly, if I want to log in as `bob', but don't
555 want my @code{EDITOR} variable to change:
558 become --login EDITOR! bob
562 (Of course, in this example, I'm at the mercy of Bob's shell init files as to
563 whether his choice of editor overrides mine.)
567 @node Removed variables, , Tweaking the environment, Environment
568 @subsection Variables removed from the environment
570 Some variables are removed from the environment which Become passes to a
571 program for security reasons:
578 These variables are used on various systems as a search path for shared
579 libraries. Clearly, by manipulating these search paths, an attacker could
580 replace a standard shared library with one of his own.
583 The shell input field separator. Modifying this variable radically alters
584 the way shells parse their inputs. (In particular, consider the case where
585 @code{IFS} contains @samp{/}.)
589 Used by some shells: it contains the name of a file to read on every shell
594 I'm not really sure what's going on here, so I'll just have to bluff my way
595 through. I think that the following is more-or-less accurate, having browsed
596 a small amount of Kerberos-related documentation.
598 Contains the name of a Kerberos configuration file. By manipulating this
599 variable, an attacker could persuade a program to believe the wrong
600 authentication server.
603 Also note that the @code{PATH} variable is modified: any items which aren't
604 absolute pathnames are removed from the path. This check may become stricter
605 in future, although getting the balance between security and convenience is
606 particularly hard here.
610 @node Group permissions, X authority, Environment, Becoming someone else
611 @section How Become handles groups
613 As well as handling changes of user id, Become also changes group ids.
614 The exact changes Become makes are under user control.
617 * Primary group selection:: Setting the new primary group
618 * Subsidiary groups:: Setting subsidiary group memberships
622 @node Primary group selection, Subsidiary groups, Group permissions, Group permissions
623 @subsection Choosing a new primary group
625 By default, the primary group is chosen according to the login style
626 (@pxref{Login styles}): the `preserve' style retains the current primary
627 group, while `set-user' and `login' styles choose the target's primary group.
629 You can override Become's default choice using the @code{--group} (@code{-g}
633 become --group=@var{group} @dots{}
636 The chosen @var{group} may be either a group name or a numeric gid. The
637 group must be one of the following:
641 Your current primary group.
643 One of your current subsidiary groups.
645 The target user's primary group.
647 One of the target user's subsidiary groups.
650 Become will raise an error if this isn't the case.
653 @node Subsidiary groups, , Primary group selection, Group permissions
654 @subsection Handling subsidiary group memberships
656 Subsidiary group memberships are a powerful tool for managing permissions
657 under Unix. Traditionally, they tend to be tied to particular users. Become
658 tries to be sightly more intelligent about group memberships.
660 Become has a concept of @dfn{group style}, analogous to login style
661 (@pxref{Login styles}). The styles are selected by giving command line
667 Retain the existing group memberships; don't add any new groups.
670 @itemx --merge-groups
671 Merge group memberships of the target user with the exiting memberships.
674 @itemx --replace-groups
675 Replace the existing group memberships with the target user's memberships.
678 Again, the defaults are dependent on the chosen login style. Both `preserve'
679 and `set-user' merge group memberships; the `login' style replaces the set of
682 Note that you can do perverse things like replace all the subsidiary groups
683 but retain your primary group (using the @code{--group} option;
684 @pxref{Primary group selection}) if you like: Become won't try to stop you.
688 @node X authority, Running commands, Group permissions, Becoming someone else
689 @section Considerations for X authority
691 Other users can't read your @file{.Xauthority} file, if you have one. This
692 is as it should be: anyone who can read it can connect to your X server and
693 read or generate events. However, once you've become another user, you can't
694 open any X windows; this can be annoying if your favourite editor is X-based.
696 There are two basic approaches. Either you can send the shared account a
697 copy of your display's magic cookie, or you can retain permission to read the
700 Be aware that allowing a shared account to connect to your X display is a
704 * The user-group method:: A fairly secure way of handling X authority
705 * Using xauth:: A less secure method, which might be easier
709 @node The user-group method, Using xauth, X authority, X authority
710 @subsection The user-group method for handling X authority
712 This method is secure only if your site uses the `user-group' system. In
713 this system, each user is allocated a group containing only that user.
714 Usually this is made the user's default primary group, although that's not
717 When you start a new X session, ensure that your cookie file is owned by you
718 and your private group. Change the file's permissions so that it's group
719 readable. Finally, ensure that your private group is retained when you
720 become someone else (@pxref{Group permissions}), and that the
721 @code{XAUTHORITY} variable is set correctly.
723 Note that Unix's security mechanisms aren't designed to prevent processes
724 owned by the same user from interfering with each other. This method does
725 not provide complete security.
727 The following Bourne shell code in a @file{.xinitrc} should do most of the
731 XAUTHORITY="$HOME/.Xauthority"
733 chgrp mygroup $XAUTHORITY
734 chmod 640 $XAUTHORITY
738 In a C shell, this becomes
741 setenv XAUTHORITY $@{HOME@}/.Xauthority
742 chgrp mygroup $XAUTHORITY
743 chmod 640 $XAUTHORITY
746 The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
747 login styles, so this isn't a problem. You can now become other users, and
748 your X permissions will follow you around correctly.
750 It's probably worth noting that the @code{xauth} program annoyingly resets
751 the permissions on the cookie file every time it writes to it. This will be
752 particularly irritating if you use @code{ssh}'s X forwarding capabilities,
753 because every @code{ssh} connection will reset the permissions. You can deal
754 with this problem by putting a line
757 chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
761 in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or
764 if ($?XAUTHORITY) then
765 chmod 640 $XAUTHORITY >&/dev/null
767 chmod 640 $@{HOME@}/.Xauthority >&/dev/null
772 in @file{.cshrc} for C shell users.
775 @node Using xauth, , The user-group method, X authority
776 @subsection The @code{xauth} method for handling X authority
778 This method sends your X cookie to the shared account. It's therefore
779 intrinsically dangerous: you must be able to trust the other users of the
780 shared account not to take undue advantage of this situation.
782 The following (Bourne) shell snippet illustrates how you might send an
783 authorisation cookie to the shared account, to allow it to connect to your
787 if test -n "$BECOME_HOME"; then
788 XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
789 elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
791 :0.0) display=`hostname`:0.0 ;;
792 *) display="$DISPLAY" ;;
794 xauth extract - $display | \
795 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
796 done_xauth_cookie=yes; export done_xauth_cookie
800 The equivalent C shell code is
803 if ($?BECOME_HOME) then
804 setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
805 else if ($?DISPLAY && ! $?done_xauth_cookie) then
806 if ($DISPLAY == :0.0) then
807 set display="`hostname`:0.0"
809 set display="$DISPLAY"
811 xauth extract - $display | \
812 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
820 If the variable @code{BECOME_HOME} is set, then we're probably really someone
821 else, so point to the shared account's authority file.
824 Otherwise, check to see whether we have a display, and the authorisation has
825 not already been sent. If this is so, resolve a local display name into a
826 remote one (just in case) and then send it to the shared account.
831 @node Running commands, , X authority, Becoming someone else
832 @section Executing specific commands
834 As well as starting shells, Become can run single commands. This can be
839 It enables Become to be used in scripts.
842 It allows access to shared accounts to be controlled on the basis of the
846 To run a command as another user, say:
849 become @var{user} @var{command} [@var{argument}@dots{}]
852 If the request is granted, Become runs @var{command}, passing it any
853 arguments following the command name. Become doesn't run a shell, so there's
854 no extra escaping which needs to be done.
856 If you really want to run a shell command as another user, you can use the
860 become @var{user} -c @var{shell-command}
863 This is exactly equivalent to
866 become @var{user} /bin/sh -c @var{shell-command}
869 in every way. In particular, you must have permission to run @file{/bin/sh}
870 as @var{user} for it to work: Become doesn't attempt to interpret the shell
871 command in any way. Also note that Become always uses the Bourne shell,
872 regardless of your current shell preference, or @var{user}'s default shell.
873 (This is done to provide a stable programming interface which works
874 irrespective of changes to the shared account's configuration.)
877 @c --------------------------------------------------------------------------
878 @node Administering Become, Invoking Become, Becoming someone else, Top
879 @chapter Become administration
882 This chapter will explain how Become is administrated and maintained.
885 * Configuration files:: Overview of Become's configuration files
886 * Standalone or networked:: The two main types of Become installations
887 * The configuration file:: How to define who's allowed to do what
888 * Networked configuration:: Considerations for networked installations
893 @node Configuration files, Standalone or networked, Administering Become, Administering Become
894 @section Configuration files
896 Become keeps its configuration and administrative files in a directory
897 usually named @file{/etc/become}, although this can be changed with the
898 @code{--with-etcdir} option to the configuration script when you build
901 Not all of the files are needed on all machines.
905 The main configuration file, containing a description of which users are
906 allowed to become which other users, where, and what they're allowed to run
907 when they get there. Only needed on servers or standalone machines.
910 A list of servers to contact. Only needed on client machines.
913 The signing key to use when sending requests to servers. Needed on servers,
914 but not on standalone machines.
917 The verification keys to use when checking server responses. Needed on
918 clients, but not on standalone machines.
921 The process id of the server. Created automatically by Become's server when
926 @node Standalone or networked, The configuration file, Configuration files, Administering Become
927 @section Installation types
930 Become can be installed in two different ways, depending on how you want to
935 In a @dfn{standalone} installation, each Become request is dealt with
936 locally: the program reads the configuration file, and decides whether it
937 should grant or deny permission.
939 Standalone installations don't depend on servers being available, or even on
940 the existence of a network. They're useful for small sites, or sites with a
941 small number of users. The disadvantages are that reading the configuration
942 file takes a while, so the program doesn't feel as responsive as it should,
943 and ensuring that all the hosts' configuration files are synchronised becomes
944 difficult when you have lots of machines.
947 In a @dfn{network} installation, any Become requests are sent on to a
948 collection of servers. The servers analyse the request and send a reply back
949 which either authorises or forbids access.
951 A networked installation clearly depends on the servers' reliability. The
952 client reacts only to the first reply it receives, so as long as there is one
953 server running, everything should continue as normal.
955 A networked installation is useful when you have a large number of client
956 machines, particularly ones which may not be awake all the time. The full
957 configuration file only needs to be installed on a small number of servers;
958 the clients require only a list of server machines to contact, and an
959 encryption key to use.
964 @node The configuration file, Networked configuration, Standalone or networked, Administering Become
965 @section The configuration file
967 The main configuration file, usually called @file{/etc/become/become.conf},
968 contains all the rules which Become uses to decide whether to grant or deny
969 requests. It may also contain additional information for the benefit of
970 Become daemons, if you're using a networked installation.
973 * Requests and rules:: How the configuration file works
974 * Basic syntax:: Quick overview of Become's syntax
975 * Classes:: Defining classes of things
976 * Predefined classes:: Become predefines some (maybe) useful classes
977 * Allow statements:: Allow users to become other users
978 * Other statements:: Some other useful statements
979 * Example configuration file:: An example, showing a few features.
980 * Checking and querying:: Checking and querying configuration files
981 * Complete grammar:: Complete grammar for Become config files
985 @node Requests and rules, Basic syntax, The configuration file, The configuration file
986 @subsection Requests and rules
988 Become looks at four pieces of information when it's analysing a request:
992 the user's current identity;
994 the identity the user wishes to assume;
996 the host which generated the request; and
998 the command the user wishes to run.
1001 Each of these pieces of information is looked at when Become decides whether
1002 to honour a request.
1004 The configuration file's main purpose is to describe the conditions under
1005 which Become should honour a request. These conditions are described by a
1006 number of @emph{rules}. A rule consists of two lists of users (called `from'
1007 and `to'), a list of hosts, and a list of commands. A rule matches a request
1012 the user's current identity is in the rule's `from' list;
1014 the target user's identity is in the rule's `to' list;
1016 the host is in the rule's host list; and
1018 the command to be run is in the rule's command list.
1021 A request is honoured if there is a rule which matches the request.
1024 @node Basic syntax, Classes, Requests and rules, The configuration file
1025 @subsection Basic configuration file syntax
1027 The configuration file consists of a sequence of statements, each terminated
1030 Comments begin with a @samp{#} character, and continue to the end of the
1031 line. This is the only time newlines behave specially: newlines behave just
1032 like any other whitespace characters within statements.
1034 Strings are enclosed in double-quote characters (@samp{"}). Within a string,
1035 a backslash causes the following character to be treated literally, whatever
1036 it may be (including quotes, backslashes and newlines).
1038 Names begin with an alphabetic character or an underscore, and consist of
1039 letters, digits and underscores.
1042 @node Classes, Predefined classes, Basic syntax, The configuration file
1045 A @dfn{class} in Become is a set of users, hosts or commands. You can define
1046 and name your own classes using statements of the form:
1049 user @var{name} = @var{class-expr} ;
1050 command @var{name} = @var{class-expr} ;
1051 host @var{name} = @var{class-expr} ;
1054 A @var{class-expr} is an expression defining a class. You can build a
1055 complex class out of simple classes using the operators (in ascending
1056 precedence order) @samp{,}, @samp{-}, @samp{|} and @samp{&}, which represent
1057 the set options `union', `subtraction', `union' (again!), and `intersection'.
1058 Subexpressions can be parenthesised to override the default precedence.
1059 Once a class name has been defined, as shown above, it can be used in
1060 subsequent class expressions.
1062 A single user may be designated by either a user name (in quotes) or an
1063 integer uid. Commands and hosts may be designated by quoted strings which
1064 may contain wildcards. Host strings are matched against both numeric (dotted
1065 quad) IP addresses and the reverse-resolved hostname. Command strings are
1066 matched against the absolute pathname of the command the user wants to
1071 @node Predefined classes, Allow statements, Classes, The configuration file
1072 @subsection Predefined classes
1074 In an attempt to make life a bit easier, Become creates a collection of
1077 The standard classes @code{all} and @code{none} match anything and nothing
1078 respectively. The @code{all} class is useful in some contexts: it gives you
1079 a way of saying `everything except@dots{}', for example:
1082 user MUNDANES = all - SYSHACKS;
1086 The @code{none} class is provided because it's needed internally anyway and
1087 someone might come up with a use for it.
1089 Become also defines some other classes:
1093 For each username @var{user}, Become adds a class called @samp{@var{user}}
1094 which matches just that user.
1097 For each group name @var{group}, Become creates a class called
1098 @samp{@var{group}} which matches any user who is a member of that group.
1100 @item For each netgroup @var{netgroup}, Become creates two classes:
1101 @samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
1102 @samp{h_@var{netgroup}} which matches any host listed in the netgroup.
1105 If a name is used for both a user @emph{and} a group, then corresponding
1106 class ends up containing the user together with all of the group members.
1107 For this reason, it's probably better to use the predefined classes for
1108 groups rather than individual users -- use quoted user names for individual
1111 Note that users and groups are read using the standard @code{get*ent} calls
1112 @emph{and} directly from the NIS server (if there is one). The idea here is
1113 that a Become server can be run on a machine which allows restricted logins.
1114 It still needs to know about all the users known to the outside world.
1116 Netgroups are read only from the NIS servers. In particular, although GNU
1117 systems allow netgroup databases to be stored in local files, Become won't
1118 read them because there's no defined interface for enumerating netgroups.
1121 @node Allow statements, Other statements, Predefined classes, The configuration file
1122 @subsection Allow statements
1124 The @code{allow} statement defines the rules Become uses when deciding
1125 whether to grant a request; see @ref{Requests and rules}.
1128 allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
1131 (The @var{host-class} is optional, but must be enclosed in square brackets if
1134 The four classes in an allow statement are called, respectively, the `host',
1135 the `to-user', the `from-user' and the `command'. Any of the four classes
1136 may be omitted, and an omitted class defaults to `all'.
1138 When a request is received, Become checks the fields in the request against
1139 the classes in each allow statement of the configuration file. If a
1140 statement matches, the request is granted; if there are no full matches,
1141 the request is denied.
1144 @node Other statements, Example configuration file, Allow statements, The configuration file
1145 @subsection Other statements
1147 Two other statement types are defined. They only have an effect on Become in
1152 keyfile @var{key-file} ;
1156 The @code{port} statement specifies the port to which the server should
1157 listen; the @var{port} may be be an integer or a quoted service name. The
1158 @code{keyfile} statement instructs Become to use the key from the file named
1159 @var{key-file}, which must be a quoted string.
1162 @node Example configuration file, Checking and querying, Other statements, The configuration file
1163 @subsection An example configuration file
1169 # Example configuration file
1172 allow wheel -> "root";
1174 user NEWS = "fred", "jim";
1175 allow NEWS -> "news";
1177 user HTTP = "jim", "bob";
1178 allow ["www.somewhere.com"]
1179 HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
1183 @node Checking and querying, Complete grammar, Example configuration file, The configuration file
1184 @subsection Checking and querying the configuration file
1186 At a reasonably sized site, Become configuration files can get rather large,
1187 and becomes tricky to work out exactly who's allowed to do what and where.
1189 The @code{bcquery} tool provided allows Become configuration files to be
1190 verified and queried. It can be used to ensure that a file is syntactically
1191 correct before it is deployed, or to enquire about privileges granted.
1194 * Verifying config files:: Checking a configuration file is correct
1195 * Querying config files:: Asking questions about privileges
1196 * Output formats:: Different ways of formatting output
1197 * Restricting output:: Being selective about what gets output
1198 * bcquery reference:: Complete command line reference
1201 @node Verifying config files, Querying config files, Checking and querying, Checking and querying
1202 @subsubsection Verifying configuration files
1204 A common use of @code{bcquery} is to ensure that a configuration file is
1205 actually valid. The command
1208 bcquery [-file @var{file}] -check
1212 verifies that a configuration file conforms to Become's expectations. If
1213 there are any errors in @var{file}, they are reported, and @code{bcquery}
1214 will return a nonzero exit code.
1216 If no @var{file} is specified, @code{bcquery} will read the configuration
1217 file which Become itself reads by default, usually
1218 @code{/etc/become/become.conf}.
1221 @node Querying config files, Output formats, Verifying config files, Checking and querying
1222 @subsubsection Querying configuration files
1224 The @code{bcquery} program will list all rules which match a selected request
1225 pattern. For example, you can display all rules which allow a particular
1226 user to change identity, or all rules which allow people to assume root
1227 privileges on a particular host.
1230 bcquery [-file @var{file}] @var{query}
1233 The following simple queries are supported:
1236 @item @code{-from} @var{user}
1237 Matches any rule containing @var{user} in its `from' list.
1238 @item @code{-to} @var{user}
1239 Matches any rule containing @var{user} in its `to' list.
1240 @item @code{-host} @var{host}
1241 Matches any rule containing @var{host} in its host list.
1242 @item @code{-command} @var{cmd}
1243 Matches any rule containing @var{cmd} in its `command' list.
1247 Simple queries can be combined using the following operators:
1250 @item @var{query-a} @code{-or} @var{query-b}
1251 Matches a rule matched by either @var{query-a} or @var{query-b}.
1252 @item @var{query-a} @code{-and} @var{query-b}
1253 Matches a rule matched by both @var{query-a} and @var{query-b}.
1254 @item @code{-not} @var{query}
1255 Matches a rule which is not matched by @var{query}.
1256 @item @code{(} @var{query} @code{)}
1257 Matches a rule matched by @var{query} (overrides default precedence).
1260 The @code{-and}, @code{-or} and @code{-not} operators may be written
1261 @code{&}, @code{|} and @code{!} respectively, if you prefer, and the
1262 @code{-and} operator is optional. These characters (and the parentheses
1263 @code{(} and @code{)}) may need to be quoted to prevent interpretation by the
1266 Some examples may explain what's going on:
1269 @item bcquery -from hacker
1270 Displays all rules applying to user `hacker'.
1271 @item bcquery -host somehost -to root
1272 Displays rules allowing people to become root on @code{somehost}.
1276 @node Output formats, Restricting output, Querying config files, Checking and querying
1277 @subsubsection Output formats
1279 The @code{bcquery} program has two distinct output formats: `rows' and
1282 The `columns' format is probably the simpler to understand, and certainly the
1283 easier to read. Each matching record is displayed with the lists of users,
1284 hosts and commands in columns. A query on the example configuration file
1285 (@pxref{Example configuration file}) is shown below:
1288 FROM TO HOST COMMAND
1290 frankie root ALL ALL
1296 jim httpd www.somewhere.com /bin/kill
1297 bob /etc/init.d/httpd
1301 The `columns' format can only show simple lists. A more complex class
1302 definition will show up as @samp{<complex>} in a `columns' format listing.
1304 The `rows' format is capable of displaying classes in their full generality,
1305 but is harder to parse and read. It displays each list in the form of an
1306 expression, in more or less the same syntax as a class definition
1309 The default behaviour is to use `columns' format where possible, or `rows'
1310 format if some of the lists are too complex to be represented in columns.
1311 You can select a format explicitly using the @code{-columns} or @code{-rows}
1312 options, which is useful if you're trying to parse the output of
1313 @code{bcquery} with a script.
1316 @node Restricting output, bcquery reference, Output formats, Checking and querying
1317 @subsubsection Restricting output
1319 It's also possible to suppress bits of information about each matched rule.
1320 For example, you can show only the `from' list, or just the `to' and `host'
1321 lists. This is done with the @code{-output} option.
1323 Each list is given a letter; the `from' list is called @samp{f}, the `to'
1324 list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
1325 select which lists are displayed by giving the corresponding letters (the
1326 order isn't important). You can also turn individual lists on or off by
1327 preceding the characters with @samp{+} or @samp{-} characters. If you start
1328 with a @samp{+} or @samp{-}, then the last-set selection (or the initial
1329 default of all-lists-enabled) is modified.
1331 For example, @samp{-output ftc} shows only the `from', `to' and `command'
1332 lists. This could be written @samp{-output -h} too, to turn the hosts list
1335 This option is mainly useful with the `columns' output format (@pxref{Output
1336 formats}) to save scripts having to select columns out themselves.
1339 @node bcquery reference, , Restricting output, Checking and querying
1340 @subsubsection @code{bcquery} options summary
1343 bcquery [@var{option}@dots{}] [@var{query}]
1346 The @var{option}s available are:
1350 Displays a summary of the available options, and exits.
1352 @item @code{-file} @var{file}
1353 Read @var{file}, rather than the compiled-in default (usually
1354 @file{/etc/become/become.conf}).
1357 Don't read a configuration file. Instead, display the query tree parsed from
1358 the command line. This is a debugging feature.
1361 Don't attempt to output any rules. Instead, just check the configuration
1364 @item @code{-output} @var{spec}
1365 Selects which columns are to be displayed for each matching rule.
1366 For full details, see @ref{Restricting output}.
1368 @item @code{-columns}
1370 Forces `columns' or `rows' output format. @xref{Output formats}.
1372 @item @code{-nohead}
1373 Suppress the header line at the top of the output in `columns' mode. Makes
1374 the output more amenable to automatic processing (but harder to read).
1376 @item @code{-from} @var{user}
1377 @itemx @code{-to} @var{user}
1378 @itemx @code{-host} @var{hostname}
1379 @itemx @code{-command} @var{cmd}
1380 Simple queries for selecting rules. @xref{Querying config files}.
1385 Operators for combining queries into something useful. @xref{Querying config
1390 @node Complete grammar, , Checking and querying, The configuration file
1391 @subsection Complete grammar for configuration files
1394 @var{file} ::= @var{file} @var{statement}
1396 @var{statement} ::= @var{class-def}
1401 @var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
1402 | @samp{command} @var{name} = @var{class-expr} @samp{;}
1403 | @samp{host} @var{name} = @var{class-expr} @samp{;}
1405 @var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
1406 @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}
1408 @var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
1411 @var{opt-user-spec} ::= @var{class-expr}
1414 @var{opt-command-spec} ::= @samp{:} @var{class-expr}
1417 @var{port-spec} ::= @samp{port} @var{integer} @samp{;}
1418 | @samp{port} @var{string} @samp{;}
1420 @var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}
1422 @var{class-expr} ::= @var{class-diff-expr}
1423 | @var{class-expr} @samp{,} @var{class-diff-expr}
1425 @var{class-diff-expr} ::= @var{class-isect-expr}
1426 | @var{class-diff-expr} @samp{-} @var{class-union-expr}
1428 @var{class-union-expr} ::= @var{class-isect-expr}
1429 | @var{class-union-expr} @samp{|} @var{class-isect-expr}
1431 @var{class-isect-expr} ::= @var{class-primary}
1432 | @var{class-isect-expr} @samp{&} @var{class-primary}
1434 @var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
1438 @var{integer} ::= one or more digits (@samp{0}--@samp{9})
1440 @var{name} ::= an alphabetic character or underscore, followed by zero or
1441 more alphanumeric characters or underscores
1443 @var{string} ::= @samp{"} @var{string-chars} @samp{"}
1445 @var{string-chars} ::= @var{string-chars} @var{string-char}
1448 @var{string-char} ::= a @samp{\} followed by any character
1449 | any character other than @samp{"}, @samp{\} or newline
1456 @node Networked configuration, , The configuration file, Administering Become
1457 @section Networked configuration
1459 If you're planning to use Become in a standalone way, you can skip this
1463 * Choosing servers:: Which servers Become tries to talk to
1464 * Setting up keys:: How to generate keys for Become
1465 * Issuing a new key:: How to issue new keys without disruption
1469 @node Choosing servers, Setting up keys, Networked configuration, Networked configuration
1470 @subsection Choosing servers
1472 Become notices that it's meant to send requests to a server if it finds a
1473 @file{become.server} file. This file contains entries of the form
1476 @var{host} [: @var{port}]
1479 If the @var{port} is omitted, Become chooses a port by looking at the
1480 services database for a service which matches the name by which Become was
1481 invoked: normally this will be @samp{become}.
1483 Become sends a request to all of the servers and believes the first valid
1484 reply it receives. Since servers ignore requests they believe to be invalid,
1485 this enables you to change Become's key without disrupting service
1486 (@pxref{Issuing a new key}).
1488 If you're using NIS, you should try to ensure that Become servers runs only
1489 on NIS servers; the NIS master is probably a good choice.
1491 Become isn't particularly processor-intensive, and doesn't seem to require
1495 @node Setting up keys, Issuing a new key, Choosing servers, Networked configuration
1496 @subsection Setting up keys
1498 Communication between Become clients and the server is encrypted to ensure
1499 that it's not feasible to gain unauthorised privilege by subverting the
1500 network. Become uses the DSA algorithm to ensure authenticity of replies.
1502 Each client machine, and the server, must have a copy of the same key. The
1503 key is usually stored in @file{/etc/become/become.key}. Become's keys are
1506 The key file can be generated using Catacomb's @code{key} program. The
1510 key -k /etc/become/become.key add -adsa -e"now + 1 year" become
1511 key -k /etc/become/become.key extract -f -secret /etc/become/become.pubkey
1515 will generate a suitable DSA key, and extract the public part. You should
1516 install the public key on all of your client computers, writable only by
1517 root. The private key should be only on the server, and readable or writable
1520 You can also use elliptic-curve DSA. The key-generation runes are more
1521 complicated in this case. For example,
1524 key -k /etc/become/become.key add -aec -Cnist-p256 -e"now + 1 year" \
1525 become sig=ecdsa hash=sha256
1527 The @code{hash=sha256} is not required, but it's good to have a hash function
1528 as strong as your curve. See the manpage for @code{key} for more details
1529 about generating elliptic curve keys, and for the kinds of curves supported.
1531 If you have multiple servers, they can all have different private keys.
1532 You'll need to put all of the public keys in the
1533 @file{/etc/become/become.pubkey} file.
1536 @node Issuing a new key, , Setting up keys, Networked configuration
1537 @subsection Issuing a new key
1539 When you're sending out a new key, you run a risk of disrupting service. The
1540 server reads a new key; the clients still have the old one.
1542 We used to recommend running two servers. Now, however, you can generate the
1543 new key, install the new public key on the clients in addition to the old
1544 one, and then install the new private key on the server. The clients try all
1545 valid public keys when attempting to authenticate a response, so this
1549 @c --------------------------------------------------------------------------
1550 @node Invoking Become, , Administering Become, Top
1551 @chapter Invoking Become
1554 This chapter provides an exhaustive description of Become's command line
1555 options, organised in a reference-manual sort of way.
1558 * Becoming another user:: Options for becoming another user
1559 * Starting Become daemons:: Options for starting Become daemons
1560 * Debugging options:: Options to use when Become goes wrong
1565 @node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
1566 @section Becoming another user
1568 @subsection Synopsis
1571 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
1574 Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
1575 order you like; the important thing is that all of them appear before the
1581 The @var{option}s appropriate for this mode are as follows:
1586 Display a (fairly verbose) help message describing the various command line
1587 options and exits successfully.
1591 Display a terse summary of the command line options and exits successfully.
1595 Display's Become's version number and exits successfully.
1598 @item --preserve-environment
1599 Selects the `preserve' login style (@pxref{The preserve style}). All
1600 environment variables are preserved. The default command is the current
1601 user's own shell. The default primary group becomes the current primary
1602 group; the default group style is set to `merge'.
1607 Selects the `set-user' login style (@pxref{The set-user style}). Most
1608 environment variables are preserved, but @code{USER}, @code{LOGNAME},
1609 @code{HOME} and other user-specific variables are altered to reflect the
1610 target user's configuration. The default command is the target user's shell.
1611 The default primary group becomes the target user's primary group; the
1612 default group style is set to `merge'.
1616 Selects the `login' login style (@pxref{The login style}). The environment
1617 is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
1618 The default command is the target user's shell. The default primary group
1619 becomes the target user's primary group; the default group style is set to
1622 @item -g @var{group}
1623 @itemx --group=@var{group}
1624 Selects @var{group} as the primary group; it may be either a group name or a
1625 numeric group id. Note that @var{group} must be the primary group or
1626 a subsidiary group of either the current user or the target user.
1629 @itemx --keep-groups
1630 Selects the `keep' group style (@pxref{Subsidiary groups}). The current set
1631 of subsidiary group memberships are passed on unchanged.
1634 @itemx --merge-groups
1635 Selects the `merge' group style (@pxref{Subsidiary groups}). The current set
1636 of subsidiary group memberships are merged with the subsidiary groups of the
1640 @itemx --replace-groups
1641 Selects the `replace' group style (@pxref{Subsidiary groups}). The target
1642 user's subsidiary group memberships are passed on; the current subsidiary
1643 groups are discarded.
1645 @item -c @var{shell-cmd}
1646 @itemx --command=@var{shell-cmd}
1647 Sets the @var{command} and @var{argument}s to invoke
1648 @code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
1649 instead of just @code{exec}ing a program. Note that permissions are checked
1650 for executing the Bourne shell @code{/bin/sh}; the contents of the
1651 @var{shell-cmd} are not inspected.
1654 The @var{env-var} arguments fine-tune the environment passed to the command.
1655 Each @var{env-var} setting must be one of the following:
1658 @item @var{var}=@var{value}
1659 Assign the variable named @var{var} the value @var{value}. Protect the
1660 variable @var{var} from modifications by the login style.
1663 Protect the variable @var{var} from modifications by the login style, but
1664 don't change its value.
1667 Remove the variable @var{var} from the environment; do not pass it on.
1670 The @var{user} specifies the user as whom the @var{command} should be
1671 executed (i.e., the @dfn{target user}). It may be a user name or a numeric
1674 The @var{command} specifies a command to execute. If @var{command} does not
1675 contain a path, it is looked for using the current @code{PATH} environment
1676 variable. The resulting pathname is canonified if necessary, to produce an
1677 absolute pathname. Note that symbolic links are @emph{not} resolved -- this
1678 prevents an attack whereby a user could invoke a program, passing it an
1679 unusual @code{argv[0]} which might cause unusual behaviour.
1681 The @var{command} name is used both as the command to execute and passed to
1682 the command as @code{argv[0]}. It is not possible to specify an alternative
1683 value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
1684 passed as @code{argv[1]} upwards.
1686 If no @var{command} is given, a shell is invoked; the particulars of the
1687 shell are determined by the login style (see above).
1689 The @var{command} is executed as follows:
1693 The subsidiary groups are chosen as determined by the group style.
1695 The real and effective gids are set.
1697 The real and effective uids are set.
1699 The @var{command} is called using the standard @code{execve} system call.
1704 @node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
1705 @section Starting Become daemons
1707 @subsection Synopsis
1710 become --daemon [@var{option}@dots{}]
1716 The following options are appropriate to this mode:
1721 Display a (fairly verbose) help message describing the various command line
1722 options and exits successfully.
1726 Display a terse summary of the command line options and exits successfully.
1730 Display's Become's version number and exits successfully.
1734 Start a Become server, instead of processing a request. Become will read its
1735 command line options, read in the configuration file (and verify that it's
1736 correct) and then fork into the background to wait for incoming requests.
1737 Become relinquishes all setuid privileges (by setting all uids to the real
1738 uid) when it enters daemon mode. It is therefore only really useful to run a
1739 daemon as the superuser.
1742 @itemx --port=@var{port}
1743 Listen for requests on @var{port}. This option is overridden by the
1744 @code{port} option in the configuration file.
1747 @itemx --config-file=@var{file}
1748 Read configuration from @var{file}, instead of the default (set at
1749 compile time, usually @file{/etc/become/become.conf}).
1752 The syntax of the configuration file is described in @ref{The configuration
1756 @node Debugging options, , Starting Become daemons, Invoking Become
1757 @section Debugging options
1759 Some options are only useful when trying to find out why Become is
1760 misbehaving. Of course, this never happens, so here are the options which
1761 you won't need to use:
1764 @item -T[@var{file}]
1765 @itemx --trace[=@var{file}]
1766 Write trace information to @var{file} (or to standard output, if no
1767 @var{file} is specified). You must be able to create the file and open it
1770 @item -L[@var{feature}...]
1771 @itemx --trace-level[=@var{feature}]
1772 Selects which features Become ought to trace. Each feature is allocated a
1773 letter; simply string together the letters for the features you want to
1774 debug. The letters @samp{D} and @samp{A} stand respectively for `default'
1775 and `all' features; you can subtract from them by saying, for example,
1776 @samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
1777 The exact list of features supported at any one time can be listed by giving
1778 the @code{--trace-level} option without an argument.
1781 @itemx --impersonate=@var{user}
1782 Pretend to be @var{user} instead of yourself when the request is checked.
1783 This option can only be used if it wasn't disabled at compile-time and if
1784 Become is not running setuid. Even so, Become will only inform you of the
1785 outcome; it will not execute any commands.
1790 @c --------------------------------------------------------------------------
1792 @c --- No index yet ---
1794 @c @node Concept index, , Invoking Become, Top
1795 @c @unnumbered Concept index
1802 @c ----- That's all, folks --------------------------------------------------