![[Return to Library]](../books.gif)
![[Contents]](../toc.gif)
![[Previous Topic]](../prev.gif)
![[Bottom of Topic]](../bot.gif)
![[Next Topic]](../next.gif)
![[Index]](../index.gif)
This chapter explains how to create and maintain user, machine, and group entries in the Protection Database.
This chapter explains how to perform the following tasks by
using the indicated commands:
| Display Protection Database entry | pts examine |
| Map user, machine or group name to AFS ID | pts examine |
| Display entry's owner or creator | pts examine |
| Display number of users or machines belonging to group | pts examine |
| Display number of groups user or machine belongs to | pts examine |
| Display group-creation quota | pts examine |
| Display entry's privacy flags | pts examine |
| Display members of group, or groups that user or machine belongs to | pts membership |
| Display groups that user or group owns | pts listowned |
| Display all entries in Protection Database | pts listentries |
| Create machine entry | pts createuser |
| Create group entry | pts creategroup |
| Add users and machines to groups | pts adduser |
| Remove users and machines from groups | pts removeuser |
| Delete machine or group entry | pts delete |
| Change a group's owner | pts chown |
| Change an entry's name | pts rename |
| Set group creation quota | pts setfields |
| Set entry's privacy flags | pts setfields |
| Display AFS ID counters | pts listmax |
| Set AFS ID counters | pts setmax |
The Protection Database stores information about AFS users, client machines, and groups which the File Server process uses to determine whether clients are authorized to access AFS data.
To obtain authenticated access to an AFS cell, a user must have an entry in the cell's Protection Database. The first time that a user requests access to the data stored on a file server machine, the File Server on that machine contacts the Protection Server to request the user's current protection subgroup (CPS), which lists all the groups to which the user belongs. The File Server scans the access control list (ACL) of the directory that houses the data, looking for groups on the CPS. It grants access in accordance with the permissions that the ACL extends to those groups or to the user individually. (The File Server stores the CPS and uses it as long as the user has the same tokens. When a user's group membership changes, he or she must reauthenticate for the File Server to recognize the change.)
Only administrators who belong to the cell's system:administrators group can create user entries (the group is itself defined in the Protection Database, as discussed in The System Groups). Members of the system:administrators group can also create machine entries, which can then be used to control access based on the machine from which the access request originates. After creating a machine entry, add it to a Protection Database group and place the group on ACLs (a machine cannot appear on ACLs directly). A machine entry can represent a single machine or multiple machines with consecutive IP addresses as specified by a wildcard notation. For instructions, see Creating User and Machine Entries. Because all replicas of a volume share the same ACL (the one on the volume's root directory mount point), machine entries enable you to replicate the volume that houses a program's binary file while still complying with a machine-based license agreement as required by the program's manufacturer. See Creating User and Machine Entries.
A group entry is a list of user entries, machine entries, or both (groups cannot belong to other groups). Putting a group on an ACL is a convenient way to extend or deny access to a set of users without listing them on the ACL individually. Similarly, adding users to a group automatically grants them access to all files and directories for which the associated ACL lists that group. Both administrators and regular users can create groups.
In addition to the groups that users and administrators can create, AFS defines the following three system groups. The Protection Server creates them automatically when it builds the first version of a cell's Protection Database, and always assigns them the same AFS GIDs.
Placing this group on an ACL is a convenient way to extend access to all users. The File Server automatically places this group on the CPS of any user who requests access to data stored on a file server machine. (Every unauthenticated user is assigned the identity anonymous and this group is the only entry on the CPS for anonymous.)
Placing this group on an ACL is therefore a convenient way to extend access to all authenticated users. The File Server automatically places this group on the CPS of any authenticated user who requests access to data stored on a file server machine.
This section describes the commands you can use to display Protection Database entries and associated information. In addition to name and AFS ID, the Protection Database stores the following information about each user, machine, or group entry.
% pts membership system:administrators
% pts examine <user or group name or id>+
where
The output includes the following fields. Examples follow.
Normally, the Protection Server assigns an AFS UID or GID automatically when you create Protection Database entries. Members of the system:administrators group can specify an ID if desired. For further discussion, see Creating User and Machine Entries and Creating Groups.
The value anonymous in this field generally indicates that the entry was created when the Protection Server was running in no-authentication mode, probably during initial configuration of the cell's first file server machine. For a description of no-authentication mode, see Managing Authentication and Authorization Requirements.
For a complete description of possible values for the flags, see Setting the Privacy Flags on Database Entries.
Group creation quota has no meaning for a machine or group entry: the Protection Server recognizes the issuer of the pts creategroup command only as an authenticated user or as the anonymous user, never as a machine or group. The default value for group entries is 0 (zero), and there is no reason to change it.
The following examples show the output for a user called pat, a machine with IP address 192.12.108.133 and a group called terry:friends:
% pts examine pat
Name: pat, id: 1020, owner: system:administrators, creator: admin,
membership: 12, flags: S----, group quota: 15.
% pts ex 192.12.108.133
Name: 192.12.108.133, id: 5151, owner: system:administrators, creator: admin,
membership: 1, flags: S----, group quota: 20.
% pts examine terry:friends
Name: terry:friends, id: -567, owner: terry, creator: terry,
membership: 12, flags: SOm--, group quota: 0.
% pts membership system:administrators
% pts membership <user or group name or id>+
where
For user and machine entries, the output begins with the following string, and then each group appears on its own line:
Groups user_or_machine (id: AFS_UID) is a member of:
For group entries, the output begins with the following string, and then each member appears on its own line:
Members of group (id: AFS_GID) are:
For the system groups system:anyuser and system:authuser, the output includes the initial header string only, because these groups do not have a stable membership listed in their Protection Database entry. See The System Groups.
The following examples show the output for a user called terry and a group called terry:friends:
% pts mem terry
Groups terry (id: 5347) is a member of:
pat:friends
sales
acctg:general
% pts mem terry:friends
Members of terry:friends (id: -567) are:
pat
smith
johnson
% pts membership system:administrators
% pts listowned <user or group name or id>+
where
The output begins with the following string, and then each group appears on its own line:
Groups owned by user_or_group (id: AFS_ID) are:
The following examples show the output for a user called terry and a group called terry:friends:
% pts listo terry
Groups owned by terry (id: 5347) are:
terry:friends
terry:co-workers
% pts listo terry:friends
Groups owned by terry:friends (id: -567) are:
terry:pals
terry:buddies
% pts membership system:administrators
% pts listentries [-users] [-groups]
where
The output is a table that includes the following columns. Examples follow.
The following example is from the ABC Corporation cell. The issuer provides no options, so the output includes user and machine entries.
% pts listentries Name ID Owner Creator anonymous 32766 -204 -204 admin 1 -204 32766 pat 1000 -204 1 terry 1001 -204 1 smith 1003 -204 1 jones 1004 -204 1 192.12.105.33 2000 -204 1 192.12.105.46 2001 -204 1
An entry in the Protection Database is one of the two required components of every AFS user account, along with an entry in the Authentication Database. It is best to create a Protection Database user entry only in the context of creating a complete user account, by using the uss add or uss bulk command as described in Creating and Deleting User Accounts with the uss Command Suite, or the pts createuser command as described in Creating AFS User Accounts.
You can also use the pts createuser command to create Protection Database machine entries, which can then be used to control access based on the machine from which the access request originates. After creating a machine entry, add it to a Protection Database group and place the group on ACLs ( a machine cannot appear on ACLs directly). Because all replicas of a volume share the same ACL (the one on the volume's root directory mount point), you can replicate the volume that houses a program's binary file while still complying with a machine-based license agreement as required by the program's manufacturer. If you do not place any other entries on the ACL, then only users working on the designated machines can access the file.
Keep in mind that creating an ACL entry for a group with machine entries in it extends access to both authenticated and unauthenticated users working on the machine. However, you can deny access to unauthenticated users by omitting an entry for the system:anyuser group from the ACLs of the parent directories in the file's pathname. Conversely, if you want to enable unauthenticated users on the machine to access a file, then the ACL on every directory leading to it must include an entry for either the system:anyuser group or a group to which the machine entry belongs. For more information on the system:anyuser group, see The System Groups.
Because a machine entry can include unauthenticated users, it is best not to add both machine entries and user entries to the same group. In general, it is easier to use and administer nonmixed groups. A machine entry can represent a single machine, or multiple machines with consecutive IP addresses (that is, all machines on a network or subnet) specified by a wildcard notation. See the instructions in To create machine entries in the Protection Database.
By default, the Protection Server assigns the next available AFS UID to a new user or machine entry. It is best to allow this, especially for machine entries. For user entries, it makes sense to assign an AFS UID only if the user already has a UNIX UID that the AFS UID needs to match (see Assigning AFS and UNIX UIDs that Match). When automatically allocating an AFS UID, the Protection Server increments the max user id counter by one and assigns the result to the new entry. Use the pts listmax command to display the counter, as described in Displaying and Setting the AFS UID and GID Counters.
Do not reuse the AFS UIDs of users who have left your cell permanently or machine entries you have removed, even though doing so seems to avoid the apparent waste of IDs. When you remove a user or machine entry from the Protection Database, the fs listacl command displays the AFS UID associated with the former entry, rather than the name. If you then assign the AFS UID to a new user or machine, the new user or machine automatically inherits permissions that were granted to the previous possessor of the ID. To remove obsolete AFS UIDs from ACLs, use the fs cleanacl command described in Removing Obsolete AFS IDs from ACLs.
In addition to the name and AFS UID, the Protection Server records the following values in the indicated fields of a new user or machine's entry. For more information and instructions on displaying an entry, see To display a Protection Database entry.
% pts membership system:administrators
% pts createuser -name <user name>+
where
Do not define a machine entry with the name 0.0.0.0 to match every machine. The system:anyuser group is equivalent.
The following example creates a machine entry that includes all of the machines in the 192.12 network.
% pts cu 192.12.0.0
Before you can add members to a group, you must create the group entry itself. The instructions in this section explain how to create both regular and prefix-less groups:
owner_name:group_name
Any user can create a regular group. Group names must always be typed in full, so a short group_name that indicates the group's purpose or its members' common interest is practical. Groups with names like terry:1 and terry:2 are less useful because their purpose is unclear. For more details on the required format for regular group names, see the instructions in To create groups.
Only members of the system:administrators group can create prefix-less groups. For a discussion of their purpose, see Using Prefix-Less Groups.
By default, the Protection Server assigns the next available AFS GID to a new group entry, and it is best to allow this. When automatically allocating an AFS GID (which is a negative integer), the Protection Server decrements the max group id counter by one and assigns the result to the new group. Use the pts listmax command to display the counter, as described in Displaying and Setting the AFS UID and GID Counters.
In addition to the name and AFS GID, the Protection Server records the following values in the indicated fields of a new group's entry. See To display a Protection Database entry.
The main reason to create groups is to place them on ACLs, which enables you to control access for multiple users without having to list them individually on the ACL. There are three basic ways to use groups, each suited to a different purpose:
The existence of the group and the identity of its members is not necessarily secret. Other users can use the fs listacl command and see the group's name on a directory's ACL, or use the pts membership command to list the groups they themselves belong to. You can set the group's third privacy flag to limit who can use the pts membership command to list the group's membership, but a member of the system:administrators group always can; see Setting the Privacy Flags on Database Entries.
| Note: | If you place a group owned by someone else on your ACLs, the group's owner can change the group's membership without informing you. Someone new can gain or lose access in a way you did not intend and without your knowledge. |
The main advantage of designating a group as an owner is that it spreads responsibility for administering a group among several people. A single person does not have to perform all administrative tasks, and if the original creator leaves the group, ownership does not have to be transferred.
However, everyone in the owner group can make changes that affect others negatively, such as adding or removing people from the group inappropriately or changing the group's ownership to themselves exclusively. These problems can be particularly sensitive in a self-owned group. Using an owner group works best if all the members know and trust each other; it is probably wise to keep the number of people in an owner group small.
% pts membership system:administrators
% pts creategroup -name <group name>+ [-owner <owner of the group>]
where
A prefix-less group name cannot include the colon (:), because it is used to separate the two parts of a regular group name:
owner_name:group_name
The Protection Server requires that the owner_name prefix of a regular group name accurately indicate the group's owner. By default, you are recorded as the owner, and the owner_name must be your AFS username. You can include the -owner argument to designate another AFS user, a regular group, or a prefix-less group as the owner, providing the required value in the owner_name field:
(For a discussion of why it is useful for a group to own another group, see Using Groups Effectively.)
Do not designate a machine as a group's owner. Because a machine cannot authenticate, there is no way for a machine to administer the group.
% pts creategroup <group name>
% pts adduser -user <user name>+ -group <group name>+
% pts chown <group name> <new owner>
Members of the system:administrators group can create prefix-less groups, which are particularly suitable for group use, which is described in Using Groups Effectively.
Suppose, for example, that the manager of the ABC Corporation's Accounting Department, user smith, creates a group that includes all of the corporation's accountants and places the group on the ACLs of directories that house departmental records. Using a prefix-less group rather than a regular group is appropriate for the following reasons:
A possible solution is to create an authentication account for a fictional user called acctg and make it the owner of regular groups which have acctg as their owner_name prefix. However, if the acctg account is also used for other purposes, then the number of people who need to know user acctg's password is possibly larger than the number of people who need to administer the groups it owns.
A prefix-less group called acctg solves the problem of inappropriate owner names. The groups that it owns have acctg as their owner_name prefix, which more accurately reflects their purpose than having the manager's name there. Prefix-less groups are also more accountable than dummy authentication accounts. Belonging to the group enables individuals to exercise the permissions granted to the group on ACLs, but users continue to perform tasks under their own names rather than under the dummy username. Even if the group owns itself, only a finite number of people can administer the group entry.
Users and machines can be members of groups; groups cannot belong to other groups. Newly created groups have no members at all. To add them, use the pts adduser command; to remove them, use the pts removeuser command.
% pts membership system:administrators
% pts adduser -user <user name>+ -group <group name>+
where
% pts membership system:administrators
% pts removeuser -user <user name>+ -group <group name>+
where
It is best to delete a Protection Database user entry only if you are removing the complete user account. Use either the uss delete command as described in Deleting Individual Accounts with the uss delete Command, or the pts delete command as described in Removing a User Account.
To remove machine and group entries, use the pts delete command as described in this section. The operation has the following results:
To remove obsolete AFS IDs from ACLs, use the fs cleanacl command as described in Removing Obsolete AFS IDs from ACLs.
% pts membership system:administrators
% pts delete <user or group name or id>+
where
For user and machine entries, the Protection Server automatically assigns ownership to the system:administrators group at creation time, and this cannot be changed. For group entries, you can change ownership. This transfers administrative responsibility for it to another user or group (for information on group ownership of other groups, see Using Groups Effectively).
When you create a regular group, its owner_name prefix must accurately reflect its owner, as described in To create groups:
When you change a regular group's owner, the Protection Server automatically changes its owner_name prefix appropriately. For example, if the user pat becomes the new owner of the group terry:friends, its name automatically changes to pat:friends, both in the Protection Database and on ACLs.
However, the Protection Server does not automatically change the owner_name prefix of any regular groups that the group owns. To continue with the previous example, suppose that the group terry:friends owns the group terry:pals. When pat becomes the new owner of terry:friends, the name terry:pals does not change. To change the owner_name prefix of a regular group that is owned by another group (in the example, to change the group's name to pat:pals), use the pts rename command as described in Changing a Protection Database Entry's Name.
% pts membership system:administrators
% pts membership <user or group name or id>
Use the pts adduser command to add yourself if necessary, as fully described in To add users and machines to groups.
% pts adduser <user name> <group name>
% pts chown <group name> <new owner>
where
% pts listowned <user or group name or id>
If you want to change their names to match the new owning group, use the pts rename command on each one, as described in To change the name of a machine or group entry.
% pts rename <old name> <new name>
To change the name of a Protection Database entry, use the pts rename command. It is best to change a user entry's name only when renaming the entire user account, since so many components of the account (Authentication Database entry, volume name, home directory mount point, and so on) share the name. For instructions, see Changing Usernames. A machine entry's name maps to the actual IP address of one or more machine, so changing the entry's name is appropriate only if the IP addresses have changed.
It is likely, then, that most often you need to change group names. The following types of name changes are possible:
You can also use the pts rename command to change the group_name portion of a regular group name, with or without changing the owner_name prefix.
Both the group's owner and the members of the system:administrators group can change its name to another regular group name.
Both the group's owner and the members of the system:administrators group can change its name to another prefix-less name.
Only members of the system:administrators group can make this type of name change.
% pts membership system:administrators
% pts rename <old name> <new name>
where
To prevent abuse of system resources, the Protection Server imposes a group-creation quota that limits how many more groups a user can create. When a new user entry is created, the quota is set to 20, but members of the system:administrators group can use the pts setfields command to increase or decrease it at any time.
It is pointless to change group-creation quota for machine or group entries. It is not possible to authenticate as a group or machine and then create groups.
To display the group-creation quota, use the pts examine command to display a user entry's group quota field, as described in To display a Protection Database entry.
% pts membership system:administrators
% pts setfields -nameorid <user or group name or id>+ \
-groupquota <set limit on group creation>
where
Members of the system:administrators group can always display and administer Protection Database entries in any way, and regular users can display and administer their own entries and any group entries they own. The privacy flags on a Protection Database entry determine who else can display certain information from the entry, and who can add and remove members in a group.
To display the flags, use the pts examine command as described in To display a Protection Database entry. The flags appear in the output's flags field. To set the flags, include the -access argument to the pts setfields command.
The five flags always appear, and always must be set, in the following order:
Each flag can take three possible types of values to enable a different set of users to issue the corresponding command:
For example, the flags SOmar on a group entry indicate that anyone can examine the group's entry and display the groups that it owns, and that only the group's members can display, add, or remove its members.
The default privacy flags for user and machine entries are S----, meaning that anyone can display the entry. The ability to perform any other functions is restricted to members of the system:administrators group and the entry's owner (as well as the user for a user entry).
The default privacy flags for group entries are S-M--, meaning that all users can display the entry and the members of the group, but only the entry owner and members of the system:administrators group can perform other functions.
% pts membership system:administrators
% pts setfields <user or group name or id>+ -access <set privacy flags>
where
When you use the pts createuser command to create a user or machine entry in the Protection Database, the Protection Server by default automatically allocates an AFS user ID (AFS UID) for it; similarly, it allocates an AFS group ID (AFS GID) for each group entry you create with the pts creategroup command. It tracks the next available AFS UID (which is a positive integer) and AFS GID (which is a negative integer) with the max user id and max group id counters, respectively.
Members of the system:administrators group can include the -id argument to either pts creation command to assign a specific ID to a new user, machine, or group. It often makes sense to assign AFS UIDs explicitly when creating AFS accounts for users with existing UNIX accounts, as discussed in Assigning AFS and UNIX UIDs that Match. It is also useful if you want to establish ranges of IDs that correspond to departmental affiliations (for example, assigning AFS UIDs from 300 to 399 to members of one department, AFS UIDs from 400 to 499 to another department, and so on).
To display the current value of the counters, use the pts listmax command. When you next create a user or machine entry and do not specify its AFS UID, the Protection Server increments the max user id counter by one and assigns that number to the new entry. When you create a new group and do not specify its AFS GID, the Protection Server decrements the max group id counter by one (makes it more negative), and assigns that number to the new group.
You can change the value of either counter, or both, in one of two ways:
If the value you specify with the -id argument is less than the max user id counter or greater (less negative) than the max group id counter, then the counter does not change.
% pts listmax
where listm is an acceptable abbreviation of listmax.
The following example illustrates the output's format. In this case, the next automatically assigned AFS UID is 5439 and AFS GID is -469.
% pts listmax Max user id is 5438 and max group id is -468.
% pts membership system:administrators
% pts setmax [-group <group max>] [-user <user max>]
where
![[Top of Topic]](../top.gif)