Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Reference | 2025.1

# p4 protect

Control user access to files, directories, and commands.

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

For Sub-protections:

    p4 protect path
    p4 protect -o path
    p4 protect -i path

Syntax conventions

## Description

Control user access to files, directories, and commands. These access rights are different from the graph depot permissions described at p4 grant-permission (graph).

`p4 protect` allows a user with super access to edit the protections table in a text form.

Run `p4 protect` immediately after installation because a new P4 Server installation allows anyone who wants to use P4 Server to connect and considers all P4 Server users to be 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.

See also the security warnings in p4 passwd.

Use `p4 protect` to set P4 Server privileges in any of the following ways:

- Control which commands particular users can run.
- Grant access to groups of users, as defined with `p4 group`.
- Grant access to a particular path for 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 `admin`, `open`, and `review` access levels are used less often.

For the minimum access level required to run each command, see Access levels required by P4 Server commands in the P4 Server Administration Documentation.

In general,

1. You grant an access level to:
   - a group, which is the 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. To understand the effect of such "exclusionary mappings", see How protections are implemented in P4 Server Administration Documentation.

### 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 P4 Server metadata, but has no access to file contents. The user can run all the commands that describe P4 Server objects, such as `p4 files`, `p4 client`, `p4 job`, `p4 describe`, `p4 branch` . Commands that list files, such as `p4 describe` and `p4 files`, only list 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 the user can do with `read` access, and also gives the user permission to `p4 add`, `p4 edit`, `p4 delete`, `p4 integrate`, and `p4 shelve` 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 the open 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. See Example with open.
`=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 P4 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 attribute` `-f`, `p4 branch` `-f`, `p4 change` `-f`, `p4 client` `-f`, `p4 job` `-f`, `p4 jobspec`, `p4 label` `-f`, `p4 obliterate`, `p4 shelve` `-f -d`, `p4 stream` `-f`, `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.
`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 example at Delegate management of parts of the protections table in the P4 Server Administration Documentation. The Sub-protections information that follows.

### Sub-protections

Sub-protections enable the user with `super` access to delegate management of parts of the protections table to non-super users or groups. To do so, create an entry with `owner` as the mode. Such entries must have a unique path without wildcards, except for a trailing `...`

Users with `super`, or that have been granted `owner` for a path, can run the `p4 protect` command while specifying the granted path as an argument to access the sub-protections table for that path.

Any entries in the sub-protections table are appended to the effective protections table directly below the `owner` entry.

- If an `owner` entry is removed, so are any entries in the sub-protections table for that path.

- The `owner` permission only grants access to the sub-protections table at the specified path. It does not grant the specified user or group any permissions on that path.

- The owner can grant the owner `admin` permissions on that path.

- Neither `owner` nor `super` entries can be added to a sub-protections table, and the paths of any other entries paths must be within the scope of path of the sub-protections table.

See SubPath under Form Fields.

### Stream spec permissions

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 * //...``
  `

Permission | Description
--- | ---
`readstreamspec` | The user can display a stream spec with `p4 stream -o` For example, if `//streamD1/main1` is the stream: `readstreamspec user user1 * //streamD1/main1`
`=readstreamspec` | If this right is denied, users cannot execute `p4 stream -o` For example, if `//streamD1/dev2` is the stream:, `=readstreamspec user user1 * -//streamD1/dev2`
`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`, P4 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. ### Direct connections or intermediaries When P4 Server evaluates protections table entries, it also considers the setting of the `dm.proxy.protects` configurable. dm.proxy.protects defaults to `1`, which causes the `proxy-` prefix to be prepended to all client host addresses that connect through an intermediary proxy, broker, or replica. The `proxy-` prefix indicates 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 such as `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. If `dm.proxy.protects` is set to `0`, the `proxy-` prefix is removed. This allows you to write a single set of protection entries that apply both to directly-connected clients and clients that connect through a proxy, broker, or replica. A single set of protection entries is more convenient. However, in some cases a connection through one or more intermediaries might be less secure. If you use the `0` 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 P4 Server depot syntax. The file specification can contain P4 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: Is not part of the protections table. Is only used when editing a sub-protections table. For an example of how to use the sub-protections table, see Delegate management of parts of the protections table in the P4 Server Administration Documentation.
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 so consider including comments.

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

## 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` | Convert comments that were created with the pre-2016.1 p4d style to the current style. The current style uses `##` and is compatible with P4Admin 2018.2 patch 1 and later. 1. Generate output with converted comments:
    p4 protect --convert-p4admin-comments -o
2. Confirm that the converted comments look correct. 3. If so, save the converted comments to the database: `p4 protect --convert-p4admin-comments -o | p4 protect -i`
`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:

Copy

    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.

To learn more, see:

- Access levels required by P4 Server commands in the P4 Server Administration Documentation.

- How protections are implemented in P4 Server Administration Documentation.

## Example

### Example with open

The open permission:

- Allows p4 edit.

- Allows p4 shelve if the user has open protections for all the files in the changelist.

- Does not allow p4 submit.

With these protections:

Copy

    list user * * -//...
    write user alice * //depot/dev/...
    write user alice * //depot/main/...
    write user bob * //depot/dev/...
    open user bob * //depot/main/...
    super user super * //...

The results are:

- alice can edit, revert, shelve, and submit in main and dev

- bob can edit, revert, shelve, and submit in dev

- bob can edit, revert, and shelve in main

- bob cannot submit in main

- bob cannot submit a shelved changed in main by using p4 submit -e

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

Your search for returned results