1 \input texinfo @c -*-texinfo-*-
3 @c $Id: become.texi,v 1.4 1998/04/23 13:16:14 mdw Exp $
5 @c Documentation for `become'
10 @c ----- Revision history ---------------------------------------------------
12 @c $Log: become.texi,v $
13 @c Revision 1.4 1998/04/23 13:16:14 mdw
14 @c Include `texinice' to produce decent printed output. Add documentation
15 @c for new `bcquery' program. Various fixes, including spelling mistakes,
16 @c and some factual inaccuracies.
18 @c Revision 1.3 1998/01/20 14:37:43 mdw
19 @c Fix typo. Short form of `--preserve' should be `-e', not `-p'.
21 @c Revision 1.2 1998/01/12 16:41:31 mdw
22 @c Tidying for new release versions. Fix copyright date.
24 @c Revision 1.1 1997/09/18 11:16:34 mdw
25 @c Brand new Texinfo manual, with wider scope than the original LaTeX one.
28 @c ----- Standard boilerplate -----------------------------------------------
31 @setfilename become.info
33 @setchapternewpage odd
43 @c ----- Useful macros ------------------------------------------------------
47 @c ----- Copyright matters --------------------------------------------------
49 @c --- The `Info' version ---
53 This file documents Become version @value{version}.
55 Copyright (c) 1998 European Bioinformatics Institute.
57 Permission is granted to make and distribute verbatim copies of this
58 manual provided the copyright notice and this permission notice are
59 preserved on all copies.
62 Permission is granted to process this file through TeX and print the
63 results, provided the printed document carries a copying permission
64 notice identical to this one except for the removal of this paragraph
65 (this paragraph not being relevant to the printed manual).
68 Permission is granted to copy and distribute modified versions of this
69 manual under the conditions for verbatim copying, provided also that the
70 sections entitled `Copying' and `GNU General Public License' are
71 included exactly as in the original, and provided that the entire
72 resulting derived work is distributed under the terms of a permission
73 notice identical to this one.
75 Permission is granted to copy and distribute translations of this manual
76 into another language, under the above conditions for modified versions,
77 except that this permission notice may be stated in a translation
78 approved by the European Bioinformatics Institute.
82 @c --- Printed title page ---
86 @title The Become program
87 @subtitle Become version @value{version}
88 @author Mark Wooding @email{mdw@@ebi.ac.uk}
91 @vskip 0pt plus 1filll
93 Copyright @copyright{} 1998 European Bioinformatics Institute.
95 Permission is granted to make and distribute verbatim copies of this
96 manual provided the copyright notice and this permission notice are
97 preserved on all copies.
99 Permission is granted to copy and distribute modified versions of this
100 manual under the conditions for verbatim copying, provided also that the
101 sections entitled `Copying' and `GNU General Public License' are
102 included exactly as in the original, and provided that the entire
103 resulting derived work is distributed under the terms of a permission
104 notice identical to this one.
106 Permission is granted to copy and distribute translations of this manual
107 into another language, under the above conditions for modified versions,
108 except that this permission notice may be stated in a translation
109 approved by the European Bioinformatics Institute.
114 @c --------------------------------------------------------------------------
116 @node Top, Copying, (dir), (dir)
120 Become is a system for managing shared accounts. It allows users to
121 `become' other users in order to do useful work. It can be managed on a
122 central server (or a small number of central servers), or it can run
125 This file documents Become version @value{version}.
130 * Copying:: Your rights to distribute and modify
131 * Introduction:: A brief introduction to Become
132 * Becoming someone else:: How to become somebody else
133 * Administering Become:: How to maintain Become
134 * Invoking Become:: Reference to Become's command line options
136 --- The Detailed Node Listing ---
138 Becoming someone else
140 * Terminology:: Some important terms defined
141 * Environment:: Login styles and environment variables
142 * Group permissions:: How Become handles group permissions
143 * X authority:: Problems with X authority files
144 * Running commands:: Running commands other than a shell
146 How Become sets up the environment
148 * New environment variables:: Become adds some useful environment variables
149 * Login styles:: Choose how Become sets the environment
150 * Tweaking the environment:: Altering individual environment variables
151 * Removed variables:: Some environment variables aren't passed on
155 * The preserve style:: Preserve the current environment
156 * The set-user style:: Set user-specific variables (like @code{su})
157 * The login style:: Clear the environment (like @code{login})
159 How Become handles groups
161 * Primary group selection:: Setting the new primary group
162 * Subsidiary groups:: Setting subsidiary group memberships
164 Considerations for X authority
166 * The user-group method:: A fairly secure way of handling X authority
167 * Using xauth:: A less secure method, which might be easier
169 Become administration
171 * Configuration files:: Overview of Become's configuration files
172 * Standalone or networked:: The two main types of Become installations
173 * The configuration file:: How to define who's allowed to do what
174 * Networked configuration:: Considerations for networked installations
176 The configuration file
178 * Requests and rules:: How the configuration file works
179 * Basic syntax:: Quick overview of Become's syntax
180 * Classes:: Defining classes of things
181 * Predefined classes:: Become predefines some (maybe) useful classes
182 * Allow statements:: Allow users to become other users
183 * Other statements:: Some other useful statements
184 * Example configuration file:: An example, showing a few features.
185 * Checking and querying:: Checking and querying configuration files
186 * Complete grammar:: Complete grammar for Become config files
188 Checking and querying the configuration file
190 * Verifying config files:: Checking a configuration file is correct
191 * Querying config files:: Asking questions about privileges
192 * Output formats:: Different ways of formatting output
193 * Restricting output:: Being selective about what gets output
194 * bcquery reference:: Complete command line reference
196 Networked configuration
198 * Choosing servers:: Which servers Become tries to talk to
199 * Setting up keys:: How to generate keys for Become
200 * Random number files:: Become keeps random number state around
201 * Issuing a new key:: How to issue new keys without disruption
205 * Invoking keygen:: How to use the @code{keygen} program
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
214 @c --------------------------------------------------------------------------
215 @node Copying, Introduction, Top, Top
216 @unnumbered The GNU General Public License
221 @c --------------------------------------------------------------------------
222 @node Introduction, Becoming someone else, Copying, Top
223 @unnumbered Introduction
226 It's often useful to be able to share accounts between a number of
227 users. For example, a group maintaining an externally visible service
228 need to be able to start and kill the server process. Giving such a
229 shared account a password is a fairly bad plan: such passwords tend not
230 to get changed very often, and they have a habit of spreading beyond the
231 group of legitimate users.
233 The Become program presented here offers a solution to the problems of
234 shared accounts. It allows the system administrator to define which
235 users are allowed access to which accounts, on which hosts, and to
236 execute which commands. Such shared accounts can then, in general, have
237 their passwords removed.
239 This coincidentally has another advantage: when `becoming' to a shared
240 account, a user can retain her@footnote{Or his. I'll choose one or the
241 other fairly randomly throughout this manual.} own environment, which
242 she's carefully crafted and honed over the years, rather then being
243 presented with some lowest-common-denominator setup which probably
244 doesn't even use the right shell.
246 The configuration file for Become can either be distributed to all the
247 various hosts in a network or a few carefully set up and secure servers
248 (@pxref{Standalone or networked}).
251 @c --------------------------------------------------------------------------
252 @node Becoming someone else, Administering Become, Introduction, Top
253 @chapter Becoming someone else
256 The simplest way to become someone else is to say
263 Become will check to see whether you're allowed to become @var{user}. If you
264 are, it starts a shell process with the user-id set to @var{user}. Any
265 commands you type are executed with the privileges of @var{user}.
267 The full invocation is slightly more complicated:
270 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{arg}@dots{}]]
273 Actually, the @var{option}s, @var{env-var}s and @var{user} can be in any
274 order -- the important point is that all of them appear before the
275 @var{command}, if there is one.
278 * Terminology:: Some important terms defined
279 * Environment:: Login styles and environment variables
280 * Group permissions:: How Become handles group permissions
281 * X authority:: Problems with X authority files
282 * Running commands:: Running commands other than a shell
287 @node Terminology, Environment, Becoming someone else, Becoming someone else
290 The following terms get used quite a bit in the following text:
294 An invocation of Become, asking permission to become another user.
297 The (real) user id of the process which invoked Become; usually, this will be
301 The user whom you want to become, named in a request.
306 @node Environment, Group permissions, Terminology, Becoming someone else
307 @section How Become sets up the environment
309 There are thorny problems with handling the user's environment. It seems
310 that (the author's initial assessment notwithstanding) there is no single
311 best way of handling environment variables. As a result, Become can do just
312 about everything you might want it to. This gets slightly complicated.
313 Don't worry: it's not as hard as all that.
316 * New environment variables:: Become adds some useful environment variables
317 * Login styles:: Choose how Become sets the environment
318 * Tweaking the environment:: Altering individual environment variables
319 * Removed variables:: Some environment variables aren't passed on
323 @node New environment variables, Login styles, Environment, Environment
324 @subsection Environment variables created by Become
326 To help you (and, more importantly, your startup scripts) keep track of who
327 you are, and who you were originally, Become adds some variables to the
328 environment of any processes it starts.
332 The name of the target user (i.e., the user you are now). It might be useful
333 to test this value in shell startup scripts, for example.
336 The home directory of the target user. It can be handy to read startup and
337 other configuration files from here.
339 @item BECOME_OLD_USER
340 The name of the user who invoked Become.
342 @item BECOME_OLD_HOME
343 The home directory of the `old' user.
345 @item BECOME_ORIGINAL_USER
346 This is intended to be the name you logged in with. If it's unset, Become
347 sets it to be the same as @code{BECOME_OLD_USER}; otherwise it leaves it
350 @item BECOME_ORIGINAL_HOME
351 This is intended to be the home directory you logged in with. If it's unset,
352 Become sets it to be the same as @code{BECOME_OLD_HOME}; otherwise, it leaves
356 Don't even think about relying on these variables as a form of
357 authentication. It won't work. They're provided only to help organise
362 @node Login styles, Tweaking the environment, New environment variables, Environment
363 @subsection Login styles
365 Originally, Become always tried to preserve your environment. There's a
366 rational explanation for this approach, which is given in the description of
367 the `preserve' style below. Unfortunately, not everyone liked this
368 approach. As a result, there's now a collection of different login styles.
370 Login styles are selected by giving command line arguments:
375 The original style: try to preserve the existing user's environment as much
380 Set some user-specific variables, like @code{USER} and @code{HOME} to reflect
381 the target user rather than the old user. All other variables are preserved.
385 Attempts to make the `become' process as much like a real login as possible.
386 All variables not explicitly preserved are deleted, and a new environment is
387 built, reflecting the target user.
390 The various styles, and the reasons behind them, are described below.
393 * The preserve style:: Preserve the current environment
394 * The set-user style:: Set user-specific variables (like @code{su})
395 * The login style:: Clear the environment (like @code{login})
399 @node The preserve style, The set-user style, Login styles, Login styles
400 @subsubsection The `preserve' login style
402 You've spent many hours (days? weeks, even?) customising and honing your
403 startup files, learning how to use your shell, and tweaking your favourite
404 text editor until it's just the way you like it. So there can be few things
405 more annoying than logging into a shared account to find out that the shell's
406 wrong, your editor startup files are ignored, and nothing works quite the way
407 you'd like it to. Typically you can't change this without annoying the other
408 users: the result is a horrible compromise which dissatisfies everyone
411 The `preserve' style lets you take your standard environment with you when
412 you become someone else. It tries hard not to modify any environment
415 Become starts your standard shell. If you have an environment variable
416 @code{SHELL} defined, than this is executed. Otherwise, the shell specified
417 in your entry in the password file is used. (You must have permission to
418 execute whatever shell is chosen as the target user, or you'll just be given
421 Most programs look at environment variables in preference to looking up
422 entries in the password database; e.g., they tend to use @code{USER} or
423 @code{LOGNAME} for the user name, and @code{HOME} for your home directory.
424 As a result, most programs will continue to find their configuration files in
425 your home directory. Also, systems like RCS will use your real name, rather
426 than the name of the user that you have become.
428 To make best use of this login style, you may need to adjust your login
429 scripts to notice when @code{BECOME_USER} is someone else, and read in
430 appropriate definitions. For example, a `bash' user might say something like
431 this in her @file{.bashrc}:
434 if [ -n "$BECOME_HOME" ]; then . $BECOME_HOME/.bashrc
438 Similarly, a C shell user (either `tcsh' or `csh') might say something like
441 if ($?BECOME_HOME) source $@{BECOME_HOME@}/.cshrc
444 (Note that plain Bourne shell users have a slight problem, because the Bourne
445 shell only reads configuration things on a login, not when a normal
446 interactive shell is started.)
449 @node The set-user style, The login style, The preserve style, Login styles
450 @subsubsection The `set-user' login style
452 The author sees the main use of Become as allowing a user to acquire the
453 privileges associated with a shared account without all the problems which
454 shared accounts usually cause. To the author's way of thinking, one of the
455 main problems is that your environment gets replaced by something alien and
456 wrong. People disagree with me over this point, and for this reason the
457 `set-user' style exists.
459 The objective of `set-user' style is to behave similarly to the standard
460 @code{su} command. Unless they've been preserved explicitly (@pxref{Tweaking
461 the environment}), `set-user' mode sets the following environment variables:
466 The name of the target user.
469 The home directory of the target user.
472 The target user's default shell
475 The result of this is that the shell will read the target user's
476 configuration files and present you with the environment set up there.
478 I can't think of this style as being anything other than a migration aid
479 while users are getting used to the freedom offered by the `preserve' style.
482 @node The login style, , The set-user style, Login styles
483 @subsubsection The `login' login style
485 The `login' style causes Become to attempt to emulate a full login. Become
486 will empty the environment of almost variables which aren't explicitly
487 preserved (@pxref{Tweaking the environment}). However, the following
488 variables are retained:
500 It will set the following variables:
505 The name of the target user.
508 The home directory of the target user.
511 The target user's default shell
514 An educated guess at where the target user's mailbox is.
517 By default, it runs the target user's shell, informing it that this is a
518 login by setting the first character of @code{argv[0]} to @samp{-}.
520 Become makes no entries in the @file{utmp} and @file{wtmp} files.
524 @node Tweaking the environment, Removed variables, Login styles, Environment
525 @subsection Tweaking individual environment variables
527 Become's login styles provide a sort of course-grained control over the
528 environment. Sometimes the control isn't fine enough. Become lets you tweak
529 individual variables: you can set, delete, or preserve named variables from
532 There are three different things you can do with environment variables:
536 Set a variable called @var{var} to a value @var{value}, by saying
539 @var{var}=@var{value}
543 The variable is preserved from automatic deletion by the login-style rules.
546 Delete a variable called @var{var} from the environment, by saying
553 Preserve a variable @var{var} from being deleted or modified by Become's
554 login-style rules, but not change its value, by saying
561 Just to try and make this slightly more sensible, here's an example. Suppose
562 I want my @code{XAUTHORITY} variable to be set when I become user `fred':
565 become XAUTHORITY=$HOME/.Xauthority fred
569 should do the job nicely. Similarly, if I want to log in as `bob', but don't
570 want my @code{EDITOR} variable to change:
573 become --login EDITOR! bob
577 (Of course, in this example, I'm at the mercy of Bob's shell init files as to
578 whether his choice of editor overrides mine.)
582 @node Removed variables, , Tweaking the environment, Environment
583 @subsection Variables removed from the environment
585 Some variables are removed from the environment which Become passes to a
586 program for security reasons:
593 These variables are used on various systems as a search path for shared
594 libraries. Clearly, by manipulating these search paths, an attacker could
595 replace a standard shared library with one of his own.
598 The shell input field separator. Modifying this variable radically alters
599 the way shells parse their inputs. (In particular, consider the case where
600 @code{IFS} contains @samp{/}.)
604 Used by some shells: it contains the name of a file to read on every shell
609 I'm not really sure what's going on here, so I'll just have to bluff my way
610 through. I think that the following is more-or-less accurate, having browsed
611 a small amount of Kerberos-related documentation.
613 Contains the name of a Kerberos configuration file. By manipulating this
614 variable, an attacker could persuade a program to believe the wrong
615 authentication server.
618 Also note that the @code{PATH} variable is modified: any items which aren't
619 absolute pathnames are removed from the path. This check may become stricter
620 in future, although getting the balance between security and convenience is
621 particularly hard here.
625 @node Group permissions, X authority, Environment, Becoming someone else
626 @section How Become handles groups
628 As well as handling changes of user id, Become also changes group ids.
629 The exact changes Become makes are under user control.
632 * Primary group selection:: Setting the new primary group
633 * Subsidiary groups:: Setting subsidiary group memberships
637 @node Primary group selection, Subsidiary groups, Group permissions, Group permissions
638 @subsection Choosing a new primary group
640 By default, the primary group is chosen according to the login style
641 (@pxref{Login styles}): the `preserve' style retains the current primary
642 group, while `set-user' and `login' styles choose the target's primary group.
644 You can override Become's default choice using the @code{--group} (@code{-g}
648 become --group=@var{group} @dots{}
651 The chosen @var{group} may be either a group name or a numeric gid. The
652 group must be one of the following:
656 Your current primary group.
658 One of your current subsidiary groups.
660 The target user's primary group.
662 One of the target user's subsidiary groups.
665 Become will raise an error if this isn't the case.
668 @node Subsidiary groups, , Primary group selection, Group permissions
669 @subsection Handling subsidiary group memberships
671 Subsidiary group memberships are a powerful tool for managing permissions
672 under Unix. Traditionally, they tend to be tied to particular users. Become
673 tries to be sightly more intelligent about group memberships.
675 Become has a concept of @dfn{group style}, analogous to login style
676 (@pxref{Login styles}). The styles are selected by giving command line
682 Retain the existing group memberships; don't add any new groups.
685 @itemx --merge-groups
686 Merge group memberships of the target user with the exiting memberships.
689 @itemx --replace-groups
690 Replace the existing group memberships with the target user's memberships.
693 Again, the defaults are dependent on the chosen login style. Both `preserve'
694 and `set-user' merge group memberships; the `login' style replaces the set of
697 Note that you can do perverse things like replace all the subsidiary groups
698 but retain your primary group (using the @code{--group} option;
699 @pxref{Primary group selection}) if you like: Become won't try to stop you.
703 @node X authority, Running commands, Group permissions, Becoming someone else
704 @section Considerations for X authority
706 Other users can't read your @file{.Xauthority} file, if you have one. This
707 is as it should be: anyone who can read it can connect to your X server and
708 read or generate events. However, once you've become another user, you can't
709 open any X windows; this can be annoying if your favourite editor is X-based.
711 There are two basic approaches. Either you can send the shared account a
712 copy of your display's magic cookie, or you can retain permission to read the
715 Be aware that allowing a shared account to connect to your X display is a
719 * The user-group method:: A fairly secure way of handling X authority
720 * Using xauth:: A less secure method, which might be easier
724 @node The user-group method, Using xauth, X authority, X authority
725 @subsection The user-group method for handling X authority
727 This method is secure only if your site uses the `user-group' system. In
728 this system, each user is allocated a group containing only that user.
729 Usually this is made the user's default primary group, although that's not
732 When you start a new X session, ensure that your cookie file is owned by you
733 and your private group. Change the file's permissions so that it's group
734 readable. Finally, ensure that your private group is retained when you
735 become someone else (@pxref{Group permissions}), and that the
736 @code{XAUTHORITY} variable is set correctly.
738 Note that Unix's security mechanisms aren't designed to prevent processes
739 owned by the same user from interfering with each other. This method does
740 not provide complete security.
742 The following Bourne shell code in a @file{.xinitrc} should do most of the
746 XAUTHORITY="$HOME/.Xauthority"
748 chgrp mygroup $XAUTHORITY
749 chmod 640 $XAUTHORITY
753 In a C shell, this becomes
756 setenv XAUTHORITY $@{HOME@}/.Xauthority
757 chgrp mygroup $XAUTHORITY
758 chmod 640 $XAUTHORITY
761 The @code{XAUTHORITY} file is preserved by both the `preserve' and `set-user'
762 login styles, so this isn't a problem. You can now become other users, and
763 your X permissions will follow you around correctly.
765 It's probably worth noting that the @code{xauth} program annoyingly resets
766 the permissions on the cookie file every time it writes to it. This will be
767 particularly irritating if you use @code{ssh}'s X forwarding capabilities,
768 because every @code{ssh} connection will reset the permissions. You can deal
769 with this problem by putting a line
772 chmod 640 $@{XAUTHORITY-$HOME/.Xauthority@} 2>/dev/null
776 in your @file{.bashrc} or @file{.profile} (for Bourne-like shell users) or
779 if ($?XAUTHORITY) then
780 chmod 640 $XAUTHORITY >&/dev/null
782 chmod 640 $@{HOME@}/.Xauthority >&/dev/null
787 in @file{.cshrc} for C shell users.
790 @node Using xauth, , The user-group method, X authority
791 @subsection The @code{xauth} method for handling X authority
793 This method sends your X cookie to the shared account. It's therefore
794 intrinsically dangerous: you must be able to trust the other users of the
795 shared account not to take undue advantage of this situation.
797 The following (Bourne) shell snippet illustrates how you might send an
798 authorisation cookie to the shared account, to allow it to connect to your
802 if test -n "$BECOME_HOME"; then
803 XAUTHORITY="$BECOME_HOME/.Xauthority"; export XAUTHORITY
804 elif test -n "$DISPLAY" && test -z "done_xauth_cookie"; then
806 :0.0) display=`hostname`:0.0 ;;
807 *) display="$DISPLAY" ;;
809 xauth extract - $display | \
810 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
811 done_xauth_cookie=yes; export done_xauth_cookie
815 The equivalent C shell code is
818 if ($?BECOME_HOME) then
819 setenv XAUTHORITY "$@{BECOME_HOME@}/.Xauthority
820 else if ($?DISPLAY && ! $?done_xauth_cookie) then
821 if ($DISPLAY == :0.0) then
822 set display="`hostname`:0.0"
824 set display="$DISPLAY"
826 xauth extract - $display | \
827 become someone -c 'xauth -f $BECOME_HOME/.Xauthority merge -'
835 If the variable @code{BECOME_HOME} is set, then we're probably really someone
836 else, so point to the shared account's authority file.
839 Otherwise, check to see whether we have a display, and the authorisation has
840 not already been sent. If this is so, resolve a local display name into a
841 remote one (just in case) and then send it to the shared account.
846 @node Running commands, , X authority, Becoming someone else
847 @section Executing specific commands
849 As well as starting shells, Become can run single commands. This can be
854 It enables Become to be used in scripts.
857 It allows access to shared accounts to be controlled on the basis of the
861 To run a command as another user, say:
864 become @var{user} @var{command} [@var{argument}@dots{}]
867 If the request is granted, Become runs @var{command}, passing it any
868 arguments following the command name. Become doesn't run a shell, so there's
869 no extra escaping which needs to be done.
871 If you really want to run a shell command as another user, you can use the
875 become @var{user} -c @var{shell-command}
878 This is exactly equivalent to
881 become @var{user} /bin/sh -c @var{shell-command}
884 in every way. In particular, you must have permission to run @file{/bin/sh}
885 as @var{user} for it to work: Become doesn't attempt to interpret the shell
886 command in any way. Also note that Become always uses the Bourne shell,
887 regardless of your current shell preference, or @var{user}'s default shell.
888 (This is done to provide a stable programming interface which works
889 irrespective of changes to the shared account's configuration.)
892 @c --------------------------------------------------------------------------
893 @node Administering Become, Invoking Become, Becoming someone else, Top
894 @chapter Become administration
897 This chapter will explain how Become is administrated and maintained.
900 * Configuration files:: Overview of Become's configuration files
901 * Standalone or networked:: The two main types of Become installations
902 * The configuration file:: How to define who's allowed to do what
903 * Networked configuration:: Considerations for networked installations
908 @node Configuration files, Standalone or networked, Administering Become, Administering Become
909 @section Configuration files
911 Become keeps its configuration and administrative files in a directory
912 usually named @file{/etc/become}, although this can be changed with the
913 @code{--with-etcdir} option to the configuration script when you build
916 Not all of the files are needed on all machines.
920 The main configuration file, containing a description of which users are
921 allowed to become which other users, where, and what they're allowed to run
922 when they get there. Only needed on servers or standalone machines.
925 A list of servers to contact. Only needed on client machines.
928 The encryption key to use when sending requests to servers. Needed on
929 clients and servers, but not on standalone machines.
932 The process id of the server. Created automatically by Become's server when
936 Contains state information for Become's random number generator. Created
937 automatically if it doesn't exist.
941 @node Standalone or networked, The configuration file, Configuration files, Administering Become
942 @section Installation types
945 Become can be installed in two different ways, depending on how you want to
950 In a @dfn{standalone} installation, each Become request is dealt with
951 locally: the program reads the configuration file, and decides whether it
952 should grant or deny permission.
954 Standalone installations don't depend on servers being available, or even on
955 the existence of a network. They're useful for small sites, or sites with a
956 small number of users. The disadvantages are that reading the configuration
957 file takes a while, so the program doesn't feel as responsive as it should,
958 and ensuring that all the hosts' configuration files are synchronised becomes
959 difficult when you have lots of machines.
962 In a @dfn{network} installation, any Become requests are sent on to a
963 collection of servers. The servers analyse the request and send a reply back
964 which either authorises or forbids access.
966 A networked installation clearly depends on the servers' reliability. The
967 client reacts only to the first reply it receives, so as long as there is one
968 server running, everything should continue as normal.
970 A networked installation is useful when you have a large number of client
971 machines, particularly ones which may not be awake all the time. The full
972 configuration file only needs to be installed on a small number of servers;
973 the clients require only a list of server machines to contact, and an
974 encryption key to use.
979 @node The configuration file, Networked configuration, Standalone or networked, Administering Become
980 @section The configuration file
982 The main configuration file, usually called @file{/etc/become/become.conf},
983 contains all the rules which Become uses to decide whether to grant or deny
984 requests. It may also contain additional information for the benefit of
985 Become daemons, if you're using a networked installation.
988 * Requests and rules:: How the configuration file works
989 * Basic syntax:: Quick overview of Become's syntax
990 * Classes:: Defining classes of things
991 * Predefined classes:: Become predefines some (maybe) useful classes
992 * Allow statements:: Allow users to become other users
993 * Other statements:: Some other useful statements
994 * Example configuration file:: An example, showing a few features.
995 * Checking and querying:: Checking and querying configuration files
996 * Complete grammar:: Complete grammar for Become config files
1000 @node Requests and rules, Basic syntax, The configuration file, The configuration file
1001 @subsection Requests and rules
1003 Become looks at four pieces of information when it's analysing a request:
1007 the user's current identity;
1009 the identity the user wishes to assume;
1011 the host which generated the request; and
1013 the command the user wishes to run.
1016 Each of these pieces of information is looked at when Become decides whether
1017 to honour a request.
1019 The configuration file's main purpose is to describe the conditions under
1020 which Become should honour a request. These conditions are described by a
1021 number of @emph{rules}. A rule consists of two lists of users (called `from'
1022 and `to'), a list of hosts, and a list of commands. A rule matches a request
1027 the user's current identity is in the rule's `from' list;
1029 the target user's identity is in the rule's `to' list;
1031 the host is in the rule's host list; and
1033 the command to be run is in the rule's command list.
1036 A request is honoured if there is a rule which matches the request.
1039 @node Basic syntax, Classes, Requests and rules, The configuration file
1040 @subsection Basic configuration file syntax
1042 The configuration file consists of a sequence of statements, each terminated
1045 Comments begin with a @samp{#} character, and continue to the end of the
1046 line. This is the only time newlines behave specially: newlines behave just
1047 like any other whitespace characters within statements.
1049 Strings are enclosed in double-quote characters (@samp{"}). Within a string,
1050 a backslash causes the following character to be treated literally, whatever
1051 it may be (including quotes, backslashes and newlines).
1053 Names begin with an alphabetic character or an underscore, and consist of
1054 letters, digits and underscores.
1057 @node Classes, Predefined classes, Basic syntax, The configuration file
1060 A @dfn{class} in Become is a set of users, hosts or commands. You can define
1061 and name your own classes using statements of the form:
1064 user @var{name} = @var{class-expr} ;
1065 command @var{name} = @var{class-expr} ;
1066 host @var{name} = @var{class-expr} ;
1069 A @var{class-expr} is an expression defining a class. You can build a
1070 complex class out of simple classes using the operators (in ascending
1071 precedence order) @samp{,}, @samp{-}, @samp{|} and @samp{&}, which represent
1072 the set options `union', `subtraction', `union' (again!), and `intersection'.
1073 Subexpressions can be parenthesised to override the default precedence.
1074 Once a class name has been defined, as shown above, it can be used in
1075 subsequent class expressions.
1077 A single user may be designated by either a user name (in quotes) or an
1078 integer uid. Commands and hosts may be designated by quoted strings which
1079 may contain wildcards. Host strings are matched against both numeric (dotted
1080 quad) IP addresses and the reverse-resolved hostname. Command strings are
1081 matched against the absolute pathname of the command the user wants to
1086 @node Predefined classes, Allow statements, Classes, The configuration file
1087 @subsection Predefined classes
1089 In an attempt to make life a bit easier, Become creates a collection of
1092 The standard classes @code{all} and @code{none} match anything and nothing
1093 respectively. The @code{all} class is useful in some contexts: it gives you
1094 a way of saying `everything except@dots{}', for example:
1097 user MUNDANES = all - SYSHACKS;
1101 The @code{none} class is provided because it's needed internally anyway and
1102 someone might come up with a use for it.
1104 Become also defines some other classes:
1108 For each username @var{user}, Become adds a class called @samp{@var{user}}
1109 which matches just that user.
1112 For each group name @var{group}, Become creates a class called
1113 @samp{@var{group}} which matches any user who is a member of that group.
1115 @item For each netgroup @var{netgroup}, Become creates two classes:
1116 @samp{u_@var{netgroup}} which matches any user listed in the netgroup, and
1117 @samp{h_@var{netgroup}} which matches any host listed in the netgroup.
1120 If a name is used for both a user @emph{and} a group, then corresponding
1121 class ends up containing the user together with all of the group members.
1122 For this reason, it's probably better to use the predefined classes for
1123 groups rather than individual users -- use quoted user names for individual
1126 Note that users and groups are read using the standard @code{get*ent} calls
1127 @emph{and} directly from the NIS server (if there is one). The idea here is
1128 that a Become server can be run on a machine which allows restricted logins.
1129 It still needs to know about all the users known to the outside world.
1131 Netgroups are read only from the NIS servers. In particular, although GNU
1132 systems allow netgroup databases to be stored in local files, Become won't
1133 read them because there's no defined interface for enumerating netgroups.
1136 @node Allow statements, Other statements, Predefined classes, The configuration file
1137 @subsection Allow statements
1139 The @code{allow} statement defines the rules Become uses when deciding
1140 whether to grant a request; see @ref{Requests and rules}.
1143 allow [[@var{host-class}]] [@var{user-class}] -> [@var{user-class}] [ : @var{command-class}]
1146 (The @var{host-class} is optional, but must be enclosed in square brackets if
1149 The four classes in an allow statement are called, respectively, the `host',
1150 the `to-user', the `from-user' and the `command'. Any of the four classes
1151 may be omitted, and an omitted class defaults to `all'.
1153 When a request is received, Become checks the fields in the request against
1154 the classes in each allow statement of the configuration file. If a
1155 statement matches, the request is granted; if there are no full matches,
1156 the request is denied.
1159 @node Other statements, Example configuration file, Allow statements, The configuration file
1160 @subsection Other statements
1162 Two other statement types are defined. They only have an effect on Become in
1167 keyfile @var{key-file} ;
1171 The @code{port} statement specifies the port to which the server should
1172 listen; the @var{port} may be be an integer or a quoted service name. The
1173 @code{keyfile} statement instructs Become to use the key from the file named
1174 @var{key-file}, which must be a quoted string.
1177 @node Example configuration file, Checking and querying, Other statements, The configuration file
1178 @subsection An example configuration file
1184 # Example configuration file
1187 allow wheel -> "root";
1189 user NEWS = "fred", "jim";
1190 allow NEWS -> "news";
1192 user HTTP = "jim", "bob";
1193 allow ["www.somewhere.com"]
1194 HTTP -> "httpd" : "/bin/kill", "/etc/init.d/httpd";
1198 @node Checking and querying, Complete grammar, Example configuration file, The configuration file
1199 @subsection Checking and querying the configuration file
1201 At a reasonably sized site, Become configuration files can get rather large,
1202 and becomes tricky to work out exactly who's allowed to do what and where.
1204 The @code{bcquery} tool provided allows Become configuration files to be
1205 verified and queried. It can be used to ensure that a file is syntactically
1206 correct before it is deployed, or to enquire about privileges granted.
1209 * Verifying config files:: Checking a configuration file is correct
1210 * Querying config files:: Asking questions about privileges
1211 * Output formats:: Different ways of formatting output
1212 * Restricting output:: Being selective about what gets output
1213 * bcquery reference:: Complete command line reference
1216 @node Verifying config files, Querying config files, Checking and querying, Checking and querying
1217 @subsubsection Verifying configuration files
1219 A common use of @code{bcquery} is to ensure that a configuration file is
1220 actually valid. The command
1223 bcquery [-file @var{file}] -check
1227 verifies that a configuration file conforms to Become's expectations. If
1228 there are any errors in @var{file}, they are reported, and @code{bcquery}
1229 will return a nonzero exit code.
1231 If no @var{file} is specified, @code{bcquery} will read the configuration
1232 file which Become itself reads by default, usually
1233 @code{/etc/become/become.conf}.
1236 @node Querying config files, Output formats, Verifying config files, Checking and querying
1237 @subsubsection Querying configuration files
1239 The @code{bcquery} program will list all rules which match a selected request
1240 pattern. For example, you can display all rules which allow a particular
1241 user to change identity, or all rules which allow people to assume root
1242 privileges on a particular host.
1245 bcquery [-file @var{file}] @var{query}
1248 The following simple queries are supported:
1251 @item @code{-from} @var{user}
1252 Matches any rule containing @var{user} in its `from' list.
1253 @item @code{-to} @var{user}
1254 Matches any rule containing @var{user} in its `to' list.
1255 @item @code{-host} @var{host}
1256 Matches any rule containing @var{host} in its host list.
1257 @item @code{-command} @var{cmd}
1258 Matches any rule containing @var{cmd} in its `command' list.
1262 Simple queries can be combined using the following operators:
1265 @item @var{query-a} @code{-or} @var{query-b}
1266 Matches a rule matched by either @var{query-a} or @var{query-b}.
1267 @item @var{query-a} @code{-and} @var{query-b}
1268 Matches a rule matched by both @var{query-a} and @var{query-b}.
1269 @item @code{-not} @var{query}
1270 Matches a rule which is not matched by @var{query}.
1271 @item @code{(} @var{query} @code{)}
1272 Matches a rule matched by @var{query} (overrides default precedence).
1275 The @code{-and}, @code{-or} and @code{-not} operators may be written
1276 @code{&}, @code{|} and @code{!} respectively, if you prefer, and the
1277 @code{-and} operator is optional. These characters (and the parentheses
1278 @code{(} and @code{)}) may need to be quoted to prevent interpretation by the
1281 Some examples may explain what's going on:
1284 @item bcquery -from hacker
1285 Displays all rules applying to user `hacker'.
1286 @item bcquery -host somehost -to root
1287 Displays rules allowing people to become root on @code{somehost}.
1291 @node Output formats, Restricting output, Querying config files, Checking and querying
1292 @subsubsection Output formats
1294 The @code{bcquery} program has two distinct output formats: `rows' and
1297 The `columns' format is probably the simpler to understand, and certainly the
1298 easier to read. Each matching record is displayed with the lists of users,
1299 hosts and commands in columns. A query on the example configuration file
1300 (@pxref{Example configuration file}) is shown below:
1303 FROM TO HOST COMMAND
1305 frankie root ALL ALL
1311 jim httpd www.somewhere.com /bin/kill
1312 bob /etc/init.d/httpd
1316 The `columns' format can only show simple lists. A more complex class
1317 definition will show up as @samp{<complex>} in a `columns' format listing.
1319 The `rows' format is capable of displaying classes in their full generality,
1320 but is harder to parse and read. It displays each list in the form of an
1321 expression, in more or less the same syntax as a class definition
1324 The default behaviour is to use `columns' format where possible, or `rows'
1325 format if some of the lists are too complex to be represented in columns.
1326 You can select a format explicitly using the @code{-columns} or @code{-rows}
1327 options, which is useful if you're trying to parse the output of
1328 @code{bcquery} with a script.
1331 @node Restricting output, bcquery reference, Output formats, Checking and querying
1332 @subsubsection Restricting output
1334 It's also possible to suppress bits of information about each matched rule.
1335 For example, you can show only the `from' list, or just the `to' and `host'
1336 lists. This is done with the @code{-output} option.
1338 Each list is given a letter; the `from' list is called @samp{f}, the `to'
1339 list @samp{t}, the host list @samp{h} and the command list @samp{c}. You can
1340 select which lists are displayed by giving the corresponding letters (the
1341 order isn't important). You can also turn individual lists on or off by
1342 preceding the characters with @samp{+} or @samp{-} characters. If you start
1343 with a @samp{+} or @samp{-}, then the last-set selection (or the initial
1344 default of all-lists-enabled) is modified.
1346 For example, @samp{-output ftc} shows only the `from', `to' and `command'
1347 lists. This could be written @samp{-output -h} too, to turn the hosts list
1350 This option is mainly useful with the `columns' output format (@pxref{Output
1351 formats}) to save scripts having to select columns out themselves.
1354 @node bcquery reference, , Restricting output, Checking and querying
1355 @subsubsection @code{bcquery} options summary
1358 bcquery [@var{option}@dots{}] [@var{query}]
1361 The @var{option}s available are:
1365 Displays a summary of the available options, and exits.
1367 @item @code{-file} @var{file}
1368 Read @var{file}, rather than the compiled-in default (usually
1369 @file{/etc/become/become.conf}).
1372 Don't read a configuration file. Instead, display the query tree parsed from
1373 the command line. This is a debugging feature.
1376 Don't attempt to output any rules. Instead, just check the configuration
1379 @item @code{-output} @var{spec}
1380 Selects which columns are to be displayed for each matching rule.
1381 For full details, see @ref{Restricting output}.
1383 @item @code{-columns}
1385 Forces `columns' or `rows' output format. @xref{Output formats}.
1387 @item @code{-nohead}
1388 Suppress the header line at the top of the output in `columns' mode. Makes
1389 the output more amenable to automatic processing (but harder to read).
1391 @item @code{-from} @var{user}
1392 @itemx @code{-to} @var{user}
1393 @itemx @code{-host} @var{hostname}
1394 @itemx @code{-command} @var{cmd}
1395 Simple queries for selecting rules. @xref{Querying config files}.
1400 Operators for combining queries into something useful. @xref{Querying config
1405 @node Complete grammar, , Checking and querying, The configuration file
1406 @subsection Complete grammar for configuration files
1409 @var{file} ::= @var{file} @var{statement}
1411 @var{statement} ::= @var{class-def}
1416 @var{class-def} ::= @samp{user} @var{name} = @var{class-expr} @samp{;}
1417 | @samp{command} @var{name} = @var{class-expr} @samp{;}
1418 | @samp{host} @var{name} = @var{class-expr} @samp{;}
1420 @var{allow-spec} ::= @samp{allow} @var{opt-host-spec} @var{opt-user-spec}
1421 @samp{->} @var{opt-user-spec} @var{opt-command-spec} @samp{;}
1423 @var{opt-host-spec} ::= @samp{[} @var{class-expr} @samp{]}
1426 @var{opt-user-spec} ::= @var{class-expr}
1429 @var{opt-command-spec} ::= @samp{:} @var{class-expr}
1432 @var{port-spec} ::= @samp{port} @var{integer} @samp{;}
1433 | @samp{port} @var{string} @samp{;}
1435 @var{key-spec} ::= @samp{keyfile} @var{string} @samp{;}
1437 @var{class-expr} ::= @var{class-diff-expr}
1438 | @var{class-expr} @samp{,} @var{class-diff-expr}
1440 @var{class-diff-expr} ::= @var{class-isect-expr}
1441 | @var{class-diff-expr} @samp{-} @var{class-union-expr}
1443 @var{class-union-expr} ::= @var{class-isect-expr}
1444 | @var{class-union-expr} @samp{|} @var{class-isect-expr}
1446 @var{class-isect-expr} ::= @var{class-primary}
1447 | @var{class-isect-expr} @samp{&} @var{class-primary}
1449 @var{class-primary} ::= @samp{(} @var{class-expr} @samp{)}
1453 @var{integer} ::= one or more digits (@samp{0}--@samp{9})
1455 @var{name} ::= an alphabetic character or underscore, followed by zero or
1456 more alphanumeric characters or underscores
1458 @var{string} ::= @samp{"} @var{string-chars} @samp{"}
1460 @var{string-chars} ::= @var{string-chars} @var{string-char}
1463 @var{string-char} ::= a @samp{\} followed by any character
1464 | any character other than @samp{"}, @samp{\} or newline
1471 @node Networked configuration, , The configuration file, Administering Become
1472 @section Networked configuration
1474 If you're planning to use Become in a standalone way, you can skip this
1478 * Choosing servers:: Which servers Become tries to talk to
1479 * Setting up keys:: How to generate keys for Become
1480 * Random number files:: Become keeps random number state around
1481 * Issuing a new key:: How to issue new keys without disruption
1485 @node Choosing servers, Setting up keys, Networked configuration, Networked configuration
1486 @subsection Choosing servers
1488 Become notices that it's meant to send requests to a server if it finds a
1489 @file{become.server} file. This file contains entries of the form
1492 @var{host} [: @var{port}]
1495 If the @var{port} is omitted, Become chooses a port by looking at the
1496 services database for a service which matches the name by which Become was
1497 invoked: normally this will be @samp{become}.
1499 Become sends a request to all of the servers and believes the first valid
1500 reply it receives. Since servers ignore requests they believe to be invalid,
1501 this enables you to change Become's key without disrupting service
1502 (@pxref{Issuing a new key}).
1504 If you're using NIS, you should try to ensure that Become servers runs only
1505 on NIS servers; the NIS master is probably a good choice.
1507 Become isn't particularly processor-intensive, and doesn't seem to require
1511 @node Setting up keys, Random number files, Choosing servers, Networked configuration
1512 @subsection Setting up keys
1514 Communication between Become clients and the server is encrypted to ensure
1515 that it's not feasible to gain unauthorised privilege by subverting the
1516 network. Become uses simple symmetric cryptography -- it's not necessary to
1517 use complicated public key techniques in this case.
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 the @code{keygen} program, supplied. The
1527 keygen --bits=128 --output=/etc/become/become.key
1531 generates a 128-bit key and writes it to @file{/etc/become/become.key} in a
1532 format which Become can read.
1534 The @code{keygen} program works by measuring the time between keystrokes. It
1535 also tries to obtain some randomness from the environment, and mixes all of
1536 this noise together before it outputs the key file.
1538 Having generated a key, it must be distributed to all of the other hosts
1539 which will use this server. The author recommends using the @code{scp}
1540 program, distributed with the @code{SSH} (Secure Shell) package, for doing
1543 Being able to read a key file enables a user to assume root privileges. The
1544 author recommends that only the super-user be able to read key files.
1547 * Invoking keygen:: How to use the @code{keygen} program
1551 @node Invoking keygen, , Setting up keys, Setting up keys
1552 @subsubsection Invoking @code{keygen}
1555 keygen [@var{option}@dots{}]
1558 By default, @code{keygen} generates a 128-bit key, and writes it to standard
1559 output in a hexadecimal format. This behaviour can be modified by passing
1565 Write a summary of @code{keygen}'s usage instructions to standard output and
1569 @itemx --bits=@var{bits}
1570 Generate a @var{bits}-bit key, instead of the default 128 bits.
1573 @itemx --output=@var{file}
1574 Write the key to @var{file} instead of standard output.
1576 @item -f @var{format}
1577 @itemx --format=@var{format}
1578 Set the format in which @code{keygen} outputs the generated key. If the
1579 @var{format} is @samp{hex} (or @samp{tx}), the key is output in Become's
1580 hexadecimal format; @samp{binary} writes the key as a raw binary dump; and
1581 @samp{base64} writes the key using the Base64 encoding.
1586 @node Random number files, Issuing a new key, Setting up keys, Networked configuration
1587 @subsection Random number files
1589 Become uses random numbers to generate session keys when it's communicating
1590 with a server. When it's finished, it stores the state of its random number
1591 generator in a file, usually @code{/etc/become/become.random}. If this file
1592 doesn't exist, Become creates it automatically, using noise collected from
1593 the environment. It's probably not worth your while creating randomness
1597 @node Issuing a new key, , Random number files, Networked configuration
1598 @subsection Issuing a new key
1600 When you're sending out a new key, you run a risk of disrupting service. The
1601 server reads a new key; the clients still have the old one.
1603 The author's recommendation is to run two servers. Update the key on one.
1604 Then send the new key to all of the clients. Finally, update the key on the
1605 other server. Because of the way Become works, a client will always get a
1606 response from one of the servers, depending on whether the new key has
1609 A similar method is handy if Become's protocol ever changes. (This is quite
1610 likely at the moment. The current protocol doesn't include any version
1611 information, and the MAC isn't as good as it could be.)
1614 @c --------------------------------------------------------------------------
1615 @node Invoking Become, , Administering Become, Top
1616 @chapter Invoking Become
1619 This chapter provides an exhaustive description of Become's command line
1620 options, organised in a reference-manual sort of way.
1623 * Becoming another user:: Options for becoming another user
1624 * Starting Become daemons:: Options for starting Become daemons
1625 * Debugging options:: Options to use when Become goes wrong
1630 @node Becoming another user, Starting Become daemons, Invoking Become, Invoking Become
1631 @section Becoming another user
1633 @subsection Synopsis
1636 become [@var{option}@dots{}] [@var{env-var}@dots{}] @var{user} [@var{command} [@var{argument}@dots{}]]
1639 Actually, you can put the @var{option}s, @var{env-var}s and @var{user} in any
1640 order you like; the important thing is that all of them appear before the
1646 The @var{option}s appropriate for this mode are as follows:
1651 Display a (fairly verbose) help message describing the various command line
1652 options and exits successfully.
1656 Display a terse summary of the command line options and exits successfully.
1660 Display's Become's version number and exits successfully.
1663 @item --preserve-environment
1664 Selects the `preserve' login style (@pxref{The preserve style}). All
1665 environment variables are preserved. The default command is the current
1666 user's own shell. The default primary group becomes the current primary
1667 group; the default group style is set to `merge'.
1672 Selects the `set-user' login style (@pxref{The set-user style}). Most
1673 environment variables are preserved, but @code{USER}, @code{LOGNAME},
1674 @code{HOME} and other user-specific variables are altered to reflect the
1675 target user's configuration. The default command is the target user's shell.
1676 The default primary group becomes the target user's primary group; the
1677 default group style is set to `merge'.
1681 Selects the `login' login style (@pxref{The login style}). The environment
1682 is cleared and rebuilt, in a similar way to the behaviour of @code{login}.
1683 The default command is the target user's shell. The default primary group
1684 becomes the target user's primary group; the default group style is set to
1687 @item -g @var{group}
1688 @itemx --group=@var{group}
1689 Selects @var{group} as the primary group; it may be either a group name or a
1690 numeric group id. Note that @var{group} must be the primary group or
1691 a subsidiary group of either the current user or the target user.
1694 @itemx --keep-groups
1695 Selects the `keep' group style (@pxref{Subsidiary groups}). The current set
1696 of subsidiary group memberships are passed on unchanged.
1699 @itemx --merge-groups
1700 Selects the `merge' group style (@pxref{Subsidiary groups}). The current set
1701 of subsidiary group memberships are merged with the subsidiary groups of the
1705 @itemx --replace-groups
1706 Selects the `replace' group style (@pxref{Subsidiary groups}). The target
1707 user's subsidiary group memberships are passed on; the current subsidiary
1708 groups are discarded.
1710 @item -c @var{shell-cmd}
1711 @itemx --command=@var{shell-cmd}
1712 Sets the @var{command} and @var{argument}s to invoke
1713 @code{/bin/sh -c @var{shell-cmd}}; i.e., to execute a Bourne shell command
1714 instead of just @code{exec}ing a program. Note that permissions are checked
1715 for executing the Bourne shell @code{/bin/sh}; the contents of the
1716 @var{shell-cmd} are not inspected.
1719 The @var{env-var} arguments fine-tune the environment passed to the command.
1720 Each @var{env-var} setting must be one of the following:
1723 @item @var{var}=@var{value}
1724 Assign the variable named @var{var} the value @var{value}. Protect the
1725 variable @var{var} from modifications by the login style.
1728 Protect the variable @var{var} from modifications by the login style, but
1729 don't change its value.
1732 Remove the variable @var{var} from the environment; do not pass it on.
1735 The @var{user} specifies the user as whom the @var{command} should be
1736 executed (i.e., the @dfn{target user}). It may be a user name or a numeric
1739 The @var{command} specifies a command to execute. If @var{command} does not
1740 contain a path, it is looked for using the current @code{PATH} environment
1741 variable. The resulting pathname is canonified if necessary, to produce an
1742 absolute pathname. Note that symbolic links are @emph{not} resolved -- this
1743 prevents an attack whereby a user could invoke a program, passing it an
1744 unusual @code{argv[0]} which might cause unusual behaviour.
1746 The @var{command} name is used both as the command to execute and passed to
1747 the command as @code{argv[0]}. It is not possible to specify an alternative
1748 value to be passed as @code{argv[0]}. Subsequent arguments, if supplied, are
1749 passed as @code{argv[1]} upwards.
1751 If no @var{command} is given, a shell is invoked; the particulars of the
1752 shell are determined by the login style (see above).
1754 The @var{command} is executed as follows:
1758 The subsidiary groups are chosen as determined by the group style.
1760 The real and effective gids are set.
1762 The real and effective uids are set.
1764 The @var{command} is called using the standard @code{execve} system call.
1769 @node Starting Become daemons, Debugging options, Becoming another user, Invoking Become
1770 @section Starting Become daemons
1772 @subsection Synopsis
1775 become --daemon [@var{option}@dots{}]
1781 The following options are appropriate to this mode:
1786 Display a (fairly verbose) help message describing the various command line
1787 options and exits successfully.
1791 Display a terse summary of the command line options and exits successfully.
1795 Display's Become's version number and exits successfully.
1799 Start a Become server, instead of processing a request. Become will read its
1800 command line options, read in the configuration file (and verify that it's
1801 correct) and then fork into the background to wait for incoming requests.
1802 Become relinquishes all setuid privileges (by setting all uids to the real
1803 uid) when it enters daemon mode. It is therefore only really useful to run a
1804 daemon as the superuser.
1807 @itemx --port=@var{port}
1808 Listen for requests on @var{port}. This option is overridden by the
1809 @code{port} option in the configuration file.
1812 @itemx --config-file=@var{file}
1813 Read configuration from @var{file}, instead of the default (set at
1814 compile time, usually @file{/etc/become/become.conf}).
1817 The syntax of the configuration file is described in @ref{The configuration
1821 @node Debugging options, , Starting Become daemons, Invoking Become
1822 @section Debugging options
1824 Some options are only useful when trying to find out why Become is
1825 misbehaving. Of course, this never happens, so here are the options which
1826 you won't need to use:
1829 @item -T[@var{file}]
1830 @itemx --trace[=@var{file}]
1831 Write trace information to @var{file} (or to standard output, if no
1832 @var{file} is specified). You must be able to create the file and open it
1835 @item -L[@var{feature}...]
1836 @itemx --trace-level[=@var{feature}]
1837 Selects which features Become ought to trace. Each feature is allocated a
1838 letter; simply string together the letters for the features you want to
1839 debug. The letters @samp{D} and @samp{A} stand respectively for `default'
1840 and `all' features; you can subtract from them by saying, for example,
1841 @samp{A-xyz} to select all features except @samp{x}, @samp{y} and @samp{z}.
1842 The exact list of features supported at any one time can be listed by giving
1843 the @code{--trace-level} option without an argument.
1846 @itemx --impersonate=@var{user}
1847 Pretend to be @var{user} instead of yourself when the request is checked.
1848 This option can only be used if it wasn't disabled at compile-time and if
1849 Become is not running setuid. Even so, Become will only inform you of the
1850 outcome; it will not execute any commands.
1855 @c --------------------------------------------------------------------------
1857 @c --- No index yet ---
1859 @c @node Concept index, , Invoking Become, Top
1860 @c @unnumbered Concept index
1867 @c ----- That's all, folks --------------------------------------------------