System Administrator's Guide

Managing Administrative Privilege

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

Summary of Commands

List members of system:administrators group	pts membership
Add a user to system:administrators group	pts adduser
Remove a user from system:administrators group	pts removeuser
Display `ADMIN` flag in Authentication Database entry	kas examine
Set or remove `ADMIN` flag on Authentication Database entry	kas setfields
Display users in UserList file	bos listusers
Add user to UserList file	bos adduser
Remove user from UserList file	bos removeuser

An Overview of Administrative Privilege

A fully privileged AFS system administrator for a cell is privileged as follows:

Belonging to the cell's system:administrators group
Having the ADMIN flag on his or her entry in the cell's Authentication Database
Inclusion in the file /usr/afs/etc/UserList on the local disk of each AFS server machine in the cell

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.

Membership in the system:administrators Group

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

The permission to issue all pts commands, which are used to administer the Protection Database. See Administering the Protection Database.
Implicit a (administer) and by default l (lookup) permissions on the access control list (ACL) on every directory in the cell's AFS filespace. Members of the group can use the fs setacl command to grant themselves any other permissions they require.
The permission to issue the fs setvol and fs setquota commands, which set the space quota on volumes.

To learn how to administer the system:administrators group, and how to change the default set of implicit ACL permissions, see Administering the system:administrators Group.

The ADMIN Flag in the Authentication Database

The second kind of AFS administrative privilege is having the ADMIN flag on the Authentication Database entry. Such administrators can issue all kas commands, which enable them to administer the Authentication Database.

To learn how to grant this type of privilege, see Granting Privilege for kas Commands: the ADMIN Flag.

Inclusion in the /usr/afs/etc/UserList File

The third type of privilege is inclusion in the file /usr/afs/etc/UserList on the local disk of each AFS server machine. Users listed in the file have the following privileges:

The permission to issue all bos commands. These enable the administrator to manage server processes and the server configuration files that define the cell's database server machines, server encryption keys, and privileged users.
The permission to issue all vos commands. These enable the administrator to manage volumes and the Volume Location Database (VLDB).
The permission to issue all backup commands. These enable the administrator to use the AFS Backup System to copy data to permanent storage.

To learn how to grant this type of privilege, see Granting Privilege for bos, vos, and backup Commands: the UserList File.

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

Members of the system:administrators group in the Protection Database can issue all pts commands and the fs setvol and fs setquota commands to set volume quotas, and implicitly have the a (administer) and by default l (lookup) permissions on the access control list (ACL) of every directory in the cell's AFS filespace.

You can change the set of ACL permissions that the File Server on a given file server machine implicitly grants to the members of the system:administrators group for the data in volumes that it houses. When you issue the bos create command to create and start the fs process on the machine, include the -implicit argument to the fileserver initialization command. For syntax details, see the fileserver reference page in the AFS Command Reference Manual. You can grant additional permissions, or remove the l permission. However, the File Server always implicitly grants the a permission to members of the group, even if you set the value of the -implicit argument to none.

To list the members of the system:administrators group

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

Verify that you have the privilege needed to add users to the system:administrators group (you must belong to the group yourself). If necessary, issue the pts membership command, as described in Administering the system:administrators Group.
```
   % pts membership system:administrators
```
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

Verify that you have the privilege needed to remove users from the system:administrators group (you must belong to the group yourself). If necessary, issue the pts membership command, as described in Administering the system:administrators Group.
```
   % pts membership system:administrators
```
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

Grant or deny an administrator the permission to issue all kas commands by setting or removing the ADMIN flag on his or her Authentication Database entry. The kas commands are used to administer the Authentication Database.

To check if the ADMIN flag is set

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 the ADMIN flag

Issue the kas setfields command to turn on the ADMIN flag in an Authentication Database entry. (The command appears on two lines only for legibility.)
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. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.
```
    % kas setfields <name of user>  ADMIN  \  
                   -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 the ADMIN flag.
-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.

To remove the ADMIN flag

Issue the kas setfields command to turn off the ADMIN flag in an Authentication Database entry. (The command appears on two lines only for legibility.)
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. To verify that an entry has the flag, issue the kas examine command as described in To check if the ADMIN flag is set.
```
   % kas setfields <name of user> 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 turn off the ADMIN flag.
-admin
Names an administrative account with the ADMIN flag on its Authentication Database entry, such as admin. The password prompt echoes it as admin_user. Enter the appropriate password as admin_password.

Granting Privilege for bos, vos, and backup Commands: the UserList File

To enable an administrator to issue all privileged bos, vos, and backup commands, add the administrator's username to the /usr/afs/etc/UserList file. 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 list the users in the UserList file

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

Verify you have the privilege needed to add users to the UserList file (you must appear in it yourself). If necessary, issue the bos listusers command, which is fully described in To list the users in the UserList file.
```
   % bos listusers <machine name>
```
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 user of each administrator to add to the UserList file.

To remove users from the UserList file

Verify you have the privilege necessary to remove users from the UserList file (you must appear in it yourself). If necessary, issue the bos listusers command, which is fully described in To list the users in the UserList file.
```
   % bos listusers <machine name>
```
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 user of each administrator to add to the UserList file.