Perforce 2009.2: Command Reference

p4 protect

Synopsis

Control users' access to files, directories, and commands.

Syntax

p4 [g-opts] protect
p4 [g-opts] protect -o
p4 [g-opts] protect -i

Description

Use p4 protect to control Perforce permissions. You can use p4 protect to:

•	Control which files particular users can access;

•	Manage which commands particular users are allowed to use;

•	Combine the two, allowing one user to write one set of files but only be able to read other files;

•	Grant permissions to groups of users, as defined with p4 group;

•	Grant or deny specific rights to users by using the =read, =open, =write, and =branch rights, without having to re-grant lesser permissions.

•	Limit access to particular IP addresses, so that only users at these IP addresses can run Perforce.

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 can then be denied.

The permission levels and access rights are:

Permission Level / Right	What the User Can Do
list	The user can access all Perforce metadata, but has no access to file contents. The user can run all the commands that describe Perforce objects, such as p4 files, p4 client, p4 job, p4 describe, p4 branch, etc.
read	The user can do everything permitted with list access, and also run any command that involves reading file data, including p4 print, p4 diff, p4 sync, and so on.
=read	If this right is denied, users cannot use p4 print, p4 diff, or p4 sync on files.
open	This gives the user permission to do everything she can do with read access, and gives her permission to p4 add, p4 edit, p4 delete, and p4 integrate files. However, the user is not allowed to lock files or submit files to the depot.
=open	If this right is denied, users cannot open files with p4 add, p4 edit, p4 delete, or p4 integrate.
write	The user can do all of the above, and can also write files with p4 submit and lock them with p4 lock.
=write	If this right is denied, users cannot submit open files.
=branch	If this right is denied, users cannot use files as a source for p4 integrate.
review	This permission is meant for external programs that access Perforce. It gives the external programs permission to do anything that list and read can do, and grants permission to run p4 review and p4 counter. It does not include open or write access.
admin	Includes all of the above, including administrative commands that override changes to metadata, but do not affect server operation. These include p4 branch -f, p4 change -f, p4 client -f, p4 job -f, p4 jobspec, p4 label -f, p4 obliterate, p4 typemap, p4 unlock -f, and p4 verify.
super	Includes all of the above, plus access to the superuser commands such as p4 admin, p4 counter, p4 triggers, p4 protect, and so on.

Form Fields

When you run p4 protect, Perforce displays a form with a single field, Protections:. Each permission is specified in its own indented line under the Protections: header, and has five values:

Column	Description
Access Level	One of the access levels list, read, open, write, review, or super, or one of the rights of =read, =open, =write, and =branch, as defined above
User or Group	Does this protection apply to a user or a group? The value of this field must be user or group.
Group Name or User Name	The name of the user or the name of the group, as defined by p4 group. To grant this permission to all users, use the * wildcard.
Host	The IP address. CIDR notation is supported. The * wildcard can also be used to refer to all IP addresses, but only when you are not using CIDR notation.
Depot File Path	The depot file path this permission is granted on, in Perforce depot syntax. The file specification can contain Perforce wildcards. To exclude this mapping from the permission set, use a dash (-) as the first character of this value.

When exclusionary mappings are not used, a user is granted the highest permission level listed in the union of all the mappings that match the user, the user's IP address, and the files the user is trying to access. In this case, the order of the mappings is irrelevant.

When exclusionary mappings are used, order is relevant: the exclusionary mapping overrides any matching protections listed above it in the table. No matter what access level is being denied in the exclusionary protection, all the access levels for the matching users, files, and IP addresses are denied.

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.

Options

-i	Read the form from standard input without invoking an editor.
-o	Write the form to standard output without invoking an editor.
g-opts	See the Global Options section.

Usage Notes

Can File Arguments Use Revision Specifier?	Can File Arguments Use Revision Range?	Minimal Access Level Required
No	No	super

•	Each permission level includes all the access levels below it, as illustrated in this chart:

•	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, which may include reading or listing files in //depot/build/..., but he is prohibited from opening files for edit (or submitting any changes he might have open.) He can, however, continue to create and modify files outside of the protected //depot/build/... area.

•	Access levels determine which commands you can use. The following table lists the minimum access level required for 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
branch	open	The -f flag to override existing metadata or other users' data requires admin access.
branches	list
browse	none
change	open	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
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
dbschema	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
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.
fstat	list
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.
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
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.
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	list
license	super
lock	write
login	list
logout	list
logtail	super
monitor	list	super access is required to terminate or clear processes, or to view arguments.
move	open
obliterate	admin
opened	list
passwd	list
print	read
protect	super
protects	list	super access is required to use the -a, -g, and -u flags.
reopen	open
replicate	super
resolve	open
resolved	open
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.
set	none
shelve	write
sizes	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.
unlock	open	The -f flag to override existing metadata or other users' data requires admin access.
unshelve	write
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.
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.
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.

•

When a new Perforce server is installed, anyone who wants to use Perforce is allowed to, and all Perforce users are superusers. The first time anyone runs p4 protect, the invoking user is made the superuser, and everyone else is given write permission on all files. Run p4 protect immediately after installation.

•	In the course of normal operation, you'll primarily grant users list, read, write, and super access levels. The open and review access levels are used less often.

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

•	Some commands (for instance, p4 change, when editing a previously submitted changelist) take a -f flag that requires admin or super access.

•

The open access level gives the user permission to change files but not submit them to the depot. Use this when you're temporarily freezing a codeline, but don't want to stop your developers from working, or when you employ testers who are allowed to change code for their own use but aren't allowed to make permanent changes to the codeline.

•	The review access level is meant for review daemons that need to access counter values.

•	If you write a review daemon that requires both review and write access, but shouldn't have super access, grant the daemon both review and write access on two separate lines of the protections table.

•	To limit or eliminate the use of the files on a particular server as a remote depot from a different server (as defined by p4 depot), create protections for user remote. Remote depots are always accessed by a virtual user named remote.

•	For further information, see the Protections chapter of the System Administrator's Guide.

Examples

Suppose that user joe is a member of groups devgroup and buggroup, as set by p4 group, and the protections table reads as follows:

super     user      bill       *                  //... write     group     devgroup   *                  //depot/... write     group     buggroup   *                  -//depot/proj/... write     user      joe        192.168.100.0/24   //...

Joe attempts a number of operations. His success or failure at each is described below:

From IP address...	Joe tries...	Results
10.14.10.1	p4 print //depot/misc/...	Succeeds. The second line grants Joe write access on these files; write access includes read access, and this protection isn't excluded by any subsequent lines.
10.14.10.1	p4 print //depot/proj/README	Fails. The third line removes all of Joe's permissions on any files in this directory. (If the second protection and the third protection had been switched, then the subsequent protection would have overridden this one, and Joe would have succeeded).
192.168.100.123	p4 print //depot/proj/README	Succeeds. Joe is sitting at an IP address from which he is granted this permission in the fourth line.
192.168.100.123	p4 verify //depot/misc/...	Fails. p4 verify requires super access; Joe doesn't have this access level no matter which IP address he's coming from.

Related Commands

To create or edit groups of users	p4 group
To list all user groups	p4 groups