doc/xml/AdminGuide/auagd021.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <chapter id="HDRWQ581">
   3   <title>Managing Administrative Privilege</title>
   4
   5   <para>This chapter explains how to enable system administrators and operators to perform privileged AFS operations.</para>
   6
   7   <sect1 id="HDRWQ582">
   8     <title>Summary of Instructions</title>
   9
  10     <para>This chapter explains how to perform the following tasks by using the indicated commands:</para>
  11
  12     <informaltable frame="none">
  13       <tgroup cols="2">
  14         <colspec colwidth="70*" />
  15
  16         <colspec colwidth="30*" />
  17
  18         <tbody>
  19           <row>
  20             <entry>Display members of <emphasis role="bold">system:administrators</emphasis> group</entry>
  21
  22             <entry><emphasis role="bold">pts membership</emphasis></entry>
  23           </row>
  24
  25           <row>
  26             <entry>Add user to <emphasis role="bold">system:administrators</emphasis> group</entry>
  27
  28             <entry><emphasis role="bold">pts adduser</emphasis></entry>
  29           </row>
  30
  31           <row>
  32             <entry>Remove user from <emphasis role="bold">system:administrators</emphasis> group</entry>
  33
  34             <entry><emphasis role="bold">pts removeuser</emphasis></entry>
  35           </row>
  36
  37           <row>
  38             <entry>Display <computeroutput>ADMIN</computeroutput> flag in Authentication Database entry</entry>
  39
  40             <entry><emphasis role="bold">kas examine</emphasis></entry>
  41           </row>
  42
  43           <row>
  44             <entry>Set or remove <computeroutput>ADMIN</computeroutput> flag on Authentication Database entry</entry>
  45
  46             <entry><emphasis role="bold">kas setfields</emphasis></entry>
  47           </row>
  48
  49           <row>
  50             <entry>Display users in <emphasis role="bold">UserList</emphasis> file</entry>
  51
  52             <entry><emphasis role="bold">bos listusers</emphasis></entry>
  53           </row>
  54
  55           <row>
  56             <entry>Add user to <emphasis role="bold">UserList</emphasis> file</entry>
  57
  58             <entry><emphasis role="bold">bos adduser</emphasis></entry>
  59           </row>
  60
  61           <row>
  62             <entry>Remove user from <emphasis role="bold">UserList</emphasis> file</entry>
  63
  64             <entry><emphasis role="bold">bos removeuser</emphasis></entry>
  65           </row>
  66         </tbody>
  67       </tgroup>
  68     </informaltable>
  69   </sect1>
  70
  71   <sect1 id="HDRWQ584">
  72     <title>An Overview of Administrative Privilege</title>
  73
  74     <indexterm>
  75       <primary>administrative privilege</primary>
  76
  77       <secondary>three types</secondary>
  78     </indexterm>
  79
  80     <indexterm>
  81       <primary>privilege</primary>
  82
  83       <secondary></secondary>
  84
  85       <see>administrative privilege</see>
  86     </indexterm>
  87
  88     <para>A fully privileged AFS system administrator has the following characteristics: <itemizedlist>
  89         <listitem>
  90           <para>Membership in the cell's <emphasis role="bold">system:administrators</emphasis> group. See <link
  91           linkend="HDRWQ586">Administering the system:administrators Group</link>.</para>
  92         </listitem>
  93
  94         <listitem>
  95           <para>The <computeroutput>ADMIN</computeroutput> flag on his or her entry in the cell's Authentication Database. See <link
  96           linkend="HDRWQ589">Granting Privilege for kas Commands: the ADMIN Flag</link>.</para>
  97         </listitem>
  98
  99         <listitem>
 100           <para>Inclusion in the file <emphasis role="bold">/usr/afs/etc/UserList</emphasis> on the local disk of each AFS server
 101           machine in the cell. See <link linkend="HDRWQ592">Administering the UserList File</link>.</para>
 102         </listitem>
 103       </itemizedlist></para>
 104
 105     <para>This section describes the three privileges and explains why more than one privilege is necessary.</para>
 106
 107     <note>
 108       <para>Never grant any administrative privilege to the user <emphasis role="bold">anonymous</emphasis>, even when a server
 109       outage makes it impossible to mutually authenticate. If you grant such privilege, then any user who can access a machine in
 110       your cell can issue privileged commands. The alternative solution is to put the affected server machine into no-authentication
 111       mode and use the <emphasis role="bold">-noauth</emphasis> flag available on many commands to prevent mutual authentication
 112       attempts. For further discussion, see <link linkend="HDRWQ123">Managing Authentication and Authorization
 113       Requirements</link>.</para>
 114     </note>
 115
 116     <sect2 id="HDRWQ585">
 117       <title>The Reason for Separate Privileges</title>
 118
 119       <para>Often, a cell's administrators require full administrative privileges to perform their jobs effectively. However,
 120       separating the three types of privilege makes it possible to grant only the minimum set of privileges that a given
 121       administrator needs to complete his or her work.</para>
 122
 123       <para>The <emphasis role="bold">system:administrators</emphasis> group privilege is perhaps the most basic, and most
 124       frequently used during normal operation (when all the servers are running normally). When the Protection Database is
 125       unavailable due to machine or server outage, it is not possible to issue commands that require this type of privilege.</para>
 126
 127       <para>The <computeroutput>ADMIN</computeroutput> flag privilege is separate because of the extreme sensitivity of the
 128       information in the Authentication Database, especially the server encryption key in the <emphasis role="bold">afs</emphasis>
 129       entry. When the Authentication Database is unavailable due to machine or server outage, it is not possible to issue commands
 130       that require this type of privilege.</para>
 131
 132       <para>The ability to issue privileged <emphasis role="bold">bos</emphasis> and <emphasis role="bold">vos</emphasis> command is
 133       recorded in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file on the local disk of each AFS server machine
 134       rather than in a database, so that in case of serious server or network problems administrators can still log onto server
 135       machines and use those commands while solving the problem.</para>
 136     </sect2>
 137   </sect1>
 138
 139   <sect1 id="HDRWQ586">
 140     <title>Administering the system:administrators Group</title>
 141
 142     <indexterm>
 143       <primary>pts commands</primary>
 144
 145       <secondary>granting privilege for</secondary>
 146     </indexterm>
 147
 148     <indexterm>
 149       <primary>fs commands</primary>
 150
 151       <secondary>granting privilege for</secondary>
 152     </indexterm>
 153
 154     <indexterm>
 155       <primary>privilege</primary>
 156
 157       <secondary>granting for pts commands</secondary>
 158     </indexterm>
 159
 160     <indexterm>
 161       <primary>privilege</primary>
 162
 163       <secondary>granting for fs commands</secondary>
 164     </indexterm>
 165
 166     <indexterm>
 167       <primary>granting</primary>
 168
 169       <secondary>privilege for fs commands</secondary>
 170     </indexterm>
 171
 172     <indexterm>
 173       <primary>granting</primary>
 174
 175       <secondary>privilege for pts commands</secondary>
 176     </indexterm>
 177
 178     <indexterm>
 179       <primary>system:administrators group</primary>
 180
 181       <secondary>privileges resulting</secondary>
 182     </indexterm>
 183
 184     <para>The first type of AFS administrative privilege is membership . Members of the <emphasis
 185     role="bold">system:administrators</emphasis> group in the Protection Database have the following privileges: <itemizedlist>
 186         <listitem>
 187           <para>Permission to issue all <emphasis role="bold">pts</emphasis> commands, which are used to administer the Protection
 188           Database. See <link linkend="HDRWQ531">Administering the Protection Database</link>.</para>
 189         </listitem>
 190
 191         <listitem>
 192           <para>Permission to issue the <emphasis role="bold">fs setvol</emphasis> and <emphasis role="bold">fs setquota</emphasis>
 193           commands, which set the space quota on volumes as described in <link linkend="HDRWQ234">Setting and Displaying Volume
 194           Quota and Current Size</link>.</para>
 195         </listitem>
 196
 197         <listitem>
 198           <para>Implicit <emphasis role="bold">a</emphasis> (<emphasis role="bold">administer</emphasis>) and by default <emphasis
 199           role="bold">l</emphasis> (<emphasis role="bold">lookup</emphasis>) permissions on the access control list (ACL) on every
 200           directory in the cell's AFS filespace. Members of the group can use the <emphasis role="bold">fs setacl</emphasis> command
 201           to grant themselves any other permissions they require, as described in <link linkend="HDRWQ573">Setting ACL
 202           Entries</link>.</para>
 203
 204           <para>You can change the ACL permissions that the File Server on a given file server machine implicitly grants to the
 205           members of the <emphasis role="bold">system:administrators</emphasis> group for the data in volumes that it houses. When
 206           you issue the <emphasis role="bold">bos create</emphasis> command to create and start the <emphasis
 207           role="bold">fs</emphasis> process on the machine, include the <emphasis role="bold">-implicit</emphasis> argument to the
 208           <emphasis role="bold">fileserver</emphasis> initialization command. For syntax details, see the <emphasis
 209           role="bold">fileserver</emphasis> reference page in the <emphasis>OpenAFS Administration Reference</emphasis>. You can
 210           grant additional permissions, or remove the <emphasis role="bold">l</emphasis> permission. However, the File Server always
 211           implicitly grants the <emphasis role="bold">a</emphasis> permission to members of the group, even if you set the value of
 212           the <emphasis role="bold">-implicit</emphasis> argument to <emphasis role="bold">none</emphasis>.</para>
 213         </listitem>
 214       </itemizedlist></para>
 215
 216     <indexterm>
 217       <primary>system:administrators group</primary>
 218
 219       <secondary>members</secondary>
 220
 221       <tertiary>displaying</tertiary>
 222     </indexterm>
 223
 224     <indexterm>
 225       <primary>displaying</primary>
 226
 227       <secondary>system:administrators group members</secondary>
 228     </indexterm>
 229
 230     <indexterm>
 231       <primary>pts commands</primary>
 232
 233       <secondary>membership</secondary>
 234
 235       <tertiary>displaying system:administrators group</tertiary>
 236     </indexterm>
 237
 238     <indexterm>
 239       <primary>commands</primary>
 240
 241       <secondary>pts membership</secondary>
 242
 243       <tertiary>displaying system:administrators group</tertiary>
 244     </indexterm>
 245
 246     <sect2 id="HDRWQ587">
 247       <title>To display the members of the system:administrators group</title>
 248
 249       <orderedlist>
 250         <listitem>
 251           <para>Issue the <emphasis role="bold">pts membership</emphasis> command to display the <emphasis
 252           role="bold">system:administrators</emphasis> group's list of members. Any user can issue this command as long as the first
 253           privacy flag on the <emphasis role="bold">system:administrators</emphasis> group's Protection Database entry is not
 254           changed from the default value of uppercase <computeroutput>S</computeroutput>. <programlisting>
 255    % <emphasis role="bold">pts membership system:administrators</emphasis>
 256 </programlisting></para>
 257
 258           <para>where <emphasis role="bold">m</emphasis> is the shortest acceptable abbreviation of <emphasis
 259           role="bold">membership</emphasis>.</para>
 260         </listitem>
 261       </orderedlist>
 262     </sect2>
 263
 264     <sect2 id="Header_657">
 265       <title>To add users to the system:administrators group</title>
 266
 267       <indexterm>
 268         <primary>system:administrators group</primary>
 269
 270         <secondary>members</secondary>
 271
 272         <tertiary>adding</tertiary>
 273       </indexterm>
 274
 275       <indexterm>
 276         <primary>adding</primary>
 277
 278         <secondary>system:administrators group members</secondary>
 279       </indexterm>
 280
 281       <indexterm>
 282         <primary>pts commands</primary>
 283
 284         <secondary>adduser</secondary>
 285
 286         <tertiary>for system:administrators group</tertiary>
 287       </indexterm>
 288
 289       <indexterm>
 290         <primary>commands</primary>
 291
 292         <secondary>pts adduser</secondary>
 293
 294         <tertiary>for system:administrators group</tertiary>
 295       </indexterm>
 296
 297       <orderedlist>
 298         <listitem>
 299           <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
 300           <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
 301           the members of the system:administrators group</link>. <programlisting>
 302    % <emphasis role="bold">pts membership system:administrators</emphasis>
 303 </programlisting></para>
 304         </listitem>
 305
 306         <listitem>
 307           <para>Issue the <emphasis role="bold">pts adduser</emphasis> group to add one or more users. <programlisting>
 308    % <emphasis role="bold">pts adduser -user</emphasis> &lt;<replaceable>user name</replaceable>&gt;+ <emphasis role="bold">-group system:administrators</emphasis>
 309 </programlisting></para>
 310
 311           <para>where <variablelist>
 312               <varlistentry>
 313                 <term><emphasis role="bold">ad</emphasis></term>
 314
 315                 <listitem>
 316                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">adduser</emphasis>.</para>
 317                 </listitem>
 318               </varlistentry>
 319
 320               <varlistentry>
 321                 <term><emphasis role="bold">-user</emphasis></term>
 322
 323                 <listitem>
 324                   <para>Names each user to add to the <emphasis role="bold">system:administrators</emphasis> group.</para>
 325                 </listitem>
 326               </varlistentry>
 327             </variablelist></para>
 328         </listitem>
 329       </orderedlist>
 330     </sect2>
 331
 332     <sect2 id="HDRWQ588">
 333       <title>To remove users from the system:administrators group</title>
 334
 335       <indexterm>
 336         <primary>system:administrators group</primary>
 337
 338         <secondary>members</secondary>
 339
 340         <tertiary>removing</tertiary>
 341       </indexterm>
 342
 343       <indexterm>
 344         <primary>removing</primary>
 345
 346         <secondary>system:administrators group members</secondary>
 347       </indexterm>
 348
 349       <indexterm>
 350         <primary>pts commands</primary>
 351
 352         <secondary>removeuser</secondary>
 353
 354         <tertiary>for system:administrators group</tertiary>
 355       </indexterm>
 356
 357       <indexterm>
 358         <primary>commands</primary>
 359
 360         <secondary>pts removeuser</secondary>
 361
 362         <tertiary>for system:administrators group</tertiary>
 363       </indexterm>
 364
 365       <orderedlist>
 366         <listitem>
 367           <para>Verify that you belong to the <emphasis role="bold">system:administrators</emphasis> group. If necessary, issue the
 368           <emphasis role="bold">pts membership</emphasis> command, which is fully described in <link linkend="HDRWQ587">To display
 369           the members of the system:administrators group</link>. <programlisting>
 370    % <emphasis role="bold">pts membership system:administrators</emphasis>
 371 </programlisting></para>
 372         </listitem>
 373
 374         <listitem>
 375           <para>Issue the <emphasis role="bold">pts removeuser</emphasis> command to remove one or more users. <programlisting>
 376    % <emphasis role="bold">pts removeuser -user</emphasis> &lt;<replaceable>user name</replaceable>&gt;+ <emphasis role="bold">-group system:administrators</emphasis>
 377 </programlisting></para>
 378
 379           <para>where <variablelist>
 380               <varlistentry>
 381                 <term><emphasis role="bold">rem</emphasis></term>
 382
 383                 <listitem>
 384                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">removeuser</emphasis>.</para>
 385                 </listitem>
 386               </varlistentry>
 387
 388               <varlistentry>
 389                 <term><emphasis role="bold">-user</emphasis></term>
 390
 391                 <listitem>
 392                   <para>Names each user to remove from the <emphasis role="bold">system:administrators</emphasis> group.</para>
 393                 </listitem>
 394               </varlistentry>
 395             </variablelist></para>
 396         </listitem>
 397       </orderedlist>
 398     </sect2>
 399   </sect1>
 400
 401   <sect1 id="HDRWQ589">
 402     <title>Granting Privilege for kas Commands: the ADMIN Flag</title>
 403
 404     <indexterm>
 405       <primary>ADMIN flag in Authentication Database entry</primary>
 406
 407       <secondary>privileges resulting</secondary>
 408     </indexterm>
 409
 410     <para>Administrators who have the <computeroutput>ADMIN</computeroutput> flag on their Authentication Database entry can issue
 411     all <emphasis role="bold">kas</emphasis> commands, which enable them to administer the Authentication Database. <indexterm>
 412         <primary>kas commands</primary>
 413
 414         <secondary>granting privilege for</secondary>
 415       </indexterm> <indexterm>
 416         <primary>privilege</primary>
 417
 418         <secondary>granting for kas commands</secondary>
 419       </indexterm> <indexterm>
 420         <primary>granting</primary>
 421
 422         <secondary>privilege for kas commands</secondary>
 423       </indexterm></para>
 424
 425     <sect2 id="HDRWQ590">
 426       <title>To check if the ADMIN flag is set</title>
 427
 428       <indexterm>
 429         <primary>ADMIN flag in Authentication Database entry</primary>
 430
 431         <secondary>displaying</secondary>
 432       </indexterm>
 433
 434       <indexterm>
 435         <primary>displaying</primary>
 436
 437         <secondary>ADMIN flag in Authentication Database entry</secondary>
 438       </indexterm>
 439
 440       <indexterm>
 441         <primary>kas commands</primary>
 442
 443         <secondary>examine</secondary>
 444
 445         <tertiary>to display ADMIN flag</tertiary>
 446       </indexterm>
 447
 448       <indexterm>
 449         <primary>commands</primary>
 450
 451         <secondary>kas examine</secondary>
 452
 453         <tertiary>to display ADMIN flag</tertiary>
 454       </indexterm>
 455
 456       <orderedlist>
 457         <listitem>
 458           <para>Issue the <emphasis role="bold">kas examine</emphasis> command to display an entry from the
 459           Authentication Database.</para>
 460
 461           <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
 462           it authenticates your local (UFS) identity, which possibly does not correspond to an AFS-privileged administrator. Include
 463           the <emphasis role="bold">-admin_username</emphasis> argument (here abbreviated to <emphasis
 464           role="bold">-admin</emphasis>) to name a user identity that has the <computeroutput>ADMIN</computeroutput> flag on its
 465           Authentication Database entry.</para>
 466
 467           <programlisting>
 468    % <emphasis role="bold">kas examine</emphasis> &lt;<replaceable>name of user</replaceable>&gt;   \
 469                  <emphasis role="bold">-admin</emphasis>  &lt;<replaceable>admin principal to use for authentication</replaceable>&gt;
 470    Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
 471 </programlisting>
 472
 473           <para>where <variablelist>
 474               <varlistentry>
 475                 <term><emphasis role="bold">e</emphasis></term>
 476
 477                 <listitem>
 478                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">examine</emphasis>.</para>
 479                 </listitem>
 480               </varlistentry>
 481
 482               <varlistentry>
 483                 <term><emphasis role="bold">name of user</emphasis></term>
 484
 485                 <listitem>
 486                   <para>Names the entry to display.</para>
 487                 </listitem>
 488               </varlistentry>
 489
 490               <varlistentry>
 491                 <term><emphasis role="bold">-admin</emphasis></term>
 492
 493                 <listitem>
 494                   <para>Names an administrative account with the <computeroutput>ADMIN</computeroutput> flag on its Authentication
 495                   Database entry, such as the <emphasis role="bold">admin</emphasis> account. The password prompt echoes it as
 496                   admin_user. Enter the appropriate password as admin_password.</para>
 497                 </listitem>
 498               </varlistentry>
 499             </variablelist></para>
 500         </listitem>
 501       </orderedlist>
 502
 503       <para>If the <computeroutput>ADMIN</computeroutput> flag is turned on, it appears on the first line, as in this
 504       example:</para>
 505
 506       <programlisting>
 507    % <emphasis role="bold">kas e terry -admin admin</emphasis>
 508    Administrator's (admin) password: &lt;<replaceable>admin_password</replaceable>&gt;
 509    User data for terry (ADMIN)
 510      key version is 0, etc...
 511 </programlisting>
 512
 513       <indexterm>
 514         <primary>commands</primary>
 515
 516         <secondary>kas setfields</secondary>
 517
 518         <tertiary>setting ADMIN flag</tertiary>
 519       </indexterm>
 520
 521       <indexterm>
 522         <primary>kas commands</primary>
 523
 524         <secondary>setfields</secondary>
 525
 526         <tertiary>setting ADMIN flag</tertiary>
 527       </indexterm>
 528
 529       <indexterm>
 530         <primary>ADMIN flag in Authentication Database entry</primary>
 531
 532         <secondary>setting or removing</secondary>
 533       </indexterm>
 534
 535       <indexterm>
 536         <primary>adding</primary>
 537
 538         <secondary>ADMIN flag to Authentication Database entry</secondary>
 539       </indexterm>
 540
 541       <indexterm>
 542         <primary>setting</primary>
 543
 544         <secondary>ADMIN flag in Authentication Database entry</secondary>
 545       </indexterm>
 546
 547       <indexterm>
 548         <primary>removing</primary>
 549
 550         <secondary>ADMIN flag from Authentication Database entry</secondary>
 551       </indexterm>
 552     </sect2>
 553
 554     <sect2 id="Header_661">
 555       <title>To set or remove the ADMIN flag</title>
 556
 557       <orderedlist>
 558         <listitem>
 559           <para>Issue the <emphasis role="bold">kas setfields</emphasis> command to turn on the
 560           <computeroutput>ADMIN</computeroutput> flag in an Authentication Database entry.</para>
 561
 562           <para>The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default,
 563           it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator.
 564           Include the <emphasis role="bold">-admin</emphasis> argument to name an identity that has the
 565           <computeroutput>ADMIN</computeroutput> flag on its Authentication Database entry. To verify that an entry has the flag,
 566           issue the <emphasis role="bold">kas examine</emphasis> command as described in <link linkend="HDRWQ590">To check if the
 567           ADMIN flag is set</link>.</para>
 568
 569           <para>The following command appears on two lines only for legibility.</para>
 570
 571           <programlisting>
 572     % <emphasis role="bold">kas setfields</emphasis> &lt;<replaceable>name of user</replaceable>&gt;  {<emphasis role="bold">ADMIN</emphasis> |  <emphasis
 573               role="bold">NOADMIN</emphasis>} \
 574                    <emphasis role="bold">-admin</emphasis> &lt;<replaceable>admin principal to use for authentication</replaceable>&gt;
 575     Administrator's (admin_user) password: &lt;<replaceable>admin_password</replaceable>&gt;
 576 </programlisting>
 577
 578           <para>where <variablelist>
 579               <varlistentry>
 580                 <term><emphasis role="bold">sf</emphasis></term>
 581
 582                 <listitem>
 583                   <para>Is an alias for <emphasis role="bold">setfields</emphasis> (and <emphasis role="bold">setf</emphasis> is the
 584                   shortest acceptable abbreviation).</para>
 585                 </listitem>
 586               </varlistentry>
 587
 588               <varlistentry>
 589                 <term><emphasis role="bold">name of user</emphasis></term>
 590
 591                 <listitem>
 592                   <para>Names the entry for which to set or remove the <computeroutput>ADMIN</computeroutput> flag.</para>
 593                 </listitem>
 594               </varlistentry>
 595
 596               <varlistentry>
 597                 <term><emphasis role="bold">ADMIN | NOADMIN</emphasis></term>
 598
 599                 <listitem>
 600                   <para>Sets or removes the <computeroutput>ADMIN</computeroutput> flag, respectively.</para>
 601                 </listitem>
 602               </varlistentry>
 603
 604               <varlistentry>
 605                 <term><emphasis role="bold">-admin</emphasis></term>
 606
 607                 <listitem>
 608                   <para>Names an administrative account with the <computeroutput>ADMIN</computeroutput> flag on its Authentication
 609                   Database entry, such as the <emphasis role="bold">admin</emphasis> account. The password prompt echoes it as
 610                   admin_user. Enter the appropriate password as admin_password.</para>
 611                 </listitem>
 612               </varlistentry>
 613             </variablelist></para>
 614         </listitem>
 615       </orderedlist>
 616     </sect2>
 617   </sect1>
 618
 619   <sect1 id="HDRWQ592">
 620     <title>Administering the UserList File</title>
 621
 622     <indexterm>
 623       <primary>UserList file</primary>
 624
 625       <secondary>privileges resulting</secondary>
 626     </indexterm>
 627
 628     <para>Inclusion in the file <emphasis role="bold">/usr/afs/etc/UserList</emphasis> on the local disk of each AFS server machine
 629     enables an administrator to issue commands from the indicated suites. <itemizedlist>
 630         <listitem>
 631           <para>The <emphasis role="bold">bos</emphasis> commands enable the administrator to manage server processes and the server
 632           configuration files that define the cell's database server machines, server encryption keys, and privileged users. See
 633           <link linkend="HDRWQ80">Administering Server Machines</link> and <link linkend="HDRWQ142">Monitoring and Controlling
 634           Server Processes</link>.</para>
 635         </listitem>
 636
 637         <listitem>
 638           <para>The <emphasis role="bold">vos</emphasis> commands enable the administrator to manage volumes and the Volume Location
 639           Database (VLDB). See <link linkend="HDRWQ174">Managing Volumes</link>.</para>
 640         </listitem>
 641
 642         <listitem>
 643           <para>The <emphasis role="bold">backup</emphasis> commands enable the administrator to use the AFS Backup System to copy
 644           data to permanent storage. See <link linkend="HDRWQ248">Configuring the AFS Backup System</link> and <link
 645           linkend="HDRWQ283">Backing Up and Restoring AFS Data</link>.</para>
 646         </listitem>
 647       </itemizedlist></para>
 648
 649     <indexterm>
 650       <primary>granting</primary>
 651
 652       <secondary>privilege for kas commands</secondary>
 653     </indexterm>
 654
 655     <indexterm>
 656       <primary>bos commands</primary>
 657
 658       <secondary>granting privilege for</secondary>
 659     </indexterm>
 660
 661     <indexterm>
 662       <primary>vos commands</primary>
 663
 664       <secondary>granting privilege for</secondary>
 665     </indexterm>
 666
 667     <indexterm>
 668       <primary>backup commands</primary>
 669
 670       <secondary>granting privilege for</secondary>
 671     </indexterm>
 672
 673     <indexterm>
 674       <primary>privilege</primary>
 675
 676       <secondary>granting for bos commands</secondary>
 677     </indexterm>
 678
 679     <indexterm>
 680       <primary>privilege</primary>
 681
 682       <secondary>granting for vos commands</secondary>
 683     </indexterm>
 684
 685     <indexterm>
 686       <primary>privilege</primary>
 687
 688       <secondary>granting for backup commands</secondary>
 689     </indexterm>
 690
 691     <indexterm>
 692       <primary>granting</primary>
 693
 694       <secondary>privilege for bos commands</secondary>
 695     </indexterm>
 696
 697     <indexterm>
 698       <primary>granting</primary>
 699
 700       <secondary>privilege for vos commands</secondary>
 701     </indexterm>
 702
 703     <indexterm>
 704       <primary>granting</primary>
 705
 706       <secondary>privilege for backup commands</secondary>
 707     </indexterm>
 708
 709     <para>Although each AFS server machine maintains a separate copy of the file on its local disk, it is conventional to keep all
 710     copies the same. It can be confusing for an administrator to have the privilege on some machines but not others. <indexterm>
 711         <primary>system control machine</primary>
 712
 713         <secondary>as distributor of UserList file</secondary>
 714       </indexterm></para>
 715
 716     <para>If your cell runs the United States edition of AFS and uses the Update Server to distribute the contents of the system
 717     control machine's <emphasis role="bold">/usr/afs/etc</emphasis> directory, then edit only the copy of the <emphasis
 718     role="bold">UserList</emphasis> file stored on the system control machine. If you have forgotten which machine is the system
 719     control machine, see <link linkend="HDRWQ90">The Four Roles for File Server Machines</link>.</para>
 720
 721     <para>If your cell runs the international edition of AFS, or does not use a system control machine, then you must edit the
 722     <emphasis role="bold">UserList</emphasis> file on each server machine individually.</para>
 723
 724     <para>To avoid making formatting errors that can result in performance problems, never edit the <emphasis
 725     role="bold">UserList</emphasis> file directly. Instead, use the <emphasis role="bold">bos adduser</emphasis> or <emphasis
 726     role="bold">bos removeuser</emphasis> commands as described in this section. <indexterm>
 727         <primary>UserList file</primary>
 728
 729         <secondary>displaying</secondary>
 730       </indexterm> <indexterm>
 731         <primary>displaying</primary>
 732
 733         <secondary>UserList file</secondary>
 734       </indexterm> <indexterm>
 735         <primary>bos commands</primary>
 736
 737         <secondary>listusers</secondary>
 738       </indexterm> <indexterm>
 739         <primary>commands</primary>
 740
 741         <secondary>bos listusers</secondary>
 742       </indexterm></para>
 743
 744     <sect2 id="HDRWQ593">
 745       <title>To display the users in the UserList file</title>
 746
 747       <orderedlist>
 748         <listitem>
 749           <para>Issue the <emphasis role="bold">bos listusers</emphasis> command to display the contents of the <emphasis
 750           role="bold">/usr/afs/etc/UserList</emphasis> file. <programlisting>
 751    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
 752 </programlisting></para>
 753
 754           <para>where <variablelist>
 755               <varlistentry>
 756                 <term><emphasis role="bold">listu</emphasis></term>
 757
 758                 <listitem>
 759                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">listusers</emphasis>.</para>
 760                 </listitem>
 761               </varlistentry>
 762
 763               <varlistentry>
 764                 <term><emphasis role="bold">machine name</emphasis></term>
 765
 766                 <listitem>
 767                   <para>Names an AFS server machine. In the normal case, any machine is acceptable because the file is the same on
 768                   all of them.</para>
 769                 </listitem>
 770               </varlistentry>
 771             </variablelist></para>
 772         </listitem>
 773       </orderedlist>
 774     </sect2>
 775
 776     <sect2 id="HDRWQ594">
 777       <title>To add users to the UserList file</title>
 778
 779       <indexterm>
 780         <primary>UserList file</primary>
 781
 782         <secondary>adding users</secondary>
 783       </indexterm>
 784
 785       <indexterm>
 786         <primary>adding</primary>
 787
 788         <secondary>UserList file users</secondary>
 789       </indexterm>
 790
 791       <indexterm>
 792         <primary>bos commands</primary>
 793
 794         <secondary>adduser</secondary>
 795       </indexterm>
 796
 797       <indexterm>
 798         <primary>commands</primary>
 799
 800         <secondary>bos adduser</secondary>
 801       </indexterm>
 802
 803       <orderedlist>
 804         <listitem>
 805           <para>Verify you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If not, you must have a
 806           qualified administrator add you before you can add entries to it yourself. If necessary, issue the <emphasis
 807           role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the users in
 808           the UserList file</link>. <programlisting>
 809    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
 810 </programlisting></para>
 811         </listitem>
 812
 813         <listitem>
 814           <para>Issue the <emphasis role="bold">bos adduser</emphasis> command to add one or more users to the <emphasis
 815           role="bold">UserList</emphasis> file. <programlisting>
 816    % <emphasis role="bold">bos adduser</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>user names</replaceable>&gt;+
 817 </programlisting></para>
 818
 819           <para>where <variablelist>
 820               <varlistentry>
 821                 <term><emphasis role="bold">addu</emphasis></term>
 822
 823                 <listitem>
 824                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">adduser</emphasis>.</para>
 825                 </listitem>
 826               </varlistentry>
 827
 828               <varlistentry>
 829                 <term><emphasis role="bold">machine name</emphasis></term>
 830
 831                 <listitem>
 832                   <para>Names the system control machine if you use the Update Server to distribute the contents of the <emphasis
 833                   role="bold">/usr/afs/etc</emphasis> directory (possible only in cells running the United States edition of AFS).
 834                   By default, it can take up to five minutes for the Update Server to distribute the changes, so newly added users
 835                   must wait that long before attempting to issue privileged commands.</para>
 836
 837                   <para>If you are running the international edition of AFS, or do not use the Update Server, repeat the command,
 838                   substituting the name of each AFS server machine for machine name in turn.</para>
 839                 </listitem>
 840               </varlistentry>
 841
 842               <varlistentry>
 843                 <term><emphasis role="bold">user names</emphasis></term>
 844
 845                 <listitem>
 846                   <para>Specifies the username of each administrator to add to the <emphasis role="bold">UserList</emphasis>
 847                   file.</para>
 848                 </listitem>
 849               </varlistentry>
 850             </variablelist></para>
 851         </listitem>
 852       </orderedlist>
 853     </sect2>
 854
 855     <sect2 id="Header_665">
 856       <title>To remove users from the UserList file</title>
 857
 858       <indexterm>
 859         <primary>UserList file</primary>
 860
 861         <secondary>removing users</secondary>
 862       </indexterm>
 863
 864       <indexterm>
 865         <primary>removing</primary>
 866
 867         <secondary>UserList file users</secondary>
 868       </indexterm>
 869
 870       <indexterm>
 871         <primary>bos commands</primary>
 872
 873         <secondary>removeuser</secondary>
 874       </indexterm>
 875
 876       <indexterm>
 877         <primary>commands</primary>
 878
 879         <secondary>bos removeuser</secondary>
 880       </indexterm>
 881
 882       <orderedlist>
 883         <listitem>
 884           <para>Verify you are listed in the <emphasis role="bold">/usr/afs/etc/UserList</emphasis> file. If not, you must have a
 885           qualified administrator add you before you can remove entries from it yourself. If necessary, issue the <emphasis
 886           role="bold">bos listusers</emphasis> command, which is fully described in <link linkend="HDRWQ593">To display the users in
 887           the UserList file</link>. <programlisting>
 888    % <emphasis role="bold">bos listusers</emphasis> &lt;<replaceable>machine name</replaceable>&gt;
 889 </programlisting></para>
 890         </listitem>
 891
 892         <listitem>
 893           <para>Issue the <emphasis role="bold">bos removeuser</emphasis> command to remove one or more users from the <emphasis
 894           role="bold">UserList</emphasis> file. <programlisting>
 895    % <emphasis role="bold">bos removeuser</emphasis> &lt;<replaceable>machine name</replaceable>&gt; &lt;<replaceable>user names</replaceable>&gt;+
 896 </programlisting></para>
 897
 898           <para>where <variablelist>
 899               <varlistentry>
 900                 <term><emphasis role="bold">removeu</emphasis></term>
 901
 902                 <listitem>
 903                   <para>Is the shortest acceptable abbreviation of <emphasis role="bold">removeuser</emphasis>.</para>
 904                 </listitem>
 905               </varlistentry>
 906
 907               <varlistentry>
 908                 <term><emphasis role="bold">machine name</emphasis></term>
 909
 910                 <listitem>
 911                   <para>Names the system control machine if you use the Update Server to distribute the contents of the <emphasis
 912                   role="bold">/usr/afs/etc</emphasis> directory (possible only in cells running the United States edition of AFS).
 913                   By default, it can take up to five minutes for the Update Server to distribute the change, so newly removed users
 914                   can continue to issue privileged commands during that time.</para>
 915
 916                   <para>If you are running the international edition of AFS, or do not use the Update Server, repeat the command,
 917                   substituting the name of each AFS server machine for machine name in turn.</para>
 918                 </listitem>
 919               </varlistentry>
 920
 921               <varlistentry>
 922                 <term><emphasis role="bold">user names</emphasis></term>
 923
 924                 <listitem>
 925                   <para>Specifies the username of each administrator to add to the <emphasis role="bold">UserList</emphasis>
 926                   file.</para>
 927                 </listitem>
 928               </varlistentry>
 929             </variablelist></para>
 930         </listitem>
 931       </orderedlist>
 932     </sect2>
 933   </sect1>
 934 </chapter>