System Administration:
Protections

Perforce provides a protection scheme to prevent unauthorized or inadvertent access to the depot. The protections determines which Perforce commands can be run, on which files, by whom, and from which host. Since any user can change their Perforce username with P4USER, user level protections provide safety, not security. At the host level, protections are as secure as the host itself.

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:

Protections: read emily * //depot/elm_proj/... write * 195.3.21.* //... write joe * -//... write lisag * -//depot/... write lisag * //depot/doc/... super edk * //...

The Permission Lines' Four Fields

Each line specifies a particular permission; each permission is always described by four fields. The meanings of these four fields are:

Field	Meaning
Access Level	Which access level is being granted: list, read, open, write, super, or review. These are described below.
User	The user whose protection level is being defined. This field can contain the `*' wildcard: `*' by itself would grant this protection to everyone; `*e' would grant this protection to everyone whose username ends with an `e'. Since Perforce usernames can be changed by setting P4USER, this field provides safety, not security.
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 (e.g. 206.14.52.194). 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 `127.30.41.*' would define access to any subnet within 127.30.41, and `*3*' would refer to any IP address with a `3' in it. Since the client's IP address is provided by IP itself, this field provides as much security as is provided by the network.
Files	The files in the depot that permission is being granted on. `//...' means all files in all depots.

Access Levels

The access level is described by the first field; the six access levels are

Access Level	Meaning
list	Permission is granted to run Perforce commands that display data about files, (e.g. 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 allow the user to write the files back to the depot. open is similar to write, except that with open permission, users are not allowed 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. 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. It is needed only by review daemons.
super	For Perforce superusers; grants permission to run all Perforce commands. Provides write and review access plus the added ability to edit protections, create depots, obliterate files, and verify files.

:

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. A full list of the minimum access levels required to run each Perforce command is provided on page 104.

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 Protections

When p4 protect is first run, two permissions are set by default. The default protections form looks like this:

Protections: write * * //... super edk * //...

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 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; 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:

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

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 Protections

A 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:

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

  The reasons for this seemingly strange behavior are described in the section How Protections are Implemented on page 105.

Ed has used p4 protect to set up protections as follows:

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

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:

• 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

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.

Command	Access Level		Command	Access Level
add	open		jobs a	list
branch 1	open		label a	open
branches	list		labels a	list
change	open		labelsync	open
change -f	super		lock	write
changes a	list		obliterate	super
client	list		open	open
clients a	list		opened	list
delete	open		print	read
depot a	super		protect a	super
depots a	list		refresh	read
describe	read		reopen	open
describe -s	list		reresolve	open
diff	read		resolve	open
diff2	read		resolved	open
edit	open		revert	open
files	list		review a	review
filelog	list		reviews a	list
fix a	open		submit	write
fixes a	list		sync	read
have	list		unlock	open
help	none		user a	list
info	none		users a	list
integrate 2	open		verify	review
integrated	list		where a	none
job a	open

a This command doesn't operate on specific files. Thus, permission is granted to run these commands if the user has the specified access to at least one file in the depot. a To run p4 integrate, the user needs open access on the target files and read access on the donor files.

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

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:

• The command is looked up in the command access level table shown on page 104 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.
• 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 is used to determine whether or not the user is allowed to know whether or not the file exists, and 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 permisson to list the file, and Perforce proceeds to the second pass. If the first mapping 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.
• As an example, suppose that our protections table is set as follows:

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

• If Ed runs p4 print //depot/foo, 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 even list the file.
• If the first pass is successful, a second pass is made at the protections table, again reading bottom to top; 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, 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.