Chapter 16. Managing Administrative Privilege

This chapter explains how to enable system administrators and operators to perform privileged AFS operations.

Summary of Instructions

This chapter explains how to perform the following tasks by using the indicated commands:

Display members of system:administrators grouppts membership
Add user to system:administrators grouppts adduser
Remove user from system:administrators grouppts removeuser
Display ADMIN flag in Authentication Database entrykas examine
Set or remove ADMIN flag on Authentication Database entrykas setfields
Display users in UserList filebos listusers
Add user to UserList filebos adduser
Remove user from UserList filebos removeuser

An Overview of Administrative Privilege

A fully privileged AFS system administrator has the following characteristics:

This section describes the three privileges and explains why more than one privilege is necessary.

Note: Never grant any administrative privilege to the user anonymous, even when a server outage makes it impossible to mutually authenticate. If you grant such privilege, then any user who can access a machine in your cell can issue privileged commands. The alternative solution is to put the affected server machine into no-authentication mode and use the -noauth flag available on many commands to prevent mutual authentication attempts. For further discussion, see Managing Authentication and Authorization Requirements.

The Reason for Separate Privileges

Often, a cell's administrators require full administrative privileges to perform their jobs effectively. However, separating the three types of privilege makes it possible to grant only the minimum set of privileges that a given administrator needs to complete his or her work.

The system:administrators group privilege is perhaps the most basic, and most frequently used during normal operation (when all the servers are running normally). When the Protection Database is unavailable due to machine or server outage, it is not possible to issue commands that require this type of privilege.

The ADMIN flag privilege is separate because of the extreme sensitivity of the information in the Authentication Database, especially the server encryption key in the afs entry. When the Authentication Database is unavailable due to machine or server outage, it is not possible to issue commands that require this type of privilege.

The ability to issue privileged bos and vos command is recorded in the /usr/afs/etc/UserList file on the local disk of each AFS server machine rather than in a database, so that in case of serious server or network problems administrators can still log onto server machines and use those commands while solving the problem.

Administering the system:administrators Group

The first type of AFS administrative privilege is membership . Members of the system:administrators group in the Protection Database have the following privileges:

To display the members of the system:administrators group

  1. Issue the pts membership command to display the system:administrators group's list of members. Any user can issue this command as long as the first privacy flag on the system:administrators group's Protection Database entry is not changed from the default value of uppercase S.

    
   % pts membership system:administrators
    

    where m is the shortest acceptable abbreviation of membership.

To add users to the system:administrators group

  1. Verify that you belong to the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

    
   % pts membership system:administrators
    

  2. Issue the pts adduser group to add one or more users.

    
   % pts adduser -user <user name>+ -group system:administrators
    

    where

    ad

    Is the shortest acceptable abbreviation of adduser.

    -user

    Names each user to add to the system:administrators group.

To remove users from the system:administrators group

  1. Verify that you belong to the system:administrators group. If necessary, issue the pts membership command, which is fully described in To display the members of the system:administrators group.

    
   % pts membership system:administrators
    

  2. Issue the pts removeuser command to remove one or more users.

    
   % pts removeuser -user <user name>+ -group system:administrators
    

    where

    rem

    Is the shortest acceptable abbreviation of removeuser.

    -user

    Names each user to remove from the system:administrators group.

Granting Privilege for kas Commands: the ADMIN Flag

Administrators who have the ADMIN flag on their Authentication Database entry can issue all kas commands, which enable them to administer the Authentication Database.

To check if the ADMIN flag is set

  1. Issue the kas examine command to display an entry from the Authentication Database.

    The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UFS) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin_username argument (here abbreviated to -admin) to name a user identity that has the ADMIN flag on its Authentication Database entry.

    
   % kas examine <name of user>   \
                     -admin  <admin principal to use for authentication>
       Administrator's (admin_user) password: <admin_password>
    

    where

    e

    Is the shortest acceptable abbreviation of examine.

    name of user

    Names the entry to display.

    -admin

    Names an administrative account with the ADMIN flag on its Authentication Database entry, such as the admin account. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

If the ADMIN flag is turned on, it appears on the first line, as in this example:


   % kas e terry -admin admin
   Administrator's (admin) password: <admin_password>
   User data for terry (ADMIN)
     key version is 0, etc...

To set or remove the ADMIN flag

  1. Issue the kas setfields command to turn on the ADMIN flag in an Authentication Database entry.

    The Authentication Server performs its own authentication rather than accepting your existing AFS token. By default, it authenticates your local (UNIX) identity, which possibly does not correspond to an AFS-privileged administrator. Include the -admin argument to name an identity that has the ADMIN flag on its Authentication Database entry. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.

    The following command appears on two lines only for legibility.

    
    % kas setfields <name of user>  {ADMIN |  NOADMIN} \  
                       -admin <admin principal to use for authentication>  
        Administrator's (admin_user) password: <admin_password>
    

    where

    sf

    Is an alias for setfields (and setf is the shortest acceptable abbreviation).

    name of user

    Names the entry for which to set or remove the ADMIN flag.

    ADMIN | NOADMIN

    Sets or removes the ADMIN flag, respectively.

    -admin

    Names an administrative account with the ADMIN flag on its Authentication Database entry, such as the admin account. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

Administering the UserList File

Inclusion in the file /usr/afs/etc/UserList on the local disk of each AFS server machine enables an administrator to issue commands from the indicated suites.

Although each AFS server machine maintains a separate copy of the file on its local disk, it is conventional to keep all copies the same. It can be confusing for an administrator to have the privilege on some machines but not others.

If your cell runs the United States edition of AFS and uses the Update Server to distribute the contents of the system control machine's /usr/afs/etc directory, then edit only the copy of the UserList file stored on the system control machine. If you have forgotten which machine is the system control machine, see The Four Roles for File Server Machines.

If your cell runs the international edition of AFS, or does not use a system control machine, then you must edit the UserList file on each server machine individually.

To avoid making formatting errors that can result in performance problems, never edit the UserList file directly. Instead, use the bos adduser or bos removeuser commands as described in this section.

To display the users in the UserList file

  1. Issue the bos listusers command to display the contents of the /usr/afs/etc/UserList file.

    
   % bos listusers <machine name>
    

    where

    listu

    Is the shortest acceptable abbreviation of listusers.

    machine name

    Names an AFS server machine. In the normal case, any machine is acceptable because the file is the same on all of them.

To add users to the UserList file

  1. Verify you are listed in the /usr/afs/etc/UserList file. If not, you must have a qualified administrator add you before you can add entries to it yourself. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

    
   % bos listusers <machine name>
    

  2. Issue the bos adduser command to add one or more users to the UserList file.

    
   % bos adduser <machine name> <user names>+
    

    where

    addu

    Is the shortest acceptable abbreviation of adduser.

    machine name

    Names the system control machine if you use the Update Server to distribute the contents of the /usr/afs/etc directory (possible only in cells running the United States edition of AFS). By default, it can take up to five minutes for the Update Server to distribute the changes, so newly added users must wait that long before attempting to issue privileged commands.

    If you are running the international edition of AFS, or do not use the Update Server, repeat the command, substituting the name of each AFS server machine for machine name in turn.

    user names

    Specifies the username of each administrator to add to the UserList file.

To remove users from the UserList file

  1. Verify you are listed in the /usr/afs/etc/UserList file. If not, you must have a qualified administrator add you before you can remove entries from it yourself. If necessary, issue the bos listusers command, which is fully described in To display the users in the UserList file.

    
   % bos listusers <machine name>
    

  2. Issue the bos removeuser command to remove one or more users from the UserList file.

    
   % bos removeuser <machine name> <user names>+
    

    where

    removeu

    Is the shortest acceptable abbreviation of removeuser.

    machine name

    Names the system control machine if you use the Update Server to distribute the contents of the /usr/afs/etc directory (possible only in cells running the United States edition of AFS). By default, it can take up to five minutes for the Update Server to distribute the change, so newly removed users can continue to issue privileged commands during that time.

    If you are running the international edition of AFS, or do not use the Update Server, repeat the command, substituting the name of each AFS server machine for machine name in turn.

    user names

    Specifies the username of each administrator to add to the UserList file.