Administering Perforce: Protections

Perforce provides a protection scheme to prevent unauthorized or inadvertent access to files in the depot. The protections determine which Perforce commands can be run, on which files, by whom, and from which host. You configure protections with the p4 protect command.

When should protections be set?

Run p4 protect immediately after installing Perforce for the first time. Before the first call to p4 protect, every Perforce user is a superuser and thus can access and change anything in the depot. The first time a user runs p4 protect, a protections table is created that gives superuser access to the user from all IP addresses, and lowers all other users' access level to write permission on all files from all IP addresses.

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

The p4 protect form contains a single form field called Protections: that consists of multiple lines. Each line in Protections: contains subfields, and the table looks like this:

Example 5. A sample protections table

Protections:
    read     user     emily   *                //depot/elm_proj/...
    write    group    devgrp  *                    //...
    write    user     *       192.168.41.0/24     -//...
    write    user     *       [2001:db8:1:2::]/64 -//...
    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.)


Note

If your site makes use of the Perforce Proxy, prepend proxy- to the addresses in the host field to make the lines apply to users of the proxy. For detailed information, see the material on "P4P and protections" in Perforce Server Administrator's Guide: Multi-site Deployment.

The permission lines' five fields

Each line specifies a particular permission level and/or access right, as defined by five fields:

Field

Meaning

Access Level

Which access level (list, read, open, write, review, admin, or super) or specific right (=read, =open, =write, or =branch) is being granted or denied. Each permission level includes all the permissions above it (except for review). Each permission right (denoted by an =) only includes the specific right and not all of the lesser rights.

In general, one typically grants an access level to a user or group, after which, if finer-grained control is required, one or more specific rights may then be denied.

User/Group

Does this protection apply to a user or a group?

Name

The user or group whose protection level is being defined. This field can contain the * wildcard. A * by itself grants this protection to everyone, *e grants this protection to every user (or group) whose username ends with an e.

Host

The TCP/IP address of the host being granted access. This must be provided as the numeric address of either one specific host (for instance, 192.168.41.2 or [2001:db8:195:1:2::1234]) or a subnet expressed in CIDR notation.

The host field can also contain the * wildcard. A * by itself means that this protection is being granted for all hosts. The wildcard can be used as in any string, so 192.168.41.* is equivalent to 192.168.41.0/24.

You cannot combine the * wildcard with CIDR notation, except at the start of a line when controlling proxy matching. If you are using IPv6 with the * wildcard, you must enclose the address with square brackets. [2001:db8:1:2:*] is equivalent to [2001:db8:1:2::]/64. Best practice is to use CIDR notation, surround IPv6 addresses with brackets, and to avoid the * wildcard.

For more about controlling access to a Perforce server via the Perforce Proxy, see the relevant chapter of Perforce Server Administrator's Guide: Multi-site Deployment.

Files

A file specification representing the files in the depot on which permissions are being granted. Perforce wildcards can be used in the specification.

"//..." means all files in all depots.

If a depot is excluded, the user denied access will no longer see the depot in the output of p4 depots. Nor will the depot show up, for this user, in the default branch, client, and label views.

Access levels

The access level is described by the first value on each line. The permission levels and access rights are:

Level

Meaning

list

Permission is granted to run Perforce commands that display file metadata, such as p4 filelog. No permission is granted to view or change the contents of the files.

read

The user can run those Perforce commands that are needed to read files, such as p4 client and p4 sync. The read permission includes list access.

=read

If this right is denied, users cannot use p4 print, p4 diff, or p4 sync on files.

open

Grants permission to read files from the depot into the client workspace, and gives permission to open and edit those files. This permission does not permit the user to write the files back to the depot. The open level is similar to write, except that with open permission, users are not permitted to run p4 submit or p4 lock.

The open permission includes read and list access.

=open

If this right is denied, users cannot open files with p4 add, p4 edit, p4 delete, or p4 integrate.

write

Permission is granted to run those commands that edit, delete, or add files. The write permission includes read, list, and open access.

This permission allows use of all Perforce commands except protect, depot, obliterate, and verify.

=write

If this right is denied, users cannot submit open files.

=branch

If this right is denied, users may not use files as a source for p4 integrate.

review

A special permission granted to review daemons. It includes list and read access, plus use of the p4 review command. Only review daemons require this permission.

admin

For Perforce administrators; grants permission to run Perforce commands that affect metadata, but not server operation. Provides write and review access plus the added ability to override other users' branch mappings, client specifications, jobs, labels, and change descriptions, as well as to update the typemap table, verify and obliterate files, and customize job specifications.

super

For Perforce superusers; grants permission to run all Perforce commands. Provides write, review, and admin access plus the added ability to create depots and triggers, edit protections and user groups, delete users, reset passwords, and shut down the server.

Each Perforce command is associated with a particular minimum access level. For example, to run p4 sync or p4 print on a particular file, the user must have been granted at least read access on that file. For a full list of the minimum access levels required to run each Perforce command, see How protections are implemented.

The specific rights of =read, =open, =write, and =branch can be used to override the automatic inclusion of lower access levels. This makes it possible to deny individual rights without having to then re-grant lesser rights.

For example, if you want administrators to have the ability to run administrative commands, but to deny them the ability to make changes in certain parts of the depot, you could set up a permissions table as follows:

admin      user      joe       *             //...
=write     user      joe       *             -//depot/build/...
=open      user      joe       *             -//depot/build/...

In this example, user joe can perform administrative functions, and this permission applies to all depots in the system. Because the admin permission level also implies the granting of all lower access levels, joe can also write, open, read and list files anywhere in the system, including //depot/build/. To protect the build area, the =write and =open exclusionary lines are added to the table. User joe is prevented from opening any files for edit in the build area. He is also prevented from submitting any changes in this area he may already have open. He can continue to create and modify files, but only if those files are outside of the protected //depot/build/... area.

Default protections

Before p4 protect is invoked, every user has superuser privileges. Before p4 protect is first run, two permissions are set by default. The default protections table looks like this:

write        user        *        *        //...
super        user        edk      *        //...

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.

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

Interpreting multiple permission lines

The 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 and is described in the next section.)

Example 6. 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

A user can be denied access to particular files by prefacing the fifth 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 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 for a more detailed explanation.

Example 7. 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 denied any file access.

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?

Use the p4 protects command to display the lines from the protections table that apply to a user, group, or set of 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, ignoring exclusionary mappings.

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

Perforce groups simplify maintenance of the protections table. The names of users with identical access requirements can be stored in a single group; the group name can then be entered in the table, and all the users in that group receive the specified permissions.

Groups are maintained with p4 group, and their protections are assigned with p4 protect. Only Perforce superusers can use these commands. (Perforce administrators can use p4 group -A to administer a group, but only if the group does not already exist.)

Creating and editing groups

If p4 group groupname is called with a nonexistent groupname, a new group named groupname is created. Calling p4 group with an existing groupname allows editing of the user list for this group.

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. Group owners are not necessarily members of a group; if a group owner is to be a member of the group, the userid must also be added to the Users: field.

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.

Adding nonexistent users to group definitions does not actually create the users, nor does it consume licenses; use the p4 user command to create users.

Groups and protections

To 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 are granted the specified access.

Example 8. 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         *        //...

According to the following three permission lines, group ac1 will have write access to //ac1/... while giving the group read-only access to //ac1/ac1_dev/....

write        group        ac1      *        //ac1/...
list         group        ac1      *        -//ac1/ac1_dev/...
read         group        ac1      *        //ac1/ac1_dev/...

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

To delete a group, invoke

p4 group -d groupname

Alternately, invoke p4 group groupname and delete all the users from the group in the resulting editor form. The group will be deleted when the form is closed.

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 the logic behind the behavior described above.

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

The following table lists the minimum access level required to run each command. For example, because p4 add requires at least open access, you can run p4 add if you have open, write, admin, or super access

Command

Access Level

Notes

add

open

admin

super

annotate

read

archive

admin

attribute

write

The -f flag to set the attributes of submitted files requires admin access.

branch

open

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

branches

list

change

open

The -o flag (display a change on standard output) requires only list access. The -f flag to override existing metadata or other users' data requires admin access.

changes

list

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

client

list

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

clients

list

configure

super

copy

list

list access to the source files; open access to the destination files.

counter

review

list access to at least one file in any depot is required to view an existing counter's value; review access is required to change a counter's value or create a new counter.

counters

list

cstat

list

dbschema

super

dbstat

super

dbverify

super

delete

open

depot

super

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

depots

list

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

describe

read

The -s flag to this command, which does not display file content, requires only list access.

diff

read

diff2

read

dirs

list

diskspace

super

edit

open

export

super

filelog

list

files

list

fix

open

fixes

list

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

flush

list

fstat

list

grep

read

group

super

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

The -a flag to this command requires only list access, provided that the user is also listed as a group owner.

The -A flag requires admin access.

groups

list

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

have

list

help

none

info

none

integrate

open

The user must have open access on the target files and read access on the source files.

integrated

list

interchanges

list

istat

list

job

open

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

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

jobs

list

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

jobspec

admin

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

journaldbchecksums

super

key

review

list access to at least one file in any depot is required to view an existing key's value; review access is required to change a key's value or create a new key.

key

list

admin access is required if the dm.keys.hide configurable is set to 2.

keys

list

admin access is required if the dm.keys.hide configurable is set to 1 or 2.

label

open

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

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

labels

list

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

labelsync

open

license

super

The -u flag, which displays license usage, requires only admin access.

list

open

lock

write

lockstat

super

logappend

list

logger

review

login

list

logout

list

logparse

super

logrotate

super

logschema

super

logstat

super

logtail

super

merge

open

monitor

list

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

move

open

obliterate

admin

opened

list

passwd

list

ping

admin

populate

open

print

read

protect

super

protects

list

super access is required to use the -a, -g, and -u flags.

property

list

list to read, admin to add/delete new properties, or show a property setting and sequence number for all users and groups.

proxy

none

Must be connected to a Perforce Proxy.

pull

super

reconcile

open

reload

open

admin access is required to use p4 reload -f to reload other users' workspaces and labels.

reopen

open

replicate

super

resolve

open

resolved

open

restore

admin

revert

list

review

review

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

reviews

list

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

server

super

serverid

list

super access is required to set the server ID.

set

none

shelve

open

admin access is required to forcibly delete shelved files with p4 shelve -f -d

sizes

list

status

open

stream

open

streams

list

submit

write

sync

read

tag

list

tickets

none

triggers

super

typemap

admin

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

unload

open

admin access is required to use p4 unload -f to unload other users' workspaces and labels.

unlock

open

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

unshelve

open

update

list

user

list

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

The -f flag (which is used to create or edit users) requires super access.

users

list

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

If the run.users.authorize configurable is set to 1, you must also authenticate yourself to the server before you can run p4 users.

verify

admin

where

list

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

Commands that list files, such as p4 describe, list only those files to which the user has at least list access.

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 for details.