1 \input texinfo @c -*-texinfo-*-
3 @c $Id: become.texi,v 1.7 2003/11/29 23:39:16 mdw Exp $
5 @c Documentation for `become'
10 @c ----- Revision history ---------------------------------------------------
12 @c $Log: become.texi,v $
13 @c Revision 1.7 2003/11/29 23:39:16 mdw
16 @c Revision 1.6 2003/10/26 11:57:46 mdw
17 @c Fix key reloading core dumps. Change advice on keys.
19 @c Revision 1.5 2003/10/12 00:14:49 mdw
20 @c Major overhaul. Now uses DSA signatures rather than the bogus symmetric
21 @c encrypt-and-hope thing. Integrated with mLib and Catacomb.
23 @c Revision 1.4 1998/04/23 13:16:14 mdw
24 @c Include `texinice' to produce decent printed output. Add documentation
25 @c for new `bcquery' program. Various fixes, including spelling mistakes,
26 @c and some factual inaccuracies.
28 @c Revision 1.3 1998/01/20 14:37:43 mdw
29 @c Fix typo. Short form of `--preserve' should be `-e', not `-p'.
31 @c Revision 1.2 1998/01/12 16:41:31 mdw
32 @c Tidying for new release versions. Fix copyright date.
34 @c Revision 1.1 1997/09/18 11:16:34 mdw
35 @c Brand new Texinfo manual, with wider scope than the original LaTeX one.
38 @c ----- Standard boilerplate -----------------------------------------------
41 @setfilename become.info
43 @setchapternewpage odd
53 @dircategory Administration tools
55 * Become: (become). Shared account administration tool
58 @c ----- Useful macros ------------------------------------------------------
62 @c ----- Copyright matters --------------------------------------------------
64 @c --- The `Info' version ---
68 This file documents Become version @value{version}.
70 Copyright (c) 1998 European Bioinformatics Institute.
72 Permission is granted to make and distribute verbatim copies of this
73 manual provided the copyright notice and this permission notice are
74 preserved on all copies.
77 Permission is granted to process this file through TeX and print the
78 results, provided the printed document carries a copying permission
79 notice identical to this one except for the removal of this paragraph
80 (this paragraph not being relevant to the printed manual).
83 Permission is granted to copy and distribute modified versions of this
84 manual under the conditions for verbatim copying, provided also that the
85 sections entitled `Copying' and `GNU General Public License' are
86 included exactly as in the original, and provided that the entire
87 resulting derived work is distributed under the terms of a permission
88 notice identical to this one.
90 Permission is granted to copy and distribute translations of this manual
91 into another language, under the above conditions for modified versions,
92 except that this permission notice may be stated in a translation
93 approved by the European Bioinformatics Institute.
97 @c --- Printed title page ---
101 @title The Become program
102 @subtitle Become version @value{version}
103 @author Mark Wooding @email{mdw@@ebi.ac.uk}
106 @vskip 0pt plus 1filll
108 Copyright @copyright{} 1998 European Bioinformatics Institute.
110 Permission is granted to make and distribute verbatim copies of this
111 manual provided the copyright notice and this permission notice are
112 preserved on all copies.
114 Permission is granted to copy and distribute modified versions of this
115 manual under the conditions for verbatim copying, provided also that the
116 sections entitled `Copying' and `GNU General Public License' are
117 included exactly as in the original, and provided that the entire
118 resulting derived work is distributed under the terms of a permission
119 notice identical to this one.
121 Permission is granted to copy and distribute translations of this manual
122 into another language, under the above conditions for modified versions,
123 except that this permission notice may be stated in a translation
124 approved by the European Bioinformatics Institute.
129 @c --------------------------------------------------------------------------
131 @node Top, Copying, (dir), (dir)
135 Become is a system for managing shared accounts. It allows users to
136 `become' other users in order to do useful work. It can be managed on a
137 central server (or a small number of central servers), or it can run
140 This file documents Become version @value{version}.
145 * Copying:: Your rights to distribute and modify
146 * Introduction:: A brief introduction to Become
147 * Becoming someone else:: How to become somebody else
148 * Administering Become:: How to maintain Become
149 * Invoking Become:: Reference to Become's command line options
152 --- The Detailed Node Listing ---
154 Becoming someone else
156 * Terminology:: Some important terms defined
157 * Environment:: Login styles and environment variables
158 * Group permissions:: How Become handles group permissions
159 * X authority:: Problems with X authority files
160 * Running commands:: Running commands other than a shell
162 How Become sets up the environment
164 * New environment variables:: Become adds some useful environment variables
165 * Login styles:: Choose how Become sets the environment
166 * Tweaking the environment:: Altering individual environment variables
167 * Removed variables:: Some environment variables aren't passed on
171 * The preserve style:: Preserve the current environment
172 * The set-user style:: Set user-specific variables (like @code{su})
173 * The login style:: Clear the environment (like @code{login})
175 How Become handles groups
177 * Primary group selection:: Setting the new primary group
178 * Subsidiary groups:: Setting subsidiary group memberships
180 Considerations for X authority
182 * The user-group method:: A fairly secure way of handling X authority
183 * Using xauth:: A less secure method, which might be easier
185 Become administration
187 * Configuration files:: Overview of Become's configuration files
188 * Standalone or networked:: The two main types of Become installations
189 * The configuration file:: How to define who's allowed to do what
190 * Networked configuration:: Considerations for networked installations
192 The configuration file
194 * Requests and rules:: How the configuration file works
195 * Basic syntax:: Quick overview of Become's syntax
196 * Classes:: Defining classes of things
197 * Predefined classes:: Become predefines some (maybe) useful classes
198 * Allow statements:: Allow users to become other users
199 * Other statements:: Some other useful statements
200 * Example configuration file:: An example, showing a few features.
201 * Checking and querying:: Checking and querying configuration files
202 * Complete grammar:: Complete grammar for Become config files
204 Checking and querying the configuration file
206 * Verifying config files:: Checking a configuration file is correct
207 * Querying config files:: Asking questions about privileges
208 * Output formats:: Different ways of formatting output
209 * Restricting output:: Being selective about what gets output
210 * bcquery reference:: Complete command line reference
212 Networked configuration
214 * Choosing servers:: Which servers Become tries to talk to
215 * Setting up keys:: How to generate keys for Become
216 * Issuing a new key:: How to issue new keys without disruption
220 * Becoming another user:: Options for becoming another user
221 * Starting Become daemons:: Options for starting Become daemons
222 * Debugging options:: Options to use when Become goes wrong
227 @c --------------------------------------------------------------------------
228 @node Copying, Introduction, Top, Top
229 @unnumbered The GNU General Public License
234 @c --------------------------------------------------------------------------
235 @node Introduction, Becoming someone else, Copying, Top
236 @unnumbered Introduction
239 It's often useful to be able to share accounts between a number of
240 users. For example, a group maintaining an externally visible service
241 need to be able to start and kill the server process. Giving such a
242 shared account a password is a fairly bad plan: such passwords tend not
243 to get changed very often, and they have a habit of spreading beyond the
244 group of legitimate users.
246 The Become program presented here offers a solution to the problems of
247 shared accounts. It allows the system administrator to define which
248 users are allowed access to which accounts, on which hosts, and to
249 execute which commands. Such shared accounts can then, in general, have
250 their passwords removed.
252 This coincidentally has another advantage: when `becoming' to a shared
253 account, a user can retain her@footnote{Or his. I'll choose one or the
254 other fairly randomly throughout this manual.} own environment, which
255 she's carefully crafted and honed over the years, rather then being
256 presented with some lowest-common-denominator setup which probably
257 doesn't even use the right shell.
259 The configuration file for Become can either be distributed to all the
260 various hosts in a network or a few carefully set up and secure servers
261 (@pxref{Standalone or networked}).
264 @c --------------------------------------------------------------------------
265 @node Becoming someone else, Administering Become, Introduction, Top
266 @chapter Becoming someone else
269 The simplest way to become someone else is to say
276 Become will check to see whether you're allowed to become @var{user}. If you
277 are, it starts a shell process with the user-id set to @var{user}. Any
278 commands you type are executed with the privileges of @var{user}.
280 The full invocation is slightly more complicated:
283 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
286 Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
287 order -- the important point is that all of them appear before the
288 @var{command}, if there is one.
291 * Terminology:: Some important terms defined
292 * Environment:: Login styles and environment variables
293 * Group permissions:: How Become handles group permissions
294 * X authority:: Problems with X authority files
295 * Running commands:: Running commands other than a shell
300 @node Terminology, Environment, Becoming someone else, Becoming someone else
303 The following terms get used quite a bit in the following text:
307 An invocation of Become, asking permission to become another user.
310 The (real) user id of the process which invoked Become; usually, this will be
314 The user whom you want to become, named in a request.
319 @node Environment, Group permissions, Terminology, Becoming someone else
320 @section How Become sets up the environment
322 There are thorny problems with handling the user's environment. It seems
323 that (the author's initial assessment notwithstanding) there is no single
324 best way of handling environment variables. As a result, Become can do just
325 about everything you might want it to. This gets slightly complicated.
326 Don't worry: it's not as hard as all that.
329 * New environment variables:: Become adds some useful environment variables
330 * Login styles:: Choose how Become sets the environment
331 * Tweaking the environment:: Altering individual environment variables
332 * Removed variables:: Some environment variables aren't passed on
336 @node New environment variables, Login styles, Environment, Environment
337 @subsection Environment variables created by Become
339 To help you (and, more importantly, your startup scripts) keep track of who
340 you are, and who you were originally, Become adds some variables to the
341 environment of any processes it starts.
345 The name of the target user (i.e., the user you are now). It might be useful
346 to test this value in shell startup scripts, for example.
349 The home directory of the target user. It can be handy to read startup and
350 other configuration files from here.
352 @item BECOME_OLD_USER
353 The name of the user who invoked Become.
355 @item BECOME_OLD_HOME
356 The home directory of the `old' user.
358 @item BECOME_ORIGINAL_USER
359 This is intended to be the name you logged in with. If it's unset, Become
360 sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
363 @item BECOME_ORIGINAL_HOME
364 This is intended to be the home directory you logged in with. If it's unset,
365 Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
369 Don't even think about relying on these variables as a form of
370 authentication. It won't work. They're provided only to help organise
375 @node Login styles, Tweaking the environment, New environment variables, Environment
376 @subsection Login styles
378 Originally, Become always tried to preserve your environment. There's a
379 rational explanation for this approach, which is given in the description of
380 the `preserve' style below. Unfortunately, not everyone liked this
381 approach. As a result, there's now a collection of different login styles.
383 Login styles are selected by giving command line arguments:
388 The original style: try to preserve the existing user's environment as much
393 Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
394 the target user rather than the old user. All other variables are preserved.
398 Attempts to make the `become' process as much like a real login as possible.
399 All variables not explicitly preserved are deleted, and a new environment is
400 built, reflecting the target user.
403 The various styles, and the reasons behind them, are described below.
406 * The preserve style:: Preserve the current environment
407 * The set-user style:: Set user-specific variables (like @code{su})
408 * The login style:: Clear the environment (like @code{login})
412 @node The preserve style, The set-user style, Login styles, Login styles
413 @subsubsection The `preserve' login style
415 You've spent many hours (days? weeks, even?) customising and honing your
416 startup files, learning how to use your shell, and tweaking your favourite
417 text editor until it's just the way you like it. So there can be few things
418 more annoying than logging into a shared account to find out that the shell's
419 wrong, your editor startup files are ignored, and nothing works quite the way
420 you'd like it to. Typically you can't change this without annoying the other
421 users: the result is a horrible compromise which dissatisfies everyone
424 The `preserve' style lets you take your standard environment with you when
425 you become someone else. It tries hard not to modify any environment
428 Become starts your standard shell. If you have an environment variable
429 @code{SHELL} defined, than this is executed. Otherwise, the shell specified
430 in your entry in the password file is used. (You must have permission to
431 execute whatever shell is chosen as the target user, or you'll just be given
434 Most programs look at environment variables in preference to looking up
435 entries in the password database; e.g., they tend to use @code{USER} or
436 @code{LOGNAME} for the user name, and @code{HOME} for your home directory.
437 As a result, most programs will continue to find their configuration files in
438 your home directory. Also, systems like RCS will use your real name, rather
439 than the name of the user that you have become.
441 To make best use of this login style, you may need to adjust your login
442 scripts to notice when @code{BECOME_USER} is someone else, and read in
443 appropriate definitions. For example, a `bash' user might say something like
444 this in her @file{.bashrc}:
447 if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
451 Similarly, a C shell user (either `tcsh' or `csh') might say something like
454 if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
457 (Note that plain Bourne shell users have a slight problem, because the Bourne
458 shell only reads configuration things on a login, not when a normal
459 interactive shell is started.)
462 @node The set-user style, The login style, The preserve style, Login styles
463 @subsubsection The `set-user' login style
465 The author sees the main use of Become as allowing a user to acquire the
466 privileges associated with a shared account without all the problems which
467 shared accounts usually cause. To the author's way of thinking, one of the
468 main problems is that your environment gets replaced by something alien and
469 wrong. People disagree with me over this point, and for this reason the
470 `set-user' style exists.
472 The objective of `set-user' style is to behave similarly to the standard
473 @code{su} command. Unless they've been preserved explicitly (@pxref{Tweaking
474 the environment}), `set-user' mode sets the following environment variables:
479 The name of the target user.
482 The home directory of the target user.
485 The target user's default shell
488 The result of this is that the shell will read the target user's
489 configuration files and present you with the environment set up there.
491 I can't think of this style as being anything other than a migration aid
492 while users are getting used to the freedom offered by the `preserve' style.
495 @node The login style, , The set-user style, Login styles
496 @subsubsection The `login' login style
498 The `login' style causes Become to attempt to emulate a full login. Become
499 will empty the environment of almost variables which aren't explicitly
500 preserved (@pxref{Tweaking the environment}). However, the following
501 variables are retained:
513 It will set the following variables:
518 The name of the target user.
521 The home directory of the target user.
524 The target user's default shell
527 An educated guess at where the target user's mailbox is.
530 By default, it runs the target user's shell, informing it that this is a
531 login by setting the first character of @code{argv[0]} to @samp{-}.
533 Become makes no entries in the @file{utmp} and @file{wtmp} files.
537 @node Tweaking the environment, Removed variables, Login styles, Environment
538 @subsection Tweaking individual environment variables
540 Become's login styles provide a sort of course-grained control over the
541 environment. Sometimes the control isn't fine enough. Become lets you tweak
542 individual variables: you can set, delete, or preserve named variables from
545 There are three different things you can do with environment variables:
549 Set a variable called @var{var} to a value @var{value}, by saying
552 @var{var}=@var{value}
556 The variable is preserved from automatic deletion by the login-style rules.
559 Delete a variable called @var{var} from the environment, by saying
566 Preserve a variable @var{var} from being deleted or modified by Become's
567 login-style rules, but not change its value, by saying
574 Just to try and make this slightly more sensible, here's an example. Suppose
575 I want my @code{XAUTHORITY} variable to be set when I become user `fred':
578 become XAUTHORITY=$HOME/.Xauthority fred
582 should do the job nicely. Similarly, if I want to log in as `bob', but don't
583 want my @code{EDITOR} variable to change:
586 become --login EDITOR! bob
590 (Of course, in this example, I'm at the mercy of Bob's shell init files as to
591 whether his choice of editor overrides mine.)
595 @node Removed variables, , Tweaking the environment, Environment
596 @subsection Variables removed from the environment
598 Some variables are removed from the environment which Become passes to a
599 program for security reasons:
606 These variables are used on various systems as a search path for shared
607 libraries. Clearly, by manipulating these search paths, an attacker could
608 replace a standard shared library with one of his own.
611 The shell input field separator. Modifying this variable radically alters
612 the way shells parse their inputs. (In particular, consider the case where
613 @code{IFS} contains @samp{/}.)
617 Used by some shells: it contains the name of a file to read on every shell
622 I'm not really sure what's going on here, so I'll just have to bluff my way
623 through. I think that the following is more-or-less accurate, having browsed
624 a small amount of Kerberos-related documentation.
626 Contains the name of a Kerberos configuration file. By manipulating this
627 variable, an attacker could persuade a program to believe the wrong
628 authentication server.
631 Also note that the @code{PATH} variable is modified: any items which aren't
632 absolute pathnames are removed from the path. This check may become stricter
633 in future, although getting the balance between security and convenience is
634 particularly hard here.
638 @node Group permissions, X authority, Environment, Becoming someone else
639 @section How Become handles groups
641 As well as handling changes of user id, Become also changes group ids.
642 The exact changes Become makes are under user control.
645 * Primary group selection:: Setting the new primary group
646 * Subsidiary groups:: Setting subsidiary group memberships
650 @node Primary group selection, Subsidiary groups, Group permissions, Group permissions
651 @subsection Choosing a new primary group
653 By default, the primary group is chosen according to the login style
654 (@pxref{Login styles}): the `preserve' style retains the current primary
655 group, while `set-user' and `login' styles choose the target's primary group.
657 You can override Become's default choice using the @code{--group} (@code{-g}
661 become --group=@var{group} @dots{}
664 The chosen @var{group} may be either a group name or a numeric gid. The
665 group must be one of the following:
669 Your current primary group.
671 One of your current subsidiary groups.
673 The target user's primary group.
675 One of the target user's subsidiary groups.
678 Become will raise an error if this isn't the case.
681 @node Subsidiary groups, , Primary group selection, Group permissions
682 @subsection Handling subsidiary group memberships
684 Subsidiary group memberships are a powerful tool for managing permissions
685 under Unix. Traditionally, they tend to be tied to particular users. Become
686 tries to be sightly more intelligent about group memberships.
688 Become has a concept of @dfn{group style}, analogous to login style
689 (@pxref{Login styles}). The styles are selected by giving command line
695 Retain the existing group memberships; don't add any new groups.
698 @itemx --merge-groups
699 Merge group memberships of the target user with the exiting memberships.
702 @itemx --replace-groups
703 Replace the existing group memberships with the target user's memberships.
706 Again, the defaults are dependent on the chosen login style. Both `preserve'
707 and `set-user' merge group memberships; the `login' style replaces the set of
710 Note that you can do perverse things like replace all the subsidiary groups
711 but retain your primary group (using the @code{--group} option;
712 @pxref{Primary group selection}) if you like: Become won't try to stop you.
716 @node X authority, Running commands, Group permissions, Becoming someone else
717 @section Considerations for X authority
719 Other users can't read your @file{.Xauthority} file, if you have one. This
720 is as it should be: anyone who can read it can connect to your X server and
721 read or generate events. However, once you've become another user, you can't
722 open any X windows; this can be annoying if your favourite editor is X-based.
724 There are two basic approaches. Either you can send the shared account a
725 copy of your display's magic cookie, or you can retain permission to read the
728 Be aware that allowing a shared account to connect to your X display is a
732 * The user-group method:: A fairly secure way of handling X authority
733 * Using xauth:: A less secure method, which might be easier
737 @node The user-group method, Using xauth, X authority, X authority
738 @subsection The user-group method for handling X authority
740 This method is secure only if your site uses the `user-group' system. In
741 this system, each user is allocated a group containing only that user.
742 Usually this is made the user's default primary group, although that's not
745 When you start a new X session, ensure that your cookie file is owned by you
746 and your private group. Change the file's permissions so that it's group
747 readable. Finally, ensure that your private group is retained when you
748 become someone else (@pxref{Group permissions}), and that the
749 @code{XAUTHORITY} variable is set correctly.
751 Note that Unix's security mechanisms aren't designed to prevent processes
752 owned by the same user from interfering with each other. This method does
753 not provide complete security.
755 The following Bourne shell code in a @file{.xinitrc} should do most of the
759 XAUTHORITY="$HOME/.Xauthority"
761 chgrp mygroup $XAUTHORITY
762 chmod 640 $XAUTHORITY
766 In a C shell, this becomes
769 setenv XAUTHORITY $@{HOME@}/.Xauthority
770 chgrp mygroup $XAUTHORITY
771 chmod 640 $XAUTHORITY
774 The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
775 login styles, so this isn't a problem. You can now become other users, and
776 your X permissions will follow you around correctly.
778 It's probably worth noting that the @code{xauth} program annoyingly resets
779 the permissions on the cookie file every time it writes to it. This will be
780 particularly irritating if you use @code{ssh}'s X forwarding capabilities,
781 because every @code{ssh} connection will reset the permissions. You can deal
782 with this problem by putting a line
785 chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
789 in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or
792 if ($?XAUTHORITY) then
793 chmod 640 $XAUTHORITY >&/dev/null
795 chmod 640 $@{HOME@}/.Xauthority >&/dev/null
800 in @file{.cshrc} for C shell users.
803 @node Using xauth, , The user-group method, X authority
804 @subsection The @code{xauth} method for handling X authority
806 This method sends your X cookie to the shared account. It's therefore
807 intrinsically dangerous: you must be able to trust the other users of the
808 shared account not to take undue advantage of this situation.
810 The following (Bourne) shell snippet illustrates how you might send an
811 authorisation cookie to the shared account, to allow it to connect to your
815 if test -n "$BECOME_HOME"; then
816 XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
817 elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
819 :0.0) display=`hostname`:0.0 ;;
820 *) display="$DISPLAY" ;;
822 xauth extract - $display | \
823 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
824 done_xauth_cookie=yes; export done_xauth_cookie
828 The equivalent C shell code is
831 if ($?BECOME_HOME) then
832 setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
833 else if ($?DISPLAY && ! $?done_xauth_cookie) then
834 if ($DISPLAY == :0.0) then
835 set display="`hostname`:0.0"
837 set display="$DISPLAY"
839 xauth extract - $display | \
840 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
848 If the variable @code{BECOME_HOME} is set, then we're probably really someone
849 else, so point to the shared account's authority file.
852 Otherwise, check to see whether we have a display, and the authorisation has
853 not already been sent. If this is so, resolve a local display name into a
854 remote one (just in case) and then send it to the shared account.
859 @node Running commands, , X authority, Becoming someone else
860 @section Executing specific commands
862 As well as starting shells, Become can run single commands. This can be
867 It enables Become to be used in scripts.
870 It allows access to shared accounts to be controlled on the basis of the
874 To run a command as another user, say:
877 become @var{user} @var{command} [@var{argument}@dots{}]
880 If the request is granted, Become runs @var{command}, passing it any
881 arguments following the command name. Become doesn't run a shell, so there's
882 no extra escaping which needs to be done.
884 If you really want to run a shell command as another user, you can use the
888 become @var{user} -c @var{shell-command}
891 This is exactly equivalent to
894 become @var{user} /bin/sh -c @var{shell-command}
897 in every way. In particular, you must have permission to run @file{/bin/sh}
898 as @var{user} for it to work: Become doesn't attempt to interpret the shell
899 command in any way. Also note that Become always uses the Bourne shell,
900 regardless of your current shell preference, or @var{user}'s default shell.
901 (This is done to provide a stable programming interface which works
902 irrespective of changes to the shared account's configuration.)
905 @c --------------------------------------------------------------------------
906 @node Administering Become, Invoking Become, Becoming someone else, Top
907 @chapter Become administration
910 This chapter will explain how Become is administrated and maintained.
913 * Configuration files:: Overview of Become's configuration files
914 * Standalone or networked:: The two main types of Become installations
915 * The configuration file:: How to define who's allowed to do what
916 * Networked configuration:: Considerations for networked installations
921 @node Configuration files, Standalone or networked, Administering Become, Administering Become
922 @section Configuration files
924 Become keeps its configuration and administrative files in a directory
925 usually named @file{/etc/become}, although this can be changed with the
926 @code{--with-etcdir} option to the configuration script when you build
929 Not all of the files are needed on all machines.
933 The main configuration file, containing a description of which users are
934 allowed to become which other users, where, and what they're allowed to run
935 when they get there. Only needed on servers or standalone machines.
938 A list of servers to contact. Only needed on client machines.
941 The signing key to use when sending requests to servers. Needed on servers,
942 but not on standalone machines.
945 The verification keys to use when checking server responses. Needed on
946 clients, but not on standalone machines.
949 The process id of the server. Created automatically by Become's server when
954 @node Standalone or networked, The configuration file, Configuration files, Administering Become
955 @section Installation types
958 Become can be installed in two different ways, depending on how you want to
963 In a @dfn{standalone} installation, each Become request is dealt with
964 locally: the program reads the configuration file, and decides whether it
965 should grant or deny permission.
967 Standalone installations don't depend on servers being available, or even on
968 the existence of a network. They're useful for small sites, or sites with a
969 small number of users. The disadvantages are that reading the configuration
970 file takes a while, so the program doesn't feel as responsive as it should,
971 and ensuring that all the hosts' configuration files are synchronised becomes
972 difficult when you have lots of machines.
975 In a @dfn{network} installation, any Become requests are sent on to a
976 collection of servers. The servers analyse the request and send a reply back
977 which either authorises or forbids access.
979 A networked installation clearly depends on the servers' reliability. The
980 client reacts only to the first reply it receives, so as long as there is one
981 server running, everything should continue as normal.
983 A networked installation is useful when you have a large number of client
984 machines, particularly ones which may not be awake all the time. The full
985 configuration file only needs to be installed on a small number of servers;
986 the clients require only a list of server machines to contact, and an
987 encryption key to use.
992 @node The configuration file, Networked configuration, Standalone or networked, Administering Become
993 @section The configuration file
995 The main configuration file, usually called @file{/etc/become/become.conf},
996 contains all the rules which Become uses to decide whether to grant or deny
997 requests. It may also contain additional information for the benefit of
998 Become daemons, if you're using a networked installation.
1001 * Requests and rules:: How the configuration file works
1002 * Basic syntax:: Quick overview of Become's syntax
1003 * Classes:: Defining classes of things
1004 * Predefined classes:: Become predefines some (maybe) useful classes
1005 * Allow statements:: Allow users to become other users
1006 * Other statements:: Some other useful statements
1007 * Example configuration file:: An example, showing a few features.
1008 * Checking and querying:: Checking and querying configuration files
1009 * Complete grammar:: Complete grammar for Become config files
1013 @node Requests and rules, Basic syntax, The configuration file, The configuration file
1014 @subsection Requests and rules
1016 Become looks at four pieces of information when it's analysing a request:
1020 the user's current identity;
1022 the identity the user wishes to assume;
1024 the host which generated the request; and
1026 the command the user wishes to run.
1029 Each of these pieces of information is looked at when Become decides whether
1030 to honour a request.
1032 The configuration file's main purpose is to describe the conditions under
1033 which Become should honour a request. These conditions are described by a
1034 number of @emph{rules}. A rule consists of two lists of users (called `from'
1035 and `to'), a list of hosts, and a list of commands. A rule matches a request
1040 the user's current identity is in the rule's `from' list;
1042 the target user's identity is in the rule's `to' list;
1044 the host is in the rule's host list; and
1046 the command to be run is in the rule's command list.
1049 A request is honoured if there is a rule which matches the request.
1052 @node Basic syntax, Classes, Requests and rules, The configuration file
1053 @subsection Basic configuration file syntax
1055 The configuration file consists of a sequence of statements, each terminated
1058 Comments begin with a @samp{#} character, and continue to the end of the
1059 line. This is the only time newlines behave specially: newlines behave just
1060 like any other whitespace characters within statements.
1062 Strings are enclosed in double-quote characters (@samp{"}). Within a string,
1063 a backslash causes the following character to be treated literally, whatever
1064 it may be (including quotes, backslashes and newlines).
1066 Names begin with an alphabetic character or an underscore, and consist of
1067 letters, digits and underscores.
1070 @node Classes, Predefined classes, Basic syntax, The configuration file
1073 A @dfn{class} in Become is a set of users, hosts or commands. You can define
1074 and name your own classes using statements of the form:
1077 user @var{name} = @var{class-expr} ;
1078 command @var{name} = @var{class-expr} ;
1079 host @var{name} = @var{class-expr} ;
1082 A @var{class-expr} is an expression defining a class. You can build a
1083 complex class out of simple classes using the operators (in ascending
1084 precedence order) @samp{,}, @samp{-}, @samp{|} and @samp{&}, which represent
1085 the set options `union', `subtraction', `union' (again!), and `intersection'.
1086 Subexpressions can be parenthesised to override the default precedence.
1087 Once a class name has been defined, as shown above, it can be used in
1088 subsequent class expressions.
1090 A single user may be designated by either a user name (in quotes) or an
1091 integer uid. Commands and hosts may be designated by quoted strings which
1092 may contain wildcards. Host strings are matched against both numeric (dotted
1093 quad) IP addresses and the reverse-resolved hostname. Command strings are
1094 matched against the absolute pathname of the command the user wants to
1099 @node Predefined classes, Allow statements, Classes, The configuration file
1100 @subsection Predefined classes
1102 In an attempt to make life a bit easier, Become creates a collection of
1105 The standard classes @code{all} and @code{none} match anything and nothing
1106 respectively. The @code{all} class is useful in some contexts: it gives you
1107 a way of saying `everything except@dots{}', for example:
1110 user MUNDANES = all - SYSHACKS;
1114 The @code{none} class is provided because it's needed internally anyway and
1115 someone might come up with a use for it.
1117 Become also defines some other classes:
1121 For each username @var{user}, Become adds a class called @samp{@var{user}}
1122 which matches just that user.
1125 For each group name @var{group}, Become creates a class called
1126 @samp{@var{group}} which matches any user who is a member of that group.
1128 @item For each netgroup @var{netgroup}, Become creates two classes:
1129 @samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
1130 @samp{h_@var{netgroup}} which matches any host listed in the netgroup.
1133 If a name is used for both a user @emph{and} a group, then corresponding
1134 class ends up containing the user together with all of the group members.
1135 For this reason, it's probably better to use the predefined classes for
1136 groups rather than individual users -- use quoted user names for individual
1139 Note that users and groups are read using the standard @code{get*ent} calls
1140 @emph{and} directly from the NIS server (if there is one). The idea here is
1141 that a Become server can be run on a machine which allows restricted logins.
1142 It still needs to know about all the users known to the outside world.
1144 Netgroups are read only from the NIS servers. In particular, although GNU
1145 systems allow netgroup databases to be stored in local files, Become won't
1146 read them because there's no defined interface for enumerating netgroups.
1149 @node Allow statements, Other statements, Predefined classes, The configuration file
1150 @subsection Allow statements
1152 The @code{allow} statement defines the rules Become uses when deciding
1153 whether to grant a request; see @ref{Requests and rules}.
1156 allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
1159 (The @var{host-class} is optional, but must be enclosed in square brackets if
1162 The four classes in an allow statement are called, respectively, the `host',
1163 the `to-user', the `from-user' and the `command'. Any of the four classes
1164 may be omitted, and an omitted class defaults to `all'.
1166 When a request is received, Become checks the fields in the request against
1167 the classes in each allow statement of the configuration file. If a
1168 statement matches, the request is granted; if there are no full matches,
1169 the request is denied.
1172 @node Other statements, Example configuration file, Allow statements, The configuration file
1173 @subsection Other statements
1175 Two other statement types are defined. They only have an effect on Become in
1180 keyfile @var{key-file} ;
1184 The @code{port} statement specifies the port to which the server should
1185 listen; the @var{port} may be be an integer or a quoted service name. The
1186 @code{keyfile} statement instructs Become to use the key from the file named
1187 @var{key-file}, which must be a quoted string.
1190 @node Example configuration file, Checking and querying, Other statements, The configuration file
1191 @subsection An example configuration file
1197 # Example configuration file
1200 allow wheel -> "root";
1202 user NEWS = "fred", "jim";
1203 allow NEWS -> "news";
1205 user HTTP = "jim", "bob";
1206 allow ["www.somewhere.com"]
1207 HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
1211 @node Checking and querying, Complete grammar, Example configuration file, The configuration file
1212 @subsection Checking and querying the configuration file
1214 At a reasonably sized site, Become configuration files can get rather large,
1215 and becomes tricky to work out exactly who's allowed to do what and where.
1217 The @code{bcquery} tool provided allows Become configuration files to be
1218 verified and queried. It can be used to ensure that a file is syntactically
1219 correct before it is deployed, or to enquire about privileges granted.
1222 * Verifying config files:: Checking a configuration file is correct
1223 * Querying config files:: Asking questions about privileges
1224 * Output formats:: Different ways of formatting output
1225 * Restricting output:: Being selective about what gets output
1226 * bcquery reference:: Complete command line reference
1229 @node Verifying config files, Querying config files, Checking and querying, Checking and querying
1230 @subsubsection Verifying configuration files
1232 A common use of @code{bcquery} is to ensure that a configuration file is
1233 actually valid. The command
1236 bcquery [-file @var{file}] -check
1240 verifies that a configuration file conforms to Become's expectations. If
1241 there are any errors in @var{file}, they are reported, and @code{bcquery}
1242 will return a nonzero exit code.
1244 If no @var{file} is specified, @code{bcquery} will read the configuration
1245 file which Become itself reads by default, usually
1246 @code{/etc/become/become.conf}.
1249 @node Querying config files, Output formats, Verifying config files, Checking and querying
1250 @subsubsection Querying configuration files
1252 The @code{bcquery} program will list all rules which match a selected request
1253 pattern. For example, you can display all rules which allow a particular
1254 user to change identity, or all rules which allow people to assume root
1255 privileges on a particular host.
1258 bcquery [-file @var{file}] @var{query}
1261 The following simple queries are supported:
1264 @item @code{-from} @var{user}
1265 Matches any rule containing @var{user} in its `from' list.
1266 @item @code{-to} @var{user}
1267 Matches any rule containing @var{user} in its `to' list.
1268 @item @code{-host} @var{host}
1269 Matches any rule containing @var{host} in its host list.
1270 @item @code{-command} @var{cmd}
1271 Matches any rule containing @var{cmd} in its `command' list.
1275 Simple queries can be combined using the following operators:
1278 @item @var{query-a} @code{-or} @var{query-b}
1279 Matches a rule matched by either @var{query-a} or @var{query-b}.
1280 @item @var{query-a} @code{-and} @var{query-b}
1281 Matches a rule matched by both @var{query-a} and @var{query-b}.
1282 @item @code{-not} @var{query}
1283 Matches a rule which is not matched by @var{query}.
1284 @item @code{(} @var{query} @code{)}
1285 Matches a rule matched by @var{query} (overrides default precedence).
1288 The @code{-and}, @code{-or} and @code{-not} operators may be written
1289 @code{&}, @code{|} and @code{!} respectively, if you prefer, and the
1290 @code{-and} operator is optional. These characters (and the parentheses
1291 @code{(} and @code{)}) may need to be quoted to prevent interpretation by the
1294 Some examples may explain what's going on:
1297 @item bcquery -from hacker
1298 Displays all rules applying to user `hacker'.
1299 @item bcquery -host somehost -to root
1300 Displays rules allowing people to become root on @code{somehost}.
1304 @node Output formats, Restricting output, Querying config files, Checking and querying
1305 @subsubsection Output formats
1307 The @code{bcquery} program has two distinct output formats: `rows' and
1310 The `columns' format is probably the simpler to understand, and certainly the
1311 easier to read. Each matching record is displayed with the lists of users,
1312 hosts and commands in columns. A query on the example configuration file
1313 (@pxref{Example configuration file}) is shown below:
1316 FROM TO HOST COMMAND
1318 frankie root ALL ALL
1324 jim httpd www.somewhere.com /bin/kill
1325 bob /etc/init.d/httpd
1329 The `columns' format can only show simple lists. A more complex class
1330 definition will show up as @samp{<complex>} in a `columns' format listing.
1332 The `rows' format is capable of displaying classes in their full generality,
1333 but is harder to parse and read. It displays each list in the form of an
1334 expression, in more or less the same syntax as a class definition
1337 The default behaviour is to use `columns' format where possible, or `rows'
1338 format if some of the lists are too complex to be represented in columns.
1339 You can select a format explicitly using the @code{-columns} or @code{-rows}
1340 options, which is useful if you're trying to parse the output of
1341 @code{bcquery} with a script.
1344 @node Restricting output, bcquery reference, Output formats, Checking and querying
1345 @subsubsection Restricting output
1347 It's also possible to suppress bits of information about each matched rule.
1348 For example, you can show only the `from' list, or just the `to' and `host'
1349 lists. This is done with the @code{-output} option.
1351 Each list is given a letter; the `from' list is called @samp{f}, the `to'
1352 list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
1353 select which lists are displayed by giving the corresponding letters (the
1354 order isn't important). You can also turn individual lists on or off by
1355 preceding the characters with @samp{+} or @samp{-} characters. If you start
1356 with a @samp{+} or @samp{-}, then the last-set selection (or the initial
1357 default of all-lists-enabled) is modified.
1359 For example, @samp{-output ftc} shows only the `from', `to' and `command'
1360 lists. This could be written @samp{-output -h} too, to turn the hosts list
1363 This option is mainly useful with the `columns' output format (@pxref{Output
1364 formats}) to save scripts having to select columns out themselves.
1367 @node bcquery reference, , Restricting output, Checking and querying
1368 @subsubsection @code{bcquery} options summary
1371 bcquery [@var{option}@dots{}] [@var{query}]
1374 The @var{option}s available are:
1378 Displays a summary of the available options, and exits.
1380 @item @code{-file} @var{file}
1381 Read @var{file}, rather than the compiled-in default (usually
1382 @file{/etc/become/become.conf}).
1385 Don't read a configuration file. Instead, display the query tree parsed from
1386 the command line. This is a debugging feature.
1389 Don't attempt to output any rules. Instead, just check the configuration
1392 @item @code{-output} @var{spec}
1393 Selects which columns are to be displayed for each matching rule.
1394 For full details, see @ref{Restricting output}.
1396 @item @code{-columns}
1398 Forces `columns' or `rows' output format. @xref{Output formats}.
1400 @item @code{-nohead}
1401 Suppress the header line at the top of the output in `columns' mode. Makes
1402 the output more amenable to automatic processing (but harder to read).
1404 @item @code{-from} @var{user}
1405 @itemx @code{-to} @var{user}
1406 @itemx @code{-host} @var{hostname}
1407 @itemx @code{-command} @var{cmd}
1408 Simple queries for selecting rules. @xref{Querying config files}.
1413 Operators for combining queries into something useful. @xref{Querying config
1418 @node Complete grammar, , Checking and querying, The configuration file
1419 @subsection Complete grammar for configuration files
1422 @var{file} ::= @var{file} @var{statement}
1424 @var{statement} ::= @var{class-def}
1429 @var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
1430 | @samp{command} @var{name} = @var{class-expr} @samp{;}
1431 | @samp{host} @var{name} = @var{class-expr} @samp{;}
1433 @var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
1434 @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}
1436 @var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
1439 @var{opt-user-spec} ::= @var{class-expr}
1442 @var{opt-command-spec} ::= @samp{:} @var{class-expr}
1445 @var{port-spec} ::= @samp{port} @var{integer} @samp{;}
1446 | @samp{port} @var{string} @samp{;}
1448 @var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}
1450 @var{class-expr} ::= @var{class-diff-expr}
1451 | @var{class-expr} @samp{,} @var{class-diff-expr}
1453 @var{class-diff-expr} ::= @var{class-isect-expr}
1454 | @var{class-diff-expr} @samp{-} @var{class-union-expr}
1456 @var{class-union-expr} ::= @var{class-isect-expr}
1457 | @var{class-union-expr} @samp{|} @var{class-isect-expr}
1459 @var{class-isect-expr} ::= @var{class-primary}
1460 | @var{class-isect-expr} @samp{&} @var{class-primary}
1462 @var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
1466 @var{integer} ::= one or more digits (@samp{0}--@samp{9})
1468 @var{name} ::= an alphabetic character or underscore, followed by zero or
1469 more alphanumeric characters or underscores
1471 @var{string} ::= @samp{"} @var{string-chars} @samp{"}
1473 @var{string-chars} ::= @var{string-chars} @var{string-char}
1476 @var{string-char} ::= a @samp{\} followed by any character
1477 | any character other than @samp{"}, @samp{\} or newline
1484 @node Networked configuration, , The configuration file, Administering Become
1485 @section Networked configuration
1487 If you're planning to use Become in a standalone way, you can skip this
1491 * Choosing servers:: Which servers Become tries to talk to
1492 * Setting up keys:: How to generate keys for Become
1493 * Issuing a new key:: How to issue new keys without disruption
1497 @node Choosing servers, Setting up keys, Networked configuration, Networked configuration
1498 @subsection Choosing servers
1500 Become notices that it's meant to send requests to a server if it finds a
1501 @file{become.server} file. This file contains entries of the form
1504 @var{host} [: @var{port}]
1507 If the @var{port} is omitted, Become chooses a port by looking at the
1508 services database for a service which matches the name by which Become was
1509 invoked: normally this will be @samp{become}.
1511 Become sends a request to all of the servers and believes the first valid
1512 reply it receives. Since servers ignore requests they believe to be invalid,
1513 this enables you to change Become's key without disrupting service
1514 (@pxref{Issuing a new key}).
1516 If you're using NIS, you should try to ensure that Become servers runs only
1517 on NIS servers; the NIS master is probably a good choice.
1519 Become isn't particularly processor-intensive, and doesn't seem to require
1523 @node Setting up keys, Issuing a new key, Choosing servers, Networked configuration
1524 @subsection Setting up keys
1526 Communication between Become clients and the server is encrypted to ensure
1527 that it's not feasible to gain unauthorised privilege by subverting the
1528 network. Become uses the DSA algorithm to ensure authenticity of replies.
1530 Each client machine, and the server, must have a copy of the same key. The
1531 key is usually stored in @file{/etc/become/become.key}. Become's keys are
1534 The key file can be generated using Catacomb's @code{key} program. The
1538 key -k /etc/become/become.key add -adsa -e"now + 1 year" become-dsa
1539 key -k /etc/become/become.key extract -f -secret /etc/become/become.pubkey
1543 will generate a suitable DSA key, and extract the public part. You should
1544 install the public key on all of your client computers, writable only by
1545 root. The private key should be only on the server, and readable or writable
1548 If you have multiple servers, they can all have different private keys.
1549 You'll need to put all of the public keys in the
1550 @file{/etc/become/become.pubkey} file.
1553 @node Issuing a new key, , Setting up keys, Networked configuration
1554 @subsection Issuing a new key
1556 When you're sending out a new key, you run a risk of disrupting service. The
1557 server reads a new key; the clients still have the old one.
1559 We used to recommend running two servers. Now, however, you can generate the
1560 new key, install the new public key on the clients in addition to the old
1561 one, and then install the new private key on the server. The clients try all
1562 valid public keys when attempting to authenticate a response, so this
1566 @c --------------------------------------------------------------------------
1567 @node Invoking Become, , Administering Become, Top
1568 @chapter Invoking Become
1571 This chapter provides an exhaustive description of Become's command line
1572 options, organised in a reference-manual sort of way.
1575 * Becoming another user:: Options for becoming another user
1576 * Starting Become daemons:: Options for starting Become daemons
1577 * Debugging options:: Options to use when Become goes wrong
1582 @node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
1583 @section Becoming another user
1585 @subsection Synopsis
1588 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
1591 Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
1592 order you like; the important thing is that all of them appear before the
1598 The @var{option}s appropriate for this mode are as follows:
1603 Display a (fairly verbose) help message describing the various command line
1604 options and exits successfully.
1608 Display a terse summary of the command line options and exits successfully.
1612 Display's Become's version number and exits successfully.
1615 @item --preserve-environment
1616 Selects the `preserve' login style (@pxref{The preserve style}). All
1617 environment variables are preserved. The default command is the current
1618 user's own shell. The default primary group becomes the current primary
1619 group; the default group style is set to `merge'.
1624 Selects the `set-user' login style (@pxref{The set-user style}). Most
1625 environment variables are preserved, but @code{USER}, @code{LOGNAME},
1626 @code{HOME} and other user-specific variables are altered to reflect the
1627 target user's configuration. The default command is the target user's shell.
1628 The default primary group becomes the target user's primary group; the
1629 default group style is set to `merge'.
1633 Selects the `login' login style (@pxref{The login style}). The environment
1634 is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
1635 The default command is the target user's shell. The default primary group
1636 becomes the target user's primary group; the default group style is set to
1639 @item -g @var{group}
1640 @itemx --group=@var{group}
1641 Selects @var{group} as the primary group; it may be either a group name or a
1642 numeric group id. Note that @var{group} must be the primary group or
1643 a subsidiary group of either the current user or the target user.
1646 @itemx --keep-groups
1647 Selects the `keep' group style (@pxref{Subsidiary groups}). The current set
1648 of subsidiary group memberships are passed on unchanged.
1651 @itemx --merge-groups
1652 Selects the `merge' group style (@pxref{Subsidiary groups}). The current set
1653 of subsidiary group memberships are merged with the subsidiary groups of the
1657 @itemx --replace-groups
1658 Selects the `replace' group style (@pxref{Subsidiary groups}). The target
1659 user's subsidiary group memberships are passed on; the current subsidiary
1660 groups are discarded.
1662 @item -c @var{shell-cmd}
1663 @itemx --command=@var{shell-cmd}
1664 Sets the @var{command} and @var{argument}s to invoke
1665 @code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
1666 instead of just @code{exec}ing a program. Note that permissions are checked
1667 for executing the Bourne shell @code{/bin/sh}; the contents of the
1668 @var{shell-cmd} are not inspected.
1671 The @var{env-var} arguments fine-tune the environment passed to the command.
1672 Each @var{env-var} setting must be one of the following:
1675 @item @var{var}=@var{value}
1676 Assign the variable named @var{var} the value @var{value}. Protect the
1677 variable @var{var} from modifications by the login style.
1680 Protect the variable @var{var} from modifications by the login style, but
1681 don't change its value.
1684 Remove the variable @var{var} from the environment; do not pass it on.
1687 The @var{user} specifies the user as whom the @var{command} should be
1688 executed (i.e., the @dfn{target user}). It may be a user name or a numeric
1691 The @var{command} specifies a command to execute. If @var{command} does not
1692 contain a path, it is looked for using the current @code{PATH} environment
1693 variable. The resulting pathname is canonified if necessary, to produce an
1694 absolute pathname. Note that symbolic links are @emph{not} resolved -- this
1695 prevents an attack whereby a user could invoke a program, passing it an
1696 unusual @code{argv[0]} which might cause unusual behaviour.
1698 The @var{command} name is used both as the command to execute and passed to
1699 the command as @code{argv[0]}. It is not possible to specify an alternative
1700 value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
1701 passed as @code{argv[1]} upwards.
1703 If no @var{command} is given, a shell is invoked; the particulars of the
1704 shell are determined by the login style (see above).
1706 The @var{command} is executed as follows:
1710 The subsidiary groups are chosen as determined by the group style.
1712 The real and effective gids are set.
1714 The real and effective uids are set.
1716 The @var{command} is called using the standard @code{execve} system call.
1721 @node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
1722 @section Starting Become daemons
1724 @subsection Synopsis
1727 become --daemon [@var{option}@dots{}]
1733 The following options are appropriate to this mode:
1738 Display a (fairly verbose) help message describing the various command line
1739 options and exits successfully.
1743 Display a terse summary of the command line options and exits successfully.
1747 Display's Become's version number and exits successfully.
1751 Start a Become server, instead of processing a request. Become will read its
1752 command line options, read in the configuration file (and verify that it's
1753 correct) and then fork into the background to wait for incoming requests.
1754 Become relinquishes all setuid privileges (by setting all uids to the real
1755 uid) when it enters daemon mode. It is therefore only really useful to run a
1756 daemon as the superuser.
1759 @itemx --port=@var{port}
1760 Listen for requests on @var{port}. This option is overridden by the
1761 @code{port} option in the configuration file.
1764 @itemx --config-file=@var{file}
1765 Read configuration from @var{file}, instead of the default (set at
1766 compile time, usually @file{/etc/become/become.conf}).
1769 The syntax of the configuration file is described in @ref{The configuration
1773 @node Debugging options, , Starting Become daemons, Invoking Become
1774 @section Debugging options
1776 Some options are only useful when trying to find out why Become is
1777 misbehaving. Of course, this never happens, so here are the options which
1778 you won't need to use:
1781 @item -T[@var{file}]
1782 @itemx --trace[=@var{file}]
1783 Write trace information to @var{file} (or to standard output, if no
1784 @var{file} is specified). You must be able to create the file and open it
1787 @item -L[@var{feature}...]
1788 @itemx --trace-level[=@var{feature}]
1789 Selects which features Become ought to trace. Each feature is allocated a
1790 letter; simply string together the letters for the features you want to
1791 debug. The letters @samp{D} and @samp{A} stand respectively for `default'
1792 and `all' features; you can subtract from them by saying, for example,
1793 @samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
1794 The exact list of features supported at any one time can be listed by giving
1795 the @code{--trace-level} option without an argument.
1798 @itemx --impersonate=@var{user}
1799 Pretend to be @var{user} instead of yourself when the request is checked.
1800 This option can only be used if it wasn't disabled at compile-time and if
1801 Become is not running setuid. Even so, Become will only inform you of the
1802 outcome; it will not execute any commands.
1807 @c --------------------------------------------------------------------------
1809 @c --- No index yet ---
1811 @c @node Concept index, , Invoking Become, Top
1812 @c @unnumbered Concept index
1819 @c ----- That's all, folks --------------------------------------------------