1 \input texinfo @c -*-texinfo-*-
3 @c $Id: become.texi,v 1.5 2003/10/12 00:14:49 mdw Exp $
5 @c Documentation for `become'
10 @c ----- Revision history ---------------------------------------------------
12 @c $Log: become.texi,v $
13 @c Revision 1.5 2003/10/12 00:14:49 mdw
14 @c Major overhaul. Now uses DSA signatures rather than the bogus symmetric
15 @c encrypt-and-hope thing. Integrated with mLib and Catacomb.
17 @c Revision 1.4 1998/04/23 13:16:14 mdw
18 @c Include `texinice' to produce decent printed output. Add documentation
19 @c for new `bcquery' program. Various fixes, including spelling mistakes,
20 @c and some factual inaccuracies.
22 @c Revision 1.3 1998/01/20 14:37:43 mdw
23 @c Fix typo. Short form of `--preserve' should be `-e', not `-p'.
25 @c Revision 1.2 1998/01/12 16:41:31 mdw
26 @c Tidying for new release versions. Fix copyright date.
28 @c Revision 1.1 1997/09/18 11:16:34 mdw
29 @c Brand new Texinfo manual, with wider scope than the original LaTeX one.
32 @c ----- Standard boilerplate -----------------------------------------------
35 @setfilename become.info
37 @setchapternewpage odd
47 @c ----- Useful macros ------------------------------------------------------
51 @c ----- Copyright matters --------------------------------------------------
53 @c --- The `Info' version ---
57 This file documents Become version @value{version}.
59 Copyright (c) 1998 European Bioinformatics Institute.
61 Permission is granted to make and distribute verbatim copies of this
62 manual provided the copyright notice and this permission notice are
63 preserved on all copies.
66 Permission is granted to process this file through TeX and print the
67 results, provided the printed document carries a copying permission
68 notice identical to this one except for the removal of this paragraph
69 (this paragraph not being relevant to the printed manual).
72 Permission is granted to copy and distribute modified versions of this
73 manual under the conditions for verbatim copying, provided also that the
74 sections entitled `Copying' and `GNU General Public License' are
75 included exactly as in the original, and provided that the entire
76 resulting derived work is distributed under the terms of a permission
77 notice identical to this one.
79 Permission is granted to copy and distribute translations of this manual
80 into another language, under the above conditions for modified versions,
81 except that this permission notice may be stated in a translation
82 approved by the European Bioinformatics Institute.
86 @c --- Printed title page ---
90 @title The Become program
91 @subtitle Become version @value{version}
92 @author Mark Wooding @email{mdw@@ebi.ac.uk}
95 @vskip 0pt plus 1filll
97 Copyright @copyright{} 1998 European Bioinformatics Institute.
99 Permission is granted to make and distribute verbatim copies of this
100 manual provided the copyright notice and this permission notice are
101 preserved on all copies.
103 Permission is granted to copy and distribute modified versions of this
104 manual under the conditions for verbatim copying, provided also that the
105 sections entitled `Copying' and `GNU General Public License' are
106 included exactly as in the original, and provided that the entire
107 resulting derived work is distributed under the terms of a permission
108 notice identical to this one.
110 Permission is granted to copy and distribute translations of this manual
111 into another language, under the above conditions for modified versions,
112 except that this permission notice may be stated in a translation
113 approved by the European Bioinformatics Institute.
118 @c --------------------------------------------------------------------------
120 @node Top, Copying, (dir), (dir)
124 Become is a system for managing shared accounts. It allows users to
125 `become' other users in order to do useful work. It can be managed on a
126 central server (or a small number of central servers), or it can run
129 This file documents Become version @value{version}.
134 * Copying:: Your rights to distribute and modify
135 * Introduction:: A brief introduction to Become
136 * Becoming someone else:: How to become somebody else
137 * Administering Become:: How to maintain Become
138 * Invoking Become:: Reference to Become's command line options
141 --- The Detailed Node Listing ---
143 Becoming someone else
145 * Terminology:: Some important terms defined
146 * Environment:: Login styles and environment variables
147 * Group permissions:: How Become handles group permissions
148 * X authority:: Problems with X authority files
149 * Running commands:: Running commands other than a shell
151 How Become sets up the environment
153 * New environment variables:: Become adds some useful environment variables
154 * Login styles:: Choose how Become sets the environment
155 * Tweaking the environment:: Altering individual environment variables
156 * Removed variables:: Some environment variables aren't passed on
160 * The preserve style:: Preserve the current environment
161 * The set-user style:: Set user-specific variables (like @code{su})
162 * The login style:: Clear the environment (like @code{login})
164 How Become handles groups
166 * Primary group selection:: Setting the new primary group
167 * Subsidiary groups:: Setting subsidiary group memberships
169 Considerations for X authority
171 * The user-group method:: A fairly secure way of handling X authority
172 * Using xauth:: A less secure method, which might be easier
174 Become administration
176 * Configuration files:: Overview of Become's configuration files
177 * Standalone or networked:: The two main types of Become installations
178 * The configuration file:: How to define who's allowed to do what
179 * Networked configuration:: Considerations for networked installations
181 The configuration file
183 * Requests and rules:: How the configuration file works
184 * Basic syntax:: Quick overview of Become's syntax
185 * Classes:: Defining classes of things
186 * Predefined classes:: Become predefines some (maybe) useful classes
187 * Allow statements:: Allow users to become other users
188 * Other statements:: Some other useful statements
189 * Example configuration file:: An example, showing a few features.
190 * Checking and querying:: Checking and querying configuration files
191 * Complete grammar:: Complete grammar for Become config files
193 Checking and querying the configuration file
195 * Verifying config files:: Checking a configuration file is correct
196 * Querying config files:: Asking questions about privileges
197 * Output formats:: Different ways of formatting output
198 * Restricting output:: Being selective about what gets output
199 * bcquery reference:: Complete command line reference
201 Networked configuration
203 * Choosing servers:: Which servers Become tries to talk to
204 * Setting up keys:: How to generate keys for Become
205 * Issuing a new key:: How to issue new keys without disruption
209 * Becoming another user:: Options for becoming another user
210 * Starting Become daemons:: Options for starting Become daemons
211 * Debugging options:: Options to use when Become goes wrong
216 @c --------------------------------------------------------------------------
217 @node Copying, Introduction, Top, Top
218 @unnumbered The GNU General Public License
223 @c --------------------------------------------------------------------------
224 @node Introduction, Becoming someone else, Copying, Top
225 @unnumbered Introduction
228 It's often useful to be able to share accounts between a number of
229 users. For example, a group maintaining an externally visible service
230 need to be able to start and kill the server process. Giving such a
231 shared account a password is a fairly bad plan: such passwords tend not
232 to get changed very often, and they have a habit of spreading beyond the
233 group of legitimate users.
235 The Become program presented here offers a solution to the problems of
236 shared accounts. It allows the system administrator to define which
237 users are allowed access to which accounts, on which hosts, and to
238 execute which commands. Such shared accounts can then, in general, have
239 their passwords removed.
241 This coincidentally has another advantage: when `becoming' to a shared
242 account, a user can retain her@footnote{Or his. I'll choose one or the
243 other fairly randomly throughout this manual.} own environment, which
244 she's carefully crafted and honed over the years, rather then being
245 presented with some lowest-common-denominator setup which probably
246 doesn't even use the right shell.
248 The configuration file for Become can either be distributed to all the
249 various hosts in a network or a few carefully set up and secure servers
250 (@pxref{Standalone or networked}).
253 @c --------------------------------------------------------------------------
254 @node Becoming someone else, Administering Become, Introduction, Top
255 @chapter Becoming someone else
258 The simplest way to become someone else is to say
265 Become will check to see whether you're allowed to become @var{user}. If you
266 are, it starts a shell process with the user-id set to @var{user}. Any
267 commands you type are executed with the privileges of @var{user}.
269 The full invocation is slightly more complicated:
272 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
275 Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
276 order -- the important point is that all of them appear before the
277 @var{command}, if there is one.
280 * Terminology:: Some important terms defined
281 * Environment:: Login styles and environment variables
282 * Group permissions:: How Become handles group permissions
283 * X authority:: Problems with X authority files
284 * Running commands:: Running commands other than a shell
289 @node Terminology, Environment, Becoming someone else, Becoming someone else
292 The following terms get used quite a bit in the following text:
296 An invocation of Become, asking permission to become another user.
299 The (real) user id of the process which invoked Become; usually, this will be
303 The user whom you want to become, named in a request.
308 @node Environment, Group permissions, Terminology, Becoming someone else
309 @section How Become sets up the environment
311 There are thorny problems with handling the user's environment. It seems
312 that (the author's initial assessment notwithstanding) there is no single
313 best way of handling environment variables. As a result, Become can do just
314 about everything you might want it to. This gets slightly complicated.
315 Don't worry: it's not as hard as all that.
318 * New environment variables:: Become adds some useful environment variables
319 * Login styles:: Choose how Become sets the environment
320 * Tweaking the environment:: Altering individual environment variables
321 * Removed variables:: Some environment variables aren't passed on
325 @node New environment variables, Login styles, Environment, Environment
326 @subsection Environment variables created by Become
328 To help you (and, more importantly, your startup scripts) keep track of who
329 you are, and who you were originally, Become adds some variables to the
330 environment of any processes it starts.
334 The name of the target user (i.e., the user you are now). It might be useful
335 to test this value in shell startup scripts, for example.
338 The home directory of the target user. It can be handy to read startup and
339 other configuration files from here.
341 @item BECOME_OLD_USER
342 The name of the user who invoked Become.
344 @item BECOME_OLD_HOME
345 The home directory of the `old' user.
347 @item BECOME_ORIGINAL_USER
348 This is intended to be the name you logged in with. If it's unset, Become
349 sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
352 @item BECOME_ORIGINAL_HOME
353 This is intended to be the home directory you logged in with. If it's unset,
354 Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
358 Don't even think about relying on these variables as a form of
359 authentication. It won't work. They're provided only to help organise
364 @node Login styles, Tweaking the environment, New environment variables, Environment
365 @subsection Login styles
367 Originally, Become always tried to preserve your environment. There's a
368 rational explanation for this approach, which is given in the description of
369 the `preserve' style below. Unfortunately, not everyone liked this
370 approach. As a result, there's now a collection of different login styles.
372 Login styles are selected by giving command line arguments:
377 The original style: try to preserve the existing user's environment as much
382 Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
383 the target user rather than the old user. All other variables are preserved.
387 Attempts to make the `become' process as much like a real login as possible.
388 All variables not explicitly preserved are deleted, and a new environment is
389 built, reflecting the target user.
392 The various styles, and the reasons behind them, are described below.
395 * The preserve style:: Preserve the current environment
396 * The set-user style:: Set user-specific variables (like @code{su})
397 * The login style:: Clear the environment (like @code{login})
401 @node The preserve style, The set-user style, Login styles, Login styles
402 @subsubsection The `preserve' login style
404 You've spent many hours (days? weeks, even?) customising and honing your
405 startup files, learning how to use your shell, and tweaking your favourite
406 text editor until it's just the way you like it. So there can be few things
407 more annoying than logging into a shared account to find out that the shell's
408 wrong, your editor startup files are ignored, and nothing works quite the way
409 you'd like it to. Typically you can't change this without annoying the other
410 users: the result is a horrible compromise which dissatisfies everyone
413 The `preserve' style lets you take your standard environment with you when
414 you become someone else. It tries hard not to modify any environment
417 Become starts your standard shell. If you have an environment variable
418 @code{SHELL} defined, than this is executed. Otherwise, the shell specified
419 in your entry in the password file is used. (You must have permission to
420 execute whatever shell is chosen as the target user, or you'll just be given
423 Most programs look at environment variables in preference to looking up
424 entries in the password database; e.g., they tend to use @code{USER} or
425 @code{LOGNAME} for the user name, and @code{HOME} for your home directory.
426 As a result, most programs will continue to find their configuration files in
427 your home directory. Also, systems like RCS will use your real name, rather
428 than the name of the user that you have become.
430 To make best use of this login style, you may need to adjust your login
431 scripts to notice when @code{BECOME_USER} is someone else, and read in
432 appropriate definitions. For example, a `bash' user might say something like
433 this in her @file{.bashrc}:
436 if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
440 Similarly, a C shell user (either `tcsh' or `csh') might say something like
443 if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
446 (Note that plain Bourne shell users have a slight problem, because the Bourne
447 shell only reads configuration things on a login, not when a normal
448 interactive shell is started.)
451 @node The set-user style, The login style, The preserve style, Login styles
452 @subsubsection The `set-user' login style
454 The author sees the main use of Become as allowing a user to acquire the
455 privileges associated with a shared account without all the problems which
456 shared accounts usually cause. To the author's way of thinking, one of the
457 main problems is that your environment gets replaced by something alien and
458 wrong. People disagree with me over this point, and for this reason the
459 `set-user' style exists.
461 The objective of `set-user' style is to behave similarly to the standard
462 @code{su} command. Unless they've been preserved explicitly (@pxref{Tweaking
463 the environment}), `set-user' mode sets the following environment variables:
468 The name of the target user.
471 The home directory of the target user.
474 The target user's default shell
477 The result of this is that the shell will read the target user's
478 configuration files and present you with the environment set up there.
480 I can't think of this style as being anything other than a migration aid
481 while users are getting used to the freedom offered by the `preserve' style.
484 @node The login style, , The set-user style, Login styles
485 @subsubsection The `login' login style
487 The `login' style causes Become to attempt to emulate a full login. Become
488 will empty the environment of almost variables which aren't explicitly
489 preserved (@pxref{Tweaking the environment}). However, the following
490 variables are retained:
502 It will set the following variables:
507 The name of the target user.
510 The home directory of the target user.
513 The target user's default shell
516 An educated guess at where the target user's mailbox is.
519 By default, it runs the target user's shell, informing it that this is a
520 login by setting the first character of @code{argv[0]} to @samp{-}.
522 Become makes no entries in the @file{utmp} and @file{wtmp} files.
526 @node Tweaking the environment, Removed variables, Login styles, Environment
527 @subsection Tweaking individual environment variables
529 Become's login styles provide a sort of course-grained control over the
530 environment. Sometimes the control isn't fine enough. Become lets you tweak
531 individual variables: you can set, delete, or preserve named variables from
534 There are three different things you can do with environment variables:
538 Set a variable called @var{var} to a value @var{value}, by saying
541 @var{var}=@var{value}
545 The variable is preserved from automatic deletion by the login-style rules.
548 Delete a variable called @var{var} from the environment, by saying
555 Preserve a variable @var{var} from being deleted or modified by Become's
556 login-style rules, but not change its value, by saying
563 Just to try and make this slightly more sensible, here's an example. Suppose
564 I want my @code{XAUTHORITY} variable to be set when I become user `fred':
567 become XAUTHORITY=$HOME/.Xauthority fred
571 should do the job nicely. Similarly, if I want to log in as `bob', but don't
572 want my @code{EDITOR} variable to change:
575 become --login EDITOR! bob
579 (Of course, in this example, I'm at the mercy of Bob's shell init files as to
580 whether his choice of editor overrides mine.)
584 @node Removed variables, , Tweaking the environment, Environment
585 @subsection Variables removed from the environment
587 Some variables are removed from the environment which Become passes to a
588 program for security reasons:
595 These variables are used on various systems as a search path for shared
596 libraries. Clearly, by manipulating these search paths, an attacker could
597 replace a standard shared library with one of his own.
600 The shell input field separator. Modifying this variable radically alters
601 the way shells parse their inputs. (In particular, consider the case where
602 @code{IFS} contains @samp{/}.)
606 Used by some shells: it contains the name of a file to read on every shell
611 I'm not really sure what's going on here, so I'll just have to bluff my way
612 through. I think that the following is more-or-less accurate, having browsed
613 a small amount of Kerberos-related documentation.
615 Contains the name of a Kerberos configuration file. By manipulating this
616 variable, an attacker could persuade a program to believe the wrong
617 authentication server.
620 Also note that the @code{PATH} variable is modified: any items which aren't
621 absolute pathnames are removed from the path. This check may become stricter
622 in future, although getting the balance between security and convenience is
623 particularly hard here.
627 @node Group permissions, X authority, Environment, Becoming someone else
628 @section How Become handles groups
630 As well as handling changes of user id, Become also changes group ids.
631 The exact changes Become makes are under user control.
634 * Primary group selection:: Setting the new primary group
635 * Subsidiary groups:: Setting subsidiary group memberships
639 @node Primary group selection, Subsidiary groups, Group permissions, Group permissions
640 @subsection Choosing a new primary group
642 By default, the primary group is chosen according to the login style
643 (@pxref{Login styles}): the `preserve' style retains the current primary
644 group, while `set-user' and `login' styles choose the target's primary group.
646 You can override Become's default choice using the @code{--group} (@code{-g}
650 become --group=@var{group} @dots{}
653 The chosen @var{group} may be either a group name or a numeric gid. The
654 group must be one of the following:
658 Your current primary group.
660 One of your current subsidiary groups.
662 The target user's primary group.
664 One of the target user's subsidiary groups.
667 Become will raise an error if this isn't the case.
670 @node Subsidiary groups, , Primary group selection, Group permissions
671 @subsection Handling subsidiary group memberships
673 Subsidiary group memberships are a powerful tool for managing permissions
674 under Unix. Traditionally, they tend to be tied to particular users. Become
675 tries to be sightly more intelligent about group memberships.
677 Become has a concept of @dfn{group style}, analogous to login style
678 (@pxref{Login styles}). The styles are selected by giving command line
684 Retain the existing group memberships; don't add any new groups.
687 @itemx --merge-groups
688 Merge group memberships of the target user with the exiting memberships.
691 @itemx --replace-groups
692 Replace the existing group memberships with the target user's memberships.
695 Again, the defaults are dependent on the chosen login style. Both `preserve'
696 and `set-user' merge group memberships; the `login' style replaces the set of
699 Note that you can do perverse things like replace all the subsidiary groups
700 but retain your primary group (using the @code{--group} option;
701 @pxref{Primary group selection}) if you like: Become won't try to stop you.
705 @node X authority, Running commands, Group permissions, Becoming someone else
706 @section Considerations for X authority
708 Other users can't read your @file{.Xauthority} file, if you have one. This
709 is as it should be: anyone who can read it can connect to your X server and
710 read or generate events. However, once you've become another user, you can't
711 open any X windows; this can be annoying if your favourite editor is X-based.
713 There are two basic approaches. Either you can send the shared account a
714 copy of your display's magic cookie, or you can retain permission to read the
717 Be aware that allowing a shared account to connect to your X display is a
721 * The user-group method:: A fairly secure way of handling X authority
722 * Using xauth:: A less secure method, which might be easier
726 @node The user-group method, Using xauth, X authority, X authority
727 @subsection The user-group method for handling X authority
729 This method is secure only if your site uses the `user-group' system. In
730 this system, each user is allocated a group containing only that user.
731 Usually this is made the user's default primary group, although that's not
734 When you start a new X session, ensure that your cookie file is owned by you
735 and your private group. Change the file's permissions so that it's group
736 readable. Finally, ensure that your private group is retained when you
737 become someone else (@pxref{Group permissions}), and that the
738 @code{XAUTHORITY} variable is set correctly.
740 Note that Unix's security mechanisms aren't designed to prevent processes
741 owned by the same user from interfering with each other. This method does
742 not provide complete security.
744 The following Bourne shell code in a @file{.xinitrc} should do most of the
748 XAUTHORITY="$HOME/.Xauthority"
750 chgrp mygroup $XAUTHORITY
751 chmod 640 $XAUTHORITY
755 In a C shell, this becomes
758 setenv XAUTHORITY $@{HOME@}/.Xauthority
759 chgrp mygroup $XAUTHORITY
760 chmod 640 $XAUTHORITY
763 The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
764 login styles, so this isn't a problem. You can now become other users, and
765 your X permissions will follow you around correctly.
767 It's probably worth noting that the @code{xauth} program annoyingly resets
768 the permissions on the cookie file every time it writes to it. This will be
769 particularly irritating if you use @code{ssh}'s X forwarding capabilities,
770 because every @code{ssh} connection will reset the permissions. You can deal
771 with this problem by putting a line
774 chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
778 in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or
781 if ($?XAUTHORITY) then
782 chmod 640 $XAUTHORITY >&/dev/null
784 chmod 640 $@{HOME@}/.Xauthority >&/dev/null
789 in @file{.cshrc} for C shell users.
792 @node Using xauth, , The user-group method, X authority
793 @subsection The @code{xauth} method for handling X authority
795 This method sends your X cookie to the shared account. It's therefore
796 intrinsically dangerous: you must be able to trust the other users of the
797 shared account not to take undue advantage of this situation.
799 The following (Bourne) shell snippet illustrates how you might send an
800 authorisation cookie to the shared account, to allow it to connect to your
804 if test -n "$BECOME_HOME"; then
805 XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
806 elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
808 :0.0) display=`hostname`:0.0 ;;
809 *) display="$DISPLAY" ;;
811 xauth extract - $display | \
812 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
813 done_xauth_cookie=yes; export done_xauth_cookie
817 The equivalent C shell code is
820 if ($?BECOME_HOME) then
821 setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
822 else if ($?DISPLAY && ! $?done_xauth_cookie) then
823 if ($DISPLAY == :0.0) then
824 set display="`hostname`:0.0"
826 set display="$DISPLAY"
828 xauth extract - $display | \
829 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
837 If the variable @code{BECOME_HOME} is set, then we're probably really someone
838 else, so point to the shared account's authority file.
841 Otherwise, check to see whether we have a display, and the authorisation has
842 not already been sent. If this is so, resolve a local display name into a
843 remote one (just in case) and then send it to the shared account.
848 @node Running commands, , X authority, Becoming someone else
849 @section Executing specific commands
851 As well as starting shells, Become can run single commands. This can be
856 It enables Become to be used in scripts.
859 It allows access to shared accounts to be controlled on the basis of the
863 To run a command as another user, say:
866 become @var{user} @var{command} [@var{argument}@dots{}]
869 If the request is granted, Become runs @var{command}, passing it any
870 arguments following the command name. Become doesn't run a shell, so there's
871 no extra escaping which needs to be done.
873 If you really want to run a shell command as another user, you can use the
877 become @var{user} -c @var{shell-command}
880 This is exactly equivalent to
883 become @var{user} /bin/sh -c @var{shell-command}
886 in every way. In particular, you must have permission to run @file{/bin/sh}
887 as @var{user} for it to work: Become doesn't attempt to interpret the shell
888 command in any way. Also note that Become always uses the Bourne shell,
889 regardless of your current shell preference, or @var{user}'s default shell.
890 (This is done to provide a stable programming interface which works
891 irrespective of changes to the shared account's configuration.)
894 @c --------------------------------------------------------------------------
895 @node Administering Become, Invoking Become, Becoming someone else, Top
896 @chapter Become administration
899 This chapter will explain how Become is administrated and maintained.
902 * Configuration files:: Overview of Become's configuration files
903 * Standalone or networked:: The two main types of Become installations
904 * The configuration file:: How to define who's allowed to do what
905 * Networked configuration:: Considerations for networked installations
910 @node Configuration files, Standalone or networked, Administering Become, Administering Become
911 @section Configuration files
913 Become keeps its configuration and administrative files in a directory
914 usually named @file{/etc/become}, although this can be changed with the
915 @code{--with-etcdir} option to the configuration script when you build
918 Not all of the files are needed on all machines.
922 The main configuration file, containing a description of which users are
923 allowed to become which other users, where, and what they're allowed to run
924 when they get there. Only needed on servers or standalone machines.
927 A list of servers to contact. Only needed on client machines.
930 The signing key to use when sending requests to servers. Needed on servers,
931 but not on standalone machines.
934 The verification keys to use when checking server responses. Needed on
935 clients, but not on standalone machines.
938 The process id of the server. Created automatically by Become's server when
943 @node Standalone or networked, The configuration file, Configuration files, Administering Become
944 @section Installation types
947 Become can be installed in two different ways, depending on how you want to
952 In a @dfn{standalone} installation, each Become request is dealt with
953 locally: the program reads the configuration file, and decides whether it
954 should grant or deny permission.
956 Standalone installations don't depend on servers being available, or even on
957 the existence of a network. They're useful for small sites, or sites with a
958 small number of users. The disadvantages are that reading the configuration
959 file takes a while, so the program doesn't feel as responsive as it should,
960 and ensuring that all the hosts' configuration files are synchronised becomes
961 difficult when you have lots of machines.
964 In a @dfn{network} installation, any Become requests are sent on to a
965 collection of servers. The servers analyse the request and send a reply back
966 which either authorises or forbids access.
968 A networked installation clearly depends on the servers' reliability. The
969 client reacts only to the first reply it receives, so as long as there is one
970 server running, everything should continue as normal.
972 A networked installation is useful when you have a large number of client
973 machines, particularly ones which may not be awake all the time. The full
974 configuration file only needs to be installed on a small number of servers;
975 the clients require only a list of server machines to contact, and an
976 encryption key to use.
981 @node The configuration file, Networked configuration, Standalone or networked, Administering Become
982 @section The configuration file
984 The main configuration file, usually called @file{/etc/become/become.conf},
985 contains all the rules which Become uses to decide whether to grant or deny
986 requests. It may also contain additional information for the benefit of
987 Become daemons, if you're using a networked installation.
990 * Requests and rules:: How the configuration file works
991 * Basic syntax:: Quick overview of Become's syntax
992 * Classes:: Defining classes of things
993 * Predefined classes:: Become predefines some (maybe) useful classes
994 * Allow statements:: Allow users to become other users
995 * Other statements:: Some other useful statements
996 * Example configuration file:: An example, showing a few features.
997 * Checking and querying:: Checking and querying configuration files
998 * Complete grammar:: Complete grammar for Become config files
1002 @node Requests and rules, Basic syntax, The configuration file, The configuration file
1003 @subsection Requests and rules
1005 Become looks at four pieces of information when it's analysing a request:
1009 the user's current identity;
1011 the identity the user wishes to assume;
1013 the host which generated the request; and
1015 the command the user wishes to run.
1018 Each of these pieces of information is looked at when Become decides whether
1019 to honour a request.
1021 The configuration file's main purpose is to describe the conditions under
1022 which Become should honour a request. These conditions are described by a
1023 number of @emph{rules}. A rule consists of two lists of users (called `from'
1024 and `to'), a list of hosts, and a list of commands. A rule matches a request
1029 the user's current identity is in the rule's `from' list;
1031 the target user's identity is in the rule's `to' list;
1033 the host is in the rule's host list; and
1035 the command to be run is in the rule's command list.
1038 A request is honoured if there is a rule which matches the request.
1041 @node Basic syntax, Classes, Requests and rules, The configuration file
1042 @subsection Basic configuration file syntax
1044 The configuration file consists of a sequence of statements, each terminated
1047 Comments begin with a @samp{#} character, and continue to the end of the
1048 line. This is the only time newlines behave specially: newlines behave just
1049 like any other whitespace characters within statements.
1051 Strings are enclosed in double-quote characters (@samp{"}). Within a string,
1052 a backslash causes the following character to be treated literally, whatever
1053 it may be (including quotes, backslashes and newlines).
1055 Names begin with an alphabetic character or an underscore, and consist of
1056 letters, digits and underscores.
1059 @node Classes, Predefined classes, Basic syntax, The configuration file
1062 A @dfn{class} in Become is a set of users, hosts or commands. You can define
1063 and name your own classes using statements of the form:
1066 user @var{name} = @var{class-expr} ;
1067 command @var{name} = @var{class-expr} ;
1068 host @var{name} = @var{class-expr} ;
1071 A @var{class-expr} is an expression defining a class. You can build a
1072 complex class out of simple classes using the operators (in ascending
1073 precedence order) @samp{,}, @samp{-}, @samp{|} and @samp{&}, which represent
1074 the set options `union', `subtraction', `union' (again!), and `intersection'.
1075 Subexpressions can be parenthesised to override the default precedence.
1076 Once a class name has been defined, as shown above, it can be used in
1077 subsequent class expressions.
1079 A single user may be designated by either a user name (in quotes) or an
1080 integer uid. Commands and hosts may be designated by quoted strings which
1081 may contain wildcards. Host strings are matched against both numeric (dotted
1082 quad) IP addresses and the reverse-resolved hostname. Command strings are
1083 matched against the absolute pathname of the command the user wants to
1088 @node Predefined classes, Allow statements, Classes, The configuration file
1089 @subsection Predefined classes
1091 In an attempt to make life a bit easier, Become creates a collection of
1094 The standard classes @code{all} and @code{none} match anything and nothing
1095 respectively. The @code{all} class is useful in some contexts: it gives you
1096 a way of saying `everything except@dots{}', for example:
1099 user MUNDANES = all - SYSHACKS;
1103 The @code{none} class is provided because it's needed internally anyway and
1104 someone might come up with a use for it.
1106 Become also defines some other classes:
1110 For each username @var{user}, Become adds a class called @samp{@var{user}}
1111 which matches just that user.
1114 For each group name @var{group}, Become creates a class called
1115 @samp{@var{group}} which matches any user who is a member of that group.
1117 @item For each netgroup @var{netgroup}, Become creates two classes:
1118 @samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
1119 @samp{h_@var{netgroup}} which matches any host listed in the netgroup.
1122 If a name is used for both a user @emph{and} a group, then corresponding
1123 class ends up containing the user together with all of the group members.
1124 For this reason, it's probably better to use the predefined classes for
1125 groups rather than individual users -- use quoted user names for individual
1128 Note that users and groups are read using the standard @code{get*ent} calls
1129 @emph{and} directly from the NIS server (if there is one). The idea here is
1130 that a Become server can be run on a machine which allows restricted logins.
1131 It still needs to know about all the users known to the outside world.
1133 Netgroups are read only from the NIS servers. In particular, although GNU
1134 systems allow netgroup databases to be stored in local files, Become won't
1135 read them because there's no defined interface for enumerating netgroups.
1138 @node Allow statements, Other statements, Predefined classes, The configuration file
1139 @subsection Allow statements
1141 The @code{allow} statement defines the rules Become uses when deciding
1142 whether to grant a request; see @ref{Requests and rules}.
1145 allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
1148 (The @var{host-class} is optional, but must be enclosed in square brackets if
1151 The four classes in an allow statement are called, respectively, the `host',
1152 the `to-user', the `from-user' and the `command'. Any of the four classes
1153 may be omitted, and an omitted class defaults to `all'.
1155 When a request is received, Become checks the fields in the request against
1156 the classes in each allow statement of the configuration file. If a
1157 statement matches, the request is granted; if there are no full matches,
1158 the request is denied.
1161 @node Other statements, Example configuration file, Allow statements, The configuration file
1162 @subsection Other statements
1164 Two other statement types are defined. They only have an effect on Become in
1169 keyfile @var{key-file} ;
1173 The @code{port} statement specifies the port to which the server should
1174 listen; the @var{port} may be be an integer or a quoted service name. The
1175 @code{keyfile} statement instructs Become to use the key from the file named
1176 @var{key-file}, which must be a quoted string.
1179 @node Example configuration file, Checking and querying, Other statements, The configuration file
1180 @subsection An example configuration file
1186 # Example configuration file
1189 allow wheel -> "root";
1191 user NEWS = "fred", "jim";
1192 allow NEWS -> "news";
1194 user HTTP = "jim", "bob";
1195 allow ["www.somewhere.com"]
1196 HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
1200 @node Checking and querying, Complete grammar, Example configuration file, The configuration file
1201 @subsection Checking and querying the configuration file
1203 At a reasonably sized site, Become configuration files can get rather large,
1204 and becomes tricky to work out exactly who's allowed to do what and where.
1206 The @code{bcquery} tool provided allows Become configuration files to be
1207 verified and queried. It can be used to ensure that a file is syntactically
1208 correct before it is deployed, or to enquire about privileges granted.
1211 * Verifying config files:: Checking a configuration file is correct
1212 * Querying config files:: Asking questions about privileges
1213 * Output formats:: Different ways of formatting output
1214 * Restricting output:: Being selective about what gets output
1215 * bcquery reference:: Complete command line reference
1218 @node Verifying config files, Querying config files, Checking and querying, Checking and querying
1219 @subsubsection Verifying configuration files
1221 A common use of @code{bcquery} is to ensure that a configuration file is
1222 actually valid. The command
1225 bcquery [-file @var{file}] -check
1229 verifies that a configuration file conforms to Become's expectations. If
1230 there are any errors in @var{file}, they are reported, and @code{bcquery}
1231 will return a nonzero exit code.
1233 If no @var{file} is specified, @code{bcquery} will read the configuration
1234 file which Become itself reads by default, usually
1235 @code{/etc/become/become.conf}.
1238 @node Querying config files, Output formats, Verifying config files, Checking and querying
1239 @subsubsection Querying configuration files
1241 The @code{bcquery} program will list all rules which match a selected request
1242 pattern. For example, you can display all rules which allow a particular
1243 user to change identity, or all rules which allow people to assume root
1244 privileges on a particular host.
1247 bcquery [-file @var{file}] @var{query}
1250 The following simple queries are supported:
1253 @item @code{-from} @var{user}
1254 Matches any rule containing @var{user} in its `from' list.
1255 @item @code{-to} @var{user}
1256 Matches any rule containing @var{user} in its `to' list.
1257 @item @code{-host} @var{host}
1258 Matches any rule containing @var{host} in its host list.
1259 @item @code{-command} @var{cmd}
1260 Matches any rule containing @var{cmd} in its `command' list.
1264 Simple queries can be combined using the following operators:
1267 @item @var{query-a} @code{-or} @var{query-b}
1268 Matches a rule matched by either @var{query-a} or @var{query-b}.
1269 @item @var{query-a} @code{-and} @var{query-b}
1270 Matches a rule matched by both @var{query-a} and @var{query-b}.
1271 @item @code{-not} @var{query}
1272 Matches a rule which is not matched by @var{query}.
1273 @item @code{(} @var{query} @code{)}
1274 Matches a rule matched by @var{query} (overrides default precedence).
1277 The @code{-and}, @code{-or} and @code{-not} operators may be written
1278 @code{&}, @code{|} and @code{!} respectively, if you prefer, and the
1279 @code{-and} operator is optional. These characters (and the parentheses
1280 @code{(} and @code{)}) may need to be quoted to prevent interpretation by the
1283 Some examples may explain what's going on:
1286 @item bcquery -from hacker
1287 Displays all rules applying to user `hacker'.
1288 @item bcquery -host somehost -to root
1289 Displays rules allowing people to become root on @code{somehost}.
1293 @node Output formats, Restricting output, Querying config files, Checking and querying
1294 @subsubsection Output formats
1296 The @code{bcquery} program has two distinct output formats: `rows' and
1299 The `columns' format is probably the simpler to understand, and certainly the
1300 easier to read. Each matching record is displayed with the lists of users,
1301 hosts and commands in columns. A query on the example configuration file
1302 (@pxref{Example configuration file}) is shown below:
1305 FROM TO HOST COMMAND
1307 frankie root ALL ALL
1313 jim httpd www.somewhere.com /bin/kill
1314 bob /etc/init.d/httpd
1318 The `columns' format can only show simple lists. A more complex class
1319 definition will show up as @samp{<complex>} in a `columns' format listing.
1321 The `rows' format is capable of displaying classes in their full generality,
1322 but is harder to parse and read. It displays each list in the form of an
1323 expression, in more or less the same syntax as a class definition
1326 The default behaviour is to use `columns' format where possible, or `rows'
1327 format if some of the lists are too complex to be represented in columns.
1328 You can select a format explicitly using the @code{-columns} or @code{-rows}
1329 options, which is useful if you're trying to parse the output of
1330 @code{bcquery} with a script.
1333 @node Restricting output, bcquery reference, Output formats, Checking and querying
1334 @subsubsection Restricting output
1336 It's also possible to suppress bits of information about each matched rule.
1337 For example, you can show only the `from' list, or just the `to' and `host'
1338 lists. This is done with the @code{-output} option.
1340 Each list is given a letter; the `from' list is called @samp{f}, the `to'
1341 list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
1342 select which lists are displayed by giving the corresponding letters (the
1343 order isn't important). You can also turn individual lists on or off by
1344 preceding the characters with @samp{+} or @samp{-} characters. If you start
1345 with a @samp{+} or @samp{-}, then the last-set selection (or the initial
1346 default of all-lists-enabled) is modified.
1348 For example, @samp{-output ftc} shows only the `from', `to' and `command'
1349 lists. This could be written @samp{-output -h} too, to turn the hosts list
1352 This option is mainly useful with the `columns' output format (@pxref{Output
1353 formats}) to save scripts having to select columns out themselves.
1356 @node bcquery reference, , Restricting output, Checking and querying
1357 @subsubsection @code{bcquery} options summary
1360 bcquery [@var{option}@dots{}] [@var{query}]
1363 The @var{option}s available are:
1367 Displays a summary of the available options, and exits.
1369 @item @code{-file} @var{file}
1370 Read @var{file}, rather than the compiled-in default (usually
1371 @file{/etc/become/become.conf}).
1374 Don't read a configuration file. Instead, display the query tree parsed from
1375 the command line. This is a debugging feature.
1378 Don't attempt to output any rules. Instead, just check the configuration
1381 @item @code{-output} @var{spec}
1382 Selects which columns are to be displayed for each matching rule.
1383 For full details, see @ref{Restricting output}.
1385 @item @code{-columns}
1387 Forces `columns' or `rows' output format. @xref{Output formats}.
1389 @item @code{-nohead}
1390 Suppress the header line at the top of the output in `columns' mode. Makes
1391 the output more amenable to automatic processing (but harder to read).
1393 @item @code{-from} @var{user}
1394 @itemx @code{-to} @var{user}
1395 @itemx @code{-host} @var{hostname}
1396 @itemx @code{-command} @var{cmd}
1397 Simple queries for selecting rules. @xref{Querying config files}.
1402 Operators for combining queries into something useful. @xref{Querying config
1407 @node Complete grammar, , Checking and querying, The configuration file
1408 @subsection Complete grammar for configuration files
1411 @var{file} ::= @var{file} @var{statement}
1413 @var{statement} ::= @var{class-def}
1418 @var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
1419 | @samp{command} @var{name} = @var{class-expr} @samp{;}
1420 | @samp{host} @var{name} = @var{class-expr} @samp{;}
1422 @var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
1423 @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}
1425 @var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
1428 @var{opt-user-spec} ::= @var{class-expr}
1431 @var{opt-command-spec} ::= @samp{:} @var{class-expr}
1434 @var{port-spec} ::= @samp{port} @var{integer} @samp{;}
1435 | @samp{port} @var{string} @samp{;}
1437 @var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}
1439 @var{class-expr} ::= @var{class-diff-expr}
1440 | @var{class-expr} @samp{,} @var{class-diff-expr}
1442 @var{class-diff-expr} ::= @var{class-isect-expr}
1443 | @var{class-diff-expr} @samp{-} @var{class-union-expr}
1445 @var{class-union-expr} ::= @var{class-isect-expr}
1446 | @var{class-union-expr} @samp{|} @var{class-isect-expr}
1448 @var{class-isect-expr} ::= @var{class-primary}
1449 | @var{class-isect-expr} @samp{&} @var{class-primary}
1451 @var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
1455 @var{integer} ::= one or more digits (@samp{0}--@samp{9})
1457 @var{name} ::= an alphabetic character or underscore, followed by zero or
1458 more alphanumeric characters or underscores
1460 @var{string} ::= @samp{"} @var{string-chars} @samp{"}
1462 @var{string-chars} ::= @var{string-chars} @var{string-char}
1465 @var{string-char} ::= a @samp{\} followed by any character
1466 | any character other than @samp{"}, @samp{\} or newline
1473 @node Networked configuration, , The configuration file, Administering Become
1474 @section Networked configuration
1476 If you're planning to use Become in a standalone way, you can skip this
1480 * Choosing servers:: Which servers Become tries to talk to
1481 * Setting up keys:: How to generate keys for Become
1482 * Issuing a new key:: How to issue new keys without disruption
1486 @node Choosing servers, Setting up keys, Networked configuration, Networked configuration
1487 @subsection Choosing servers
1489 Become notices that it's meant to send requests to a server if it finds a
1490 @file{become.server} file. This file contains entries of the form
1493 @var{host} [: @var{port}]
1496 If the @var{port} is omitted, Become chooses a port by looking at the
1497 services database for a service which matches the name by which Become was
1498 invoked: normally this will be @samp{become}.
1500 Become sends a request to all of the servers and believes the first valid
1501 reply it receives. Since servers ignore requests they believe to be invalid,
1502 this enables you to change Become's key without disrupting service
1503 (@pxref{Issuing a new key}).
1505 If you're using NIS, you should try to ensure that Become servers runs only
1506 on NIS servers; the NIS master is probably a good choice.
1508 Become isn't particularly processor-intensive, and doesn't seem to require
1512 @node Setting up keys, Issuing a new key, Choosing servers, Networked configuration
1513 @subsection Setting up keys
1515 Communication between Become clients and the server is encrypted to ensure
1516 that it's not feasible to gain unauthorised privilege by subverting the
1517 network. Become uses the DSA algorithm to ensure authenticity of replies.
1519 Each client machine, and the server, must have a copy of the same key. The
1520 key is usually stored in @file{/etc/become/become.key}. Become's keys are
1523 The key file can be generated using Catacomb's @code{key} program. The
1527 key -k /etc/become/become.key add -adsa become-dsa
1528 key -k /etc/become/become.key extract -f -secret /etc/become/become.pubkey
1532 will generate a suitable DSA key, and extract the public part. You should
1533 install the public key on all of your client computers, writable only by
1534 root. The private key should be only on the server, and readable or writable
1537 If you have multiple servers, they can all have different private keys.
1538 You'll need to put all of the public keys in the
1539 @file{/etc/become/become.pubkey} file.
1542 @node Issuing a new key, , Setting up keys, Networked configuration
1543 @subsection Issuing a new key
1545 When you're sending out a new key, you run a risk of disrupting service. The
1546 server reads a new key; the clients still have the old one.
1548 We used to recommend running two servers. Now, however, you can generate the
1549 new key, install the new public key on the clients in addition to the old
1550 one, and then install the new private key on the server. The clients try all
1551 valid public keys when attempting to authenticate a response, so this
1555 @c --------------------------------------------------------------------------
1556 @node Invoking Become, , Administering Become, Top
1557 @chapter Invoking Become
1560 This chapter provides an exhaustive description of Become's command line
1561 options, organised in a reference-manual sort of way.
1564 * Becoming another user:: Options for becoming another user
1565 * Starting Become daemons:: Options for starting Become daemons
1566 * Debugging options:: Options to use when Become goes wrong
1571 @node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
1572 @section Becoming another user
1574 @subsection Synopsis
1577 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
1580 Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
1581 order you like; the important thing is that all of them appear before the
1587 The @var{option}s appropriate for this mode are as follows:
1592 Display a (fairly verbose) help message describing the various command line
1593 options and exits successfully.
1597 Display a terse summary of the command line options and exits successfully.
1601 Display's Become's version number and exits successfully.
1604 @item --preserve-environment
1605 Selects the `preserve' login style (@pxref{The preserve style}). All
1606 environment variables are preserved. The default command is the current
1607 user's own shell. The default primary group becomes the current primary
1608 group; the default group style is set to `merge'.
1613 Selects the `set-user' login style (@pxref{The set-user style}). Most
1614 environment variables are preserved, but @code{USER}, @code{LOGNAME},
1615 @code{HOME} and other user-specific variables are altered to reflect the
1616 target user's configuration. The default command is the target user's shell.
1617 The default primary group becomes the target user's primary group; the
1618 default group style is set to `merge'.
1622 Selects the `login' login style (@pxref{The login style}). The environment
1623 is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
1624 The default command is the target user's shell. The default primary group
1625 becomes the target user's primary group; the default group style is set to
1628 @item -g @var{group}
1629 @itemx --group=@var{group}
1630 Selects @var{group} as the primary group; it may be either a group name or a
1631 numeric group id. Note that @var{group} must be the primary group or
1632 a subsidiary group of either the current user or the target user.
1635 @itemx --keep-groups
1636 Selects the `keep' group style (@pxref{Subsidiary groups}). The current set
1637 of subsidiary group memberships are passed on unchanged.
1640 @itemx --merge-groups
1641 Selects the `merge' group style (@pxref{Subsidiary groups}). The current set
1642 of subsidiary group memberships are merged with the subsidiary groups of the
1646 @itemx --replace-groups
1647 Selects the `replace' group style (@pxref{Subsidiary groups}). The target
1648 user's subsidiary group memberships are passed on; the current subsidiary
1649 groups are discarded.
1651 @item -c @var{shell-cmd}
1652 @itemx --command=@var{shell-cmd}
1653 Sets the @var{command} and @var{argument}s to invoke
1654 @code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
1655 instead of just @code{exec}ing a program. Note that permissions are checked
1656 for executing the Bourne shell @code{/bin/sh}; the contents of the
1657 @var{shell-cmd} are not inspected.
1660 The @var{env-var} arguments fine-tune the environment passed to the command.
1661 Each @var{env-var} setting must be one of the following:
1664 @item @var{var}=@var{value}
1665 Assign the variable named @var{var} the value @var{value}. Protect the
1666 variable @var{var} from modifications by the login style.
1669 Protect the variable @var{var} from modifications by the login style, but
1670 don't change its value.
1673 Remove the variable @var{var} from the environment; do not pass it on.
1676 The @var{user} specifies the user as whom the @var{command} should be
1677 executed (i.e., the @dfn{target user}). It may be a user name or a numeric
1680 The @var{command} specifies a command to execute. If @var{command} does not
1681 contain a path, it is looked for using the current @code{PATH} environment
1682 variable. The resulting pathname is canonified if necessary, to produce an
1683 absolute pathname. Note that symbolic links are @emph{not} resolved -- this
1684 prevents an attack whereby a user could invoke a program, passing it an
1685 unusual @code{argv[0]} which might cause unusual behaviour.
1687 The @var{command} name is used both as the command to execute and passed to
1688 the command as @code{argv[0]}. It is not possible to specify an alternative
1689 value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
1690 passed as @code{argv[1]} upwards.
1692 If no @var{command} is given, a shell is invoked; the particulars of the
1693 shell are determined by the login style (see above).
1695 The @var{command} is executed as follows:
1699 The subsidiary groups are chosen as determined by the group style.
1701 The real and effective gids are set.
1703 The real and effective uids are set.
1705 The @var{command} is called using the standard @code{execve} system call.
1710 @node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
1711 @section Starting Become daemons
1713 @subsection Synopsis
1716 become --daemon [@var{option}@dots{}]
1722 The following options are appropriate to this mode:
1727 Display a (fairly verbose) help message describing the various command line
1728 options and exits successfully.
1732 Display a terse summary of the command line options and exits successfully.
1736 Display's Become's version number and exits successfully.
1740 Start a Become server, instead of processing a request. Become will read its
1741 command line options, read in the configuration file (and verify that it's
1742 correct) and then fork into the background to wait for incoming requests.
1743 Become relinquishes all setuid privileges (by setting all uids to the real
1744 uid) when it enters daemon mode. It is therefore only really useful to run a
1745 daemon as the superuser.
1748 @itemx --port=@var{port}
1749 Listen for requests on @var{port}. This option is overridden by the
1750 @code{port} option in the configuration file.
1753 @itemx --config-file=@var{file}
1754 Read configuration from @var{file}, instead of the default (set at
1755 compile time, usually @file{/etc/become/become.conf}).
1758 The syntax of the configuration file is described in @ref{The configuration
1762 @node Debugging options, , Starting Become daemons, Invoking Become
1763 @section Debugging options
1765 Some options are only useful when trying to find out why Become is
1766 misbehaving. Of course, this never happens, so here are the options which
1767 you won't need to use:
1770 @item -T[@var{file}]
1771 @itemx --trace[=@var{file}]
1772 Write trace information to @var{file} (or to standard output, if no
1773 @var{file} is specified). You must be able to create the file and open it
1776 @item -L[@var{feature}...]
1777 @itemx --trace-level[=@var{feature}]
1778 Selects which features Become ought to trace. Each feature is allocated a
1779 letter; simply string together the letters for the features you want to
1780 debug. The letters @samp{D} and @samp{A} stand respectively for `default'
1781 and `all' features; you can subtract from them by saying, for example,
1782 @samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
1783 The exact list of features supported at any one time can be listed by giving
1784 the @code{--trace-level} option without an argument.
1787 @itemx --impersonate=@var{user}
1788 Pretend to be @var{user} instead of yourself when the request is checked.
1789 This option can only be used if it wasn't disabled at compile-time and if
1790 Become is not running setuid. Even so, Become will only inform you of the
1791 outcome; it will not execute any commands.
1796 @c --------------------------------------------------------------------------
1798 @c --- No index yet ---
1800 @c @node Concept index, , Invoking Become, Top
1801 @c @unnumbered Concept index
1808 @c ----- That's all, folks --------------------------------------------------