Chapter 4
Administering Perforce:
Protections

When should protections be set?

The Perforce protections table is 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

Example:  A sample protections table

Protections: read        user       emily       *            //depot/elm_proj/... write       group      devgrp      *            //... write       user       *           195.3.24.*   -//... write       user       joe         *            -//... write       user       lisag       *            -//depot/... write       user       lisag       *            //depot/doc/... super       user       edk         *            //...

(The five fields might not line up vertically on your screen; they are aligned here for readability.)

The permission lines' five fields

The meanings of these fields are shown in the following table.

Access levels

Each Perforce command is associated with a particular minimum access level. For example, to run p4 sync on a particular file, the user must have been granted at least read access on that file.

The access level required to run a particular command can usually be reasoned from knowledge of what the command does. For example, it is somewhat obvious that p4 print would require read access. For a full list of the minimum access levels required to run each Perforce command, see "How protections are implemented" on page 81.

Which users should receive which permissions?

Read access to particular files should be granted to users who never need to edit those files. For example, an engineer might have write permission for source files, but have only read access to the documentation, and managers not working with code might be granted read access to all files.

Because open access enables local editing of files, but does not permit these files to be written to the depot, open access is granted only in unusual circumstances. You might choose open access over write access when users are testing their changes locally but when these changes should not be seen by other users. For instance, bug testers might need to change code in order to test theories as to why particular bugs occur, but these changes are not to be written to the depot. Perhaps a codeline has been frozen, and local changes are to be submitted to the depot only after careful review by the development team. In these cases, open access is granted until the code changes have been approved, after which time the protection level is upgraded to write and the changes submitted.

Default protections

This indicates that write access is granted to all users, on all hosts, to all files. Additionally, the user who first invoked p4 protect (in this case, edk) is granted superuser privileges.

Interpreting multiple permission lines

Example:  Multiple permission lines

Lisa, whose Perforce username is lisag, is using a workstation with the IP address 195.42.39.17. The protections file reads as follows:

read         user     *        195.42.39.17    //... write        user     lisag    195.42.39.17    //depot/elm_proj/doc/... read         user     lisag    *               //... super        user     edk      *               //...

The union of the first three permissions applies 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 elm_proj/doc subdirectory but can only read other files. Lisa tries the following:

She types p4 edit //depot/elm_proj/doc/elm-help.1, and is successful.

She types p4 edit //depot/elm_proj/READ.ME, and is told that she doesn't have the proper permission. She is trying to write to a file to which has only read access. She types p4 sync //depot/elm_proj/READ.ME, and this command succeeds, because 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 //depot/elm_proj/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 protections

To use exclusionary mappings properly, it is necessary to understand some of their peculiarities:

• When an exclusionary protection is included in the protections table, the order of the protections is relevant: the exclusionary protection is used to remove any matching protections above it in the table.

• No matter what access level is provided in an exclusionary protection, all access levels for the matching files and IP addresses are denied. The access levels provided in exclusionary protections are irrelevant. See "How protections are implemented" on page 81 for a more detailed explanation.
  Example:  Exclusionary protections
  An administrator has used p4 protect to set up protections as follows:

  write       user       *           *       //... read        user       emily       *       //depot/elm_proj/... super       user       joe         *       -//... list        user       lisag       *       -//... write       user       lisag       *       //depot/elm_proj/doc/...

  The first permission looks like it grants write access to all users to all files in all depots, but this is overruled by later exclusionary protections for certain users.
  The third permission denies Joe permission to access any file from any host. No subsequent lines grant Joe any further permissions; thus, Joe has been effectively locked out of Perforce.
  The fourth permission denies Lisa all access to all files on all hosts, but the fifth permission gives her back write access on all files within a specific directory. If the fourth and fifth lines were switched, Lisa would be unable to run any Perforce command.

Which lines apply to which users or files?

With no options, p4 protects displays the lines in the protections table that apply to the current user. If a file argument is provided, only those lines in the protection table that apply to the named files are displayed. Using the -m flag displays a one-word summary of the maximum applicable access level.

Perforce superusers can use p4 protects -a to see all lines for all users, or p4 protects -u user, -g group, or -h host flags to see lines for a specific user, group, or host IP address.

Granting access to groups of users

Groups are maintained with p4 group, and their protections are assigned with p4 protect. Only Perforce superusers can use these commands.

Creating and editing groups

To add users to a group, add user names in the Users: field of the form generated by the p4 group groupname command. User names are entered under the Users: field header; each user name must be typed on its own line, indented. A single user can be listed in any number of groups.

Groups can contain other groups as well as individual users. To add all users in a previously defined group to the group you're working with, include the group name in the Subgroups: field of the p4 group form. User and group names occupy separate namespaces, so groups and users can have the same names.

Groups and protections

Example:  Granting access to Perforce groups

This protections table grants list access to all members of the group devgrp, and super access to user edk:

list        group        devgrp      *        //... super       user         edk         *        //...

If a user belongs to multiple groups, one permission can override another. For instance, if you use exclusionary mappings to deny access to an area of the depot to members of group1, but grant access to the same area of the depot to members of group2, a user who is a member of both group1 and group2 is either granted or denied access based on whichever line appears last in the protections table. The actual permissions granted to a specific user can be determined by replacing the names of all groups to which a particular user belongs with the user's name within the protections table and applying the rules described earlier in this chapter.

Deleting groups

p4 group -d groupname

How protections are implemented

Users' access to files is determined by the following steps:

1. The command is looked up in the command access level table shown in "Access Levels Required by Perforce Commands" on page 82 to determine the minimum access level needed to run that command. In our example, p4 print is the command, and the minimum access level required to run that command is read.

2. Perforce makes the first of two passes through the protections table. Both passes move up the protections table, bottom to top, looking for the first relevant line.

   The first pass determines whether the user is permitted to know if the file exists. This search simply looks for the first line encountered that matches the user name, host IP address, and file argument. If the first matching line found is an inclusionary protection, the user has permission to at least list the file, and Perforce proceeds to the second pass. Otherwise, if the first matching protection found is an exclusionary mapping, or if the top of the protections table is reached without a matching protection being found, the user has no permission to even list the file, and will receive a message such as File not on client.

   Example:  Interpreting the order of mappings in the protections table
   Suppose the protections table is as follows:

   write       user        *        *      //... read        user        edk      *      -//... read        user        edk      *      //depot/elm_proj/...

   If Ed runs p4 print //depot/file.c, Perforce examines the protections table bottom to top, and first encounters the last line. The files specified there don't match the file that Ed wants to print, so this line is irrelevant. The second-to-last line is examined next; this line matches Ed's user name, his IP address, and the file he wants to print; since this line is an exclusionary mapping, Ed isn't allowed to list the file.

3. If the first pass is successful, Perforce makes a second pass at the protections table; this pass is the same as the first, except that access level is now taken into account.

   If an inclusionary protection line is the first line encountered that matches the user name, IP address, and file argument, and has an access level greater than or equal to the access level required by the given command, the user is given permission to run the command.

   If an exclusionary mapping is the first line encountered that matches according to the above criteria, or if the top of the protections table is reached without finding a matching protection, the user has no permission to run the command, and receives a message such as You don't have permission for this operation.

Access Levels Required by Perforce Commands

a This command doesn't operate on specific files. Thus, permission is granted to run the command if the user has the specified access to at least one file in the depot.

b The -o flag to this command, which allows the form to be read but not edited, requires only list access.

c list access is required to view an existing counter's value; review access is required to change a counter's value or create a new counter.

d To run p4 integrate, the user needs open access on the target files and read access on the donor files.

e The -f flag to override existing metadata or other users' data requires admin access.

f super access required to terminate or clear processes, admin access required to view arguments.

g super access required to use -a and -u flags for p4 protects.

Some commands (for example, p4 change, when you edit a previously submitted changelist) take a -f flag that can only be used by Perforce superusers. See "Forcing operations with the -f flag" on page 51 for details.