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 --convert-p4admin-comments -o | -i

Description

For a new Perforce installation, anyone who wants to use Perforce is allowed to connect to the service, 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.

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

  • Control which commands and/or files particular users can access
  • Grant permissions to groups of users, as defined with p4 group
  • Grant access to the p4 protect command for a particular path, to a user or group
  • Grant or deny specific access 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 the specified IP addresses can run Perforce.

The command provides three syntax variants:

  • The first variant allows you to edit the protections table in a text form.
  • The second variant writes the protection table to standard output
  • The third variant reads the protection table from standard input. You can also use this variant to convert comments in the p4admin-generated protection table. For more information, see Comments.

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

In general, you typically grant an access level to a user or group, after which, if finer-grained control is required, you can selectively deny one or more specific rights.

For detailed information, see the "Security" chapter of the Helix Versioning Engine Administrator Guide: Fundamentals.

Permission levels and access rights are described in the table below:

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.

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

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.

The open access level gives the user permission to change files but not submit them to the depot. Assign this level 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 are not allowed to make permanent changes to the codeline.

=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 service operation.

These include p4 branch -f, p4 change -f, p4 client -f, p4 job -f, p4 jobspec, p4 label -f, p4 obliterate, p4 shelve -f -d, 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, the ability to create users with p4 user -f, and so on.

owner

Use this permission to assign permission to a specific user or group to run p4 protect for a particular path. For details, see the section Authorizing access in Helix Versioning Engine Administrator Guide: Fundamentals.

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 uses the following five values to define protections:

Column Description

Access Level or Mode

One of the access levels list, read, open, write, admin, super, owner, review; or one of the rights =read, =open, =write, and =branch, as defined above.

User or Group

Specifies whether this protection applies to a user or a 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 of the client host. IPv6 addresses and IPv4 addresses are also supported. You can use the * wildcard to refer to all IP addresses, but only when you are not using CIDR notation.

If you use the * wildcard with an IPv6 address, you must enclose the entire IPv6 address in square brackets. For example, [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.

How the system forms host addresses depends on the setting of the dm.proxy.protects variable. By default, this variable is set to 1. This means that if the client host uses some intermediary (proxy, broker, replica) to access the server, the proxy- prefix is prepended to the client host address to indicate that the connection is not direct. If you specify proxy-* for the Host field, that will affect all connections made via proxies, brokers, and replicas. A value like proxy-10.0.0.5 identifies a client machine with an IP address of 10.0.0.5 that is connected to the server through an intermediary.

Setting the dm.proxy.protects variable to 0, removes the proxy- prefix and allows you to write a single set of protection entries that apply both to directly-connected clients as well as to those that connect via an intermediary. This is more convenient but less secure if it matters that a connection is made using an intermediary. If you use this setting, all intermediaries must be at release 2012.1 or higher.

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.

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.

Exclusionary mappings

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.

Comments

Protection tables can be difficult to interpret and debug. Including comments can make this work much easier.

  • You can append comments at the end of a line using the ## symbols:

    write user *   10.1.1.1   //depot/test/...  ## robinson crusoe
  • Or you can write a comment line by prefixing the line with the ## symbols:

    ## robinson crusoe
    write user *   10.1.1.1   //depot/test/...

Warning

Comments you have created using the P4Admin tool are not compatible with comments created using the 2016.1 version of p4 protect. You can use the following command to convert a file containing comments created with P4Admin into a file containing p4 protect type comments:

$ p4 protect --convert-p4admin-comments -o

Then save the resulting file.

Once you have converted the comments, you must continue to define and manage protections using p4 protect and can no longer use P4Admin to do so because this tool is unable to parse p4 protect comments.

Options

-i

Read the form from standard input without invoking an editor.

-o

Write the form to standard output without invoking an editor.

--convert-p4admin-comments

Converts an existing protections form (and comments) created using P4Admin tool, to a form that can be used by p4 protect.

g-opts

See “Global Options”.

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:

permission levels

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.

To limit or eliminate the use of the files on a particular server as a remote depot from another server (as defined by p4 depot), create protections for user remote (or for the service user by which the other server authenticates itself). Remote depots are accessed either by the service user associated with the user’s Perforce service, or by a virtual user named remote.

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.

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

Command Access Level Notes

add

open

 

admin

super

 

annotate

read

 

archive

admin

 

attribute

write

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

branch

open

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

branches

list

 

change

open

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

changes

list

This command does not 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 option 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 option to this command, which allows the form to be read but not edited, requires only list access.

depots

list

This command does not 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 option 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 does not 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 option to this command, which allows the form to be read but not edited, requires only list access.

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

The -A option requires admin access.

groups

list

This command does not 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 option to this command, which allows the form to be read but not edited, requires only list access.

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

jobs

list

This command does not 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.

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 does not 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 option to override existing metadata or other users' data requires admin access.

labels

list

This command does not 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 option, 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 options.

property

list

list to read, admin to add/delete new properties, or show a property setting 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 does not 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 does not 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 option 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 option to override existing metadata or other users' data requires admin access.

unshelve

open

 

update

list

 

user

list

This command does not 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 option (which is used to create or edit users) requires super access.

users

list

This command does not 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 does not 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.

Examples

Suppose that user joe is a member of groups devgroup and buggroup, as set by p4 group, the organization is using only IPv4 connections, 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 is not 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’s workstation is 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 does not have this access level no matter what IP address he’s coming from.

Related Commands

To create or edit groups of users

p4 group

To list all user groups

p4 groups