This chapter explains how to enable system administrators and operators to perform privileged AFS operations.
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 |
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.
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.
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.
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.
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
Is the shortest acceptable abbreviation of adduser.
Names each user to add 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 removeuser command to remove one or more users.
% pts removeuser -user <user name>+ -group system:administrators
where
Is the shortest acceptable abbreviation of removeuser.
Names each user to remove from the system:administrators group.
Administrators who have the ADMIN flag on their Authentication Database entry can issue all kas commands, which enable them to administer the Authentication Database.
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
Is the shortest acceptable abbreviation of examine.
Names the entry to display.
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...
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
Is an alias for setfields (and setf is the shortest acceptable abbreviation).
Names the entry for which to set or remove the ADMIN flag.
Sets or removes the ADMIN flag, respectively.
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.
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.
Issue the bos listusers command to display the contents of the /usr/afs/etc/UserList file.
% bos listusers <machine name>
where
Is the shortest acceptable abbreviation of listusers.
Names an AFS server machine. In the normal case, any machine is acceptable because the file is the same on all of them.
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
Is the shortest acceptable abbreviation of adduser.
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.
Specifies the username of each administrator to add 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 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
Is the shortest acceptable abbreviation of removeuser.
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.
Specifies the username of each administrator to add to the UserList file.