Administration Guide

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 group	pts membership
Add user to system:administrators group	pts adduser
Remove 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 has the following characteristics:

Membership in the cell's system:administrators group. See Administering the system:administrators Group.
The ADMIN flag on his or her entry in the cell's Authentication Database. See Granting Privilege for kas Commands: the ADMIN Flag.
Inclusion in the file /usr/afs/etc/UserList on the local disk of each AFS server machine in the cell. See Administering the UserList File.

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:

Permission to issue all pts commands, which are used to administer the Protection Database. See Administering the Protection Database.
Permission to issue the fs setvol and fs setquota commands, which set the space quota on volumes as described in Setting and Displaying Volume Quota and Current Size.
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, as described in Setting ACL Entries.
You can change the 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 IBM AFS Administration Reference. 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 display 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 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
   
```
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 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
   
```
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

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

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.

The bos commands 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. See Administering Server Machines and Monitoring and Controlling Server Processes.
The vos commands enable the administrator to manage volumes and the Volume Location Database (VLDB). See Managing Volumes.
The backup commands enable the administrator to use the AFS Backup System to copy data to permanent storage. See Configuring the AFS Backup System and Backing Up and Restoring AFS Data.

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

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 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>
```
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

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>
```
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.