Perforce 2005.1 System Administrator's Guide
<< Previous Chapter
Administering Perforce:
Superuser Tasks

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Customizing Perforce:
Job Specifications


Chapter 4
Administering Perforce:
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. 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 may 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 (or if you accidentally lock yourself out!) 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:

The permission lines' five fields

Each line specifies a particular permission; each permission is defined by five fields.

The meanings of these fields are:

Field
Meaning

Access Level

Which access level is being granted: list, read, open, write, review, admin, or super. These are described below.

User/Group

Does this protection apply to a user or a group? The value must be user or group.

Name

The user or group whose protection level is being defined. This field may 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 the host in dotted quad notation (for instance, 192.168.41.2).

This field may 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.*" would define access to any subnet within 192.168.41, and "*3*" would refer to any IP address with a "3" in it.

Because the client's IP address is provided by the Internet Protocol itself, this field provides as much security as is provided by the network.

If you are using Perforce Proxy, see "P4P and protections" on page 139 to find out how to use host-based protections for users connecting to a Perforce Server from behind a Perforce Proxy.

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.

Access levels

The access level is described by the first value on each line. The seven access levels 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(s) can run those Perforce commands that are needed to read files, such as p4 client and p4 sync. The read permission includes list access.

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

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.

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 specifications, client specifications, jobs, labels, and change descriptions, as well as to update the typemap table, verify and obliterate files, and to 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 to shut down the server.

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

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 never need to edit those files. For example, an engineer may have write permission for source files, but have only read access to the documentation, and managers not working with code may 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 may want 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

Before p4 protect is invoked, every user has superuser privileges. When 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.

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

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:

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 assigned with p4 protect. Only Perforce superusers may use these commands.

Creating and editing groups

If p4 group groupname is called with a non-existent 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 may be listed in any number of groups.

Groups may 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

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.

If a user belongs to multiple groups, one permission may 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

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, as the material here is provided to explain the logic behind the behavior described above.

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

The first pass determines whether or not the user is permitted to know whether or not 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, then 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, then the user has no permission to even list the file, and will receive a message like File not on client.

If an inclusionary protection line is the first line encountered that matches the user name, IP address, file argument, and has an access level greater than or equal to the access level required by the given command, then 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, then the user has no permission to run the command, and will receive the message "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
Command
Access Level

add

open

jobs a

list

admin

super

jobspec b

admin

annotate

read

label a e

open

branch e

open

labels a b

list

branches

list

labelsync

open

changelist e

open

lock

write

changelists a

list

login

none

client e

list

logout

none

clients

list

monitor

list f

counter c

review

obliterate

admin

counters

list

opened

list

delete

open

passwd

list

depot a b

super

print

read

depots a

list

protect a

super

describe

read

reopen

open

describe -s

list

resolve

open

diff

read

resolved

open

diff2

read

revert

open

dirs

list

review a

review

edit

open

reviews a

list

filelog

list

set

list

files

list

submit

write

fixes a

list

sync

read

fstat

list

tag

open

group a b

super

tickets

none

groups a

list

triggers

super

have

list

typemap

admin

help

none

unlock e

open

info

none

user a b

list

integrate d

open

users a

list

integrated

list

verify

admin

job b e

open

where a

none

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 admin access required to terminate or clear processes.
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 editing a previously submitted changelist) take a -f flag which can only be used by Perforce superusers. See "Forcing operations with the -f flag" on page 51 for details.


Perforce 2005.1 System Administrator's Guide
<< Previous Chapter
Administering Perforce:
Superuser Tasks

Table of Contents
Index
Perforce on the Web
Next Chapter >>
Customizing Perforce:
Job Specifications

Please send comments and questions about this manual to [email protected].
Copyright 1999-2005 Perforce Software. All rights reserved.
Last updated: 05/12/05