Helix Core P4 Command Reference (2020.1)

p4 protect

Control user access to files, directories, and commands.

Note

These access rights are different from the graph depot permissions described at p4 grant-permission (graph).

Syntax

p4 [g-opts] protect
p4 [g-opts] protect -o p4 [g-opts] protect -i
p4 [g-opts] protect --convert-p4admin-comments -o | -i

Description

Important

We recommend that you run p4 protect immediately after installation because a new Helix server installation:

  • allows anyone who wants to use Helix server to connect to the service
  • considers all Helix server users as superusers

The first time a user runs p4 protect, that user is made the superuser, and all other users are given write privilege on all files. We recommend that you use p4 protect to create additional controls.

p4 [g-opts] protect allows a user with super access to edit the protections table in a text form.

Use p4 protect to set Helix server privileges in any of the following ways:

  • Control which commands particular users can access
  • Control which commands particular users can run
  • Grant access 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
  • Use =read, =open, =write, and =branch in conjunction with an exclusionary mapping
  • Limit access to particular IP addresses

It is common to specify any of the following access levels: list, read, write, owner, and super. The open and review access levels are used less often.

In general,

  1. You grant an access level to a:
    • group (best practice) or
    • a user (if you cannot combine multiple users into a suitable group)
  2. If finer-grained control is required, you can selectively deny one or more specific rights.
Tip

To understand the effect of "exclusionary mappings", see How protections are implemented in Helix Core Server Administrator Guide.

Permission levels and access rights

If the name of a permission level has the = prefix, it means the denial of a right.

Permission Level / Right What the User Can Do

list

The user can access all Helix server metadata, but has no access to file contents. The user can run all the commands that describe Helix server 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. For example,

=read group Dev1 * -//depot/dev/prodA/...

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. For example,

=open group Dev1 * -//depot/dev/prodA/...

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 can open and edit files, but cannot submit them. For example,

=write group Admins * -//depot/dev/prodA/...

to ensure that Admins do not accidentally alter the files that developers have approved for a product release.

=branch

If this right is denied, users cannot use files as a source for p4 integrate. For example,

=branch group Dev1 * -//depot/dev/prodA/...

review

This permission is meant for external programs that access Helix server. 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 Core Server Administrator Guide.

Stream spec permissions

Important

Prior to release 2020.1, there were no protections modes specific to stream specs. The permissions for listing, reading, and editing stream specs were inferred from the corresponding filespec protections as follows:

  • list permission in a depot granted the ability to run p4 streams to list streams in that depot
  • open or write permission on a file spec granted the ability to edit and save any stream spec whose stream root matches that file spec

The 2020.1 release added protections modes that are specific to stream specs. By default, these permissions can exist in the protection table, but will not be used until the dm.protects.streamspec configurable has been set to 1. If the dm.protects.streamspec configurable is set to 1 and any stream spec permissions exist in the protection table, the pre-2020.1 permissions no longer apply and all users who are not admin or super require explicit stream spec permissions.

If you want to implement the legacy permissions with the stream spec permissions:

  • Create a user group containing all users who require readstreamspec

    readstreamspec group readgroup * //...

  • Create another user group containing all users who require writestreamspec

    writestreamspec group writegroup * //...

readstreamspec The user can display a stream spec with p4 stream -o
=readstreamspec If this right is denied, users cannot execute p4 stream -o
openstreamspec This gives the user permission to revert, resolve, shelve, or open for edit a stream spec.
=openstreamspec If this right is denied, users cannot revert, resolve, shelve, or open for edit a stream spec.
writestreamspec The user can submit or modify a stream spec.
=writestreamspec If this right is denied, users cannot submit or modify a stream spec.

Form Fields

When you run p4 protect, Helix server 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, or a comma-separated list of IP addresses, 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 on which this permission is granted, in Helix server depot syntax. The file specification can contain Helix server 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.

SubPath

 

The root path of the sub-protections table:

This field is not part of the protections table.

Update

 

The date this specification was last modified (read-only).

  • If this date is modified, the protections table will not be saved
  • Omitting this field will avoid the modification check.

This field is not part of 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/...  ## my comment
  • Or you can write a comment line by prefixing the line with the ## symbols:

    ## my comment
    write user *   10.1.1.1   //depot/test/...
Warning

Comments you have created using the P4Admin tool are not compatible with comments created using p4 protect (2016.1 or later). 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.

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

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:

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

  • The =open exclusion prevents joe from opening any files for edit under //depot/build/
  • The =write exclusion prevents joe from submitting any changes he might already have open under //depot/build/

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

For command-by-command details, see "Access levels required by Helix server commands" in Helix Core Server Administrator Guide.

Related Commands

To create or edit groups of users

p4 group

To list all user groups

p4 groups

To grant permission for depots and repos of type graph p4 grant-permission (graph)