| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Chapter 14 System Administration: Protections | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Perforce provides a protection scheme to prevent unauthorized or inadvertent access to the depot. The protections determine which Perforce commands can be run, on which files, by whom, and from which host. Protections are set with the p4 protect command.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
When Should Protections Be Set? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Before p4 protect is run, every Perforce user is a superuser, and can access and change anything in the depot. The first time protect is invoked, a protections table is created that gives the invoking user superuser access from all hosts, and lowers everyone else's access level to write permission on all files from all hosts. Therefore, protect should be run as the concluding step of all new Perforce installations; the superuser can change the access levels as needed at any time.
The Perforce protections are stored in the db.protect file in the server root directory; if p4 protect is first run by an unauthorized user, the depot can be brought back to its unprotected state by removing this file.
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Setting Protections with p4 protect | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
The p4 protect form contains a single field with multiple lines. Each line specifies a particular permission; the contents look something like this:
|
(The four fields may not line up vertically on your screen; they are aligned here for ease of reading). The Permission Lines' Five FieldsEach line specifies a particular permission; each permission is always described by five fields. The meanings of these fields are:
Access LevelsThe access level is described by the first value on each line. The six access levels are:
Which Users Should Receive Which Permissions?The simplest method of granting permissions is to give write permission to all users who don't need to manage the Perforce system, and give super access to those who do. But there are times when this simple solution isn't sufficient.Read access to particular files should be granted to users who don't ever need to edit those files. For example, an engineer might have write permissions for source files, but have only read access to the documentation; managers might be granted only read access to all files. Because open access allows local editing of files, but doesn't allow these files to be written to the depot, open access is usually granted only in unusual circumstances. Choose open access over write access when users will be testing their changes locally, but when these changes should not be seen by other users. For example, bug testers may want to change code in order to test theories as to why particular bugs occur, but these changes would be for their own use, and would not be written to the depot. Or, a codeline might be frozen, with local changes submitted to the depot only after careful review by the development team. In this case, open access would be granted until the code changes have been approved; at that time, the protection level would be upgraded to write. Default ProtectionsWhen p4 protect is first run, two permissions are set by default. The default protections form looks like this:
This indicates that write access is granted to all users, on all hosts, to all files. Additionally, the user who first invokes p4 protect (in this case, edk) is granted superuser privileges. Interpreting Multiple Permission LinesThe access rights granted to any user are defined by the union of mappings in the protection lines that match her user name and client IP address. (This behavior is slightly different when exclusionary protections are provided; this is described in the next section).
Lisa, whose Perforce username is lisag, is using a client with the IP address
195.42.39.17. The protections file reads as follows: |
The union of the first three permissions apply to Lisa. Her username is lisag, and she's currently using a client workspace on the host specified in lines 1 and 2. Thus, she can write files located in the depot's doc subdirectory, but can only read other files. Lisa tries the following: She types p4 edit //lisag/doc/elm-help.1, and is successful. She types p4 edit //lisag/READ.ME, and is told that she doesn't have the proper permission. She is trying to write a file that she only has read access to. She types p4 sync //lisag/READ.ME, and this command succeeds; only read access is needed, and this is granted to her on line 1. Lisa later switches to another machine with IP address 195.42.39.13. She types p4 edit //lisag/doc/elm-help.1, and the command fails; when she's using this host, only the third permission applies to her, and she only has read privileges. Exclusionary ProtectionsA user can be denied access from particular files by prefacing the fourth field in a permission line with a minus sign ( - ). This is useful for giving most users access to a particular set of files, while denying access to the same files to only a few users.To use exclusionary mappings properly, it is necessary to understand some peculiarities associated with them:
Ed has used p4 protect to set up protections as follows: |
The second permission seemingly grants write access to all users to all files in all depots, but this is overruled by later exclusionary protections for certain users:
| Granting Access to Groups of Users
Perforce groups ease maintenance of the protections table. The names of users with identical access requirements can be stored in a single group; rather then enter each user individually into the protections table, the group name can be entered in the table, and all the users in that group will receive the specified accesses.
| Creating and Editing GroupsThe command p4 group groupname displays a form with two fields: Group: and Users:. The Group: field stores the group name, and can't be edited; Users: is empty when the group is first created, and must be filled in. User names are entered under the Users: field header; each user name must be typed on its own line, and should be indented. A single user may be listed in any number of groups.User names and group names occupy separate namespaces; thus, groups and users can have the same names. If p4 group groupname is called with a non-existent groupname, a new group with the name groupname will be created. Calling this command with an existing groupname allows editing of the user list for this group. Only Perforce superusers may invoke p4 group. Groups and ProtectionsTo use a group with the p4 protect form, specify a group name instead of a user name in any line in the protections table, and set the value of the second field on the line to group instead of user. All the users in that group will be granted the specified access. For example, the following protections table gives write access to all members of the group devgroup, and super access to user edk:
If a user belongs to multiple groups, one permission may override another, but the actual permissions granted to a specific user can be determined by replacing the names of all groups that a particular user belongs to with the users name within the protections table, and applying the rules described earlier in this chapter. Deleting GroupsTo delete a group, invoke p4 group groupname and delete all the users from the group. The group will be deleted when the form is closed.
| Access Levels Required by Perforce Commands
The following table lists the minimum access level required to run each command. For example, since p4 add requires at least open access, p4 add can be run if open, write or super protections are granted. |
Those commands that list files, such as p4 describe, will only list those files to which the user has at least list access. Some of these commands take a -f flag which can only be run by Perforce superusers. Please see Forcing Operations with the -f Flag.
| How Protections are Implemented
This section describes the algorithm that Perforce follows to implement its protection scheme. Protections can be used properly without reading this section; the material here is provided to explain some of the more eccentric behavior described above.
| Users' access to files is determined by the following steps:
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||