Administering Perforce: Protections
Perforce provides a protection scheme to prevent unauthorized or inadvertent access to files in the depot. The protections determine which Perforce commands can be run, on which files, by whom, and from which host. You configure protections with the p4 protect command.
When should protections be set?
Run p4 protect immediately after installing Perforce
for the first time. Before the first call to p4
protect, every Perforce user is a superuser and thus can access
and change anything in the depot. The first time a user runs p4
protect, a protections table is created that gives superuser
access to the user from all IP addresses, and lowers all other users'
access level to write permission on all files from all
IP addresses.
The Perforce protections table is 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 form field called
Protections: that consists of multiple lines. Each line
in Protections: contains subfields, and the table looks
like this:
Example 5. A sample protections table
Protections:
read user emily * //depot/elm_proj/...
write group devgrp * //...
write user * 192.168.41.0/24 -//...
write user * [2001:db8:1:2::]/64 -//...
write user joe * -//...
write user lisag * -//depot/...
write user lisag * //depot/doc/...
super user edk * //...
(The five fields might not line up vertically on your screen; they are aligned here for readability.)
Note
If your site makes use of the Perforce Proxy, prepend
proxy- to the addresses in the host field to
make the lines apply to users of the proxy. For detailed information,
see the material on "P4P and protections" in
Perforce
Server Administrator's Guide: Multi-site Deployment.
The permission lines' five fields
Each line specifies a particular permission level and/or access right, as defined by five fields:
|
Field |
Meaning |
|---|---|
|
|
Which access level ( 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 may then be denied. |
|
|
Does this protection apply to a |
|
|
The user or group whose protection level is being defined.
This field can contain the |
|
|
The TCP/IP address of the host being granted access. This
must be provided as the numeric address of either one specific
host (for instance,
The host field can also contain the
You cannot combine the For more about controlling access to a Perforce server via the Perforce Proxy, see the relevant chapter of Perforce Server Administrator's Guide: Multi-site Deployment. |
|
|
A file specification representing the files in the depot on which permissions are being granted. Perforce wildcards can be used in the specification.
" 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. |
Access levels
The access level is described by the first value on each line. The permission levels and access rights are:
|
Level |
Meaning |
|---|---|
|
|
Permission is granted to run Perforce commands that display file metadata, such as p4 filelog. No permission is granted to view or change the contents of the files. |
|
|
The user can run those Perforce commands that are needed to
read files, such as p4 client and
p4 sync. The |
|
|
If this right is denied, users cannot use p4 print, p4 diff, or p4 sync on files. |
|
|
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 permit the user to write the files
back to the depot. The
The |
|
|
If this right is denied, users cannot open files with p4 add, p4 edit, p4 delete, or p4 integrate. |
|
|
Permission is granted to run those commands that edit, delete,
or add files. The
This permission allows use of all Perforce commands except
|
|
|
If this right is denied, users cannot submit open files. |
|
|
If this right is denied, users may not use files as a source for p4 integrate. |
|
|
A special permission granted to review daemons. It includes list and read access, plus use of the p4 review command. Only review daemons require this permission. |
|
|
For Perforce administrators; grants permission to run Perforce
commands that affect metadata, but not server operation.
Provides |
|
|
For Perforce superusers; grants permission to run all Perforce
commands. Provides |
Each Perforce command is associated with a particular minimum access
level. For example, to run p4 sync or p4
print on a particular file, the user must have been granted at
least read access on that file. For a full list of
the minimum access levels required to run each Perforce command, see
How protections are implemented.
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.
Default protections
Before p4 protect is invoked, every user has superuser privileges. Before p4 protect is first run, two permissions are set by default. The default protections table looks like this:
write user * * //... super user edk * //...
This indicates that write access is granted to all
users, on all hosts, to all files. Additionally, the user who first
invoked p4 protect (in this case,
edk) is granted superuser privileges.
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 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 never need to edit those files. For example, an engineer might
have write permission for source files, but have only
read access to the documentation, and managers not
working with code might be granted read access to all
files.
Because open access enables local editing of files,
but does not permit these files to be written to the depot,
open access is granted only in unusual circumstances.
You might choose open access over
write access when users are testing their changes
locally but when these changes should not be seen by other users. For
instance, bug testers might need to change code in order to test
theories as to why particular bugs occur, but these changes are not to
be written to the depot. Perhaps a codeline has been frozen, and local
changes are to be submitted to the depot only after careful review by
the development team. In these cases, open access is
granted until the code changes have been approved, after which time the
protection level is upgraded to write and the changes
submitted.
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 and is described in the next section.)
Example 6. Multiple permission lines
Lisa, whose Perforce username is lisag, is using a
workstation with the IP address 195.42.39.17. The
protections file reads as follows:
read user * 195.42.39.17 //... write user lisag 195.42.39.17 //depot/elm_proj/doc/... read user lisag * //... super user edk * //...
The union of the first three permissions applies 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 elm_proj/doc
subdirectory but can only read other files. Lisa tries the following:
She types p4 edit depot/elm_proj/doc/elm-help.1, and is successful.
She types p4 edit //depot/elm_proj/READ.ME, and is
told that she doesn't have the proper permission. She is trying to
write to a file to which has only read access. She
types p4 sync depot/elm_proj/READ.ME, and this
command succeeds, because 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
//depot/elm_proj/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 to particular files by prefacing the fifth
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 of their peculiarities:
-
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. See How protections are implemented for a more detailed explanation.
Example 7. Exclusionary protections
An administrator has used p4 protect to set up protections as follows:
write user * * //... read user emily * //depot/elm_proj/... super user joe * -//... list user lisag * -//... write user lisag * //depot/elm_proj/doc/...
The first permission looks like it 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 denied any file access.
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.
Which lines apply to which users or files?
Use the p4 protects command to display the lines from the protections table that apply to a user, group, or set of files.
With no options, p4 protects displays the lines in
the protections table that apply to the current user. If a
file argument is provided, only those lines
in the protection table that apply to the named files are displayed.
Using the -m flag displays a one-word summary of
the maximum applicable access level, ignoring exclusionary mappings.
Perforce superusers can use p4 protects -a to see all
lines for all users, or p4 protects -u
user, -g
, or group-h
flags to see lines for a
specific user, group, or host IP address.
host
Granting access to groups of users
Perforce groups simplify maintenance of the protections table. The names of users with identical access requirements can be stored in a single group; the group name can then be entered in the table, and all the users in that group receive the specified permissions.
Groups are maintained with p4 group, and their protections are assigned with p4 protect. Only Perforce superusers can use these commands. (Perforce administrators can use p4 group -A to administer a group, but only if the group does not already exist.)
Creating and editing groups
If p4 group groupname is
called with a nonexistent groupname, a new
group named groupname is created. Calling
p4 group with an existing
groupname allows editing of the user list for
this group.
To add users to a group, add user names in the Users:
field of the form generated by the p4 group
groupname command. User names are
entered under the Users: field header; each user name
must be typed on its own line, indented. A single user can be listed in
any number of groups. Group owners are not necessarily members of a
group; if a group owner is to be a member of the group, the userid must
also be added to the Users: field.
Groups can contain other groups as well as individual users. To add all
users in a previously defined group to the group you're working with,
include the group name in the Subgroups: field of the
p4 group form. User and group names occupy separate
namespaces, so groups and users can have the same names.
Adding nonexistent users to group definitions does not actually create the users, nor does it consume licenses; use the p4 user command to create users.
Groups and protections
To use a group with the p4 protect form, specify a
group name instead of a user name in any line in the protections table
and set the value of the second field on the line to
group instead of user. All the
users in that group are granted the specified access.
Example 8. Granting access to Perforce groups
This protections table grants list access to all
members of the group devgrp, and
super access to user edk:
list group devgrp * //... super user edk * //...
According to the following three permission lines, group ac1 will have
write access to //ac1/... while giving the group
read-only access to //ac1/ac1_dev/....
write group ac1 * //ac1/... list group ac1 * -//ac1/ac1_dev/... read group ac1 * //ac1/ac1_dev/...
If a user belongs to multiple groups, one permission can override
another. For instance, 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. The actual permissions granted to a specific user can
be determined by replacing the names of all groups to which a particular
user belongs with the user's name within the protections table and
applying the rules described earlier in this chapter.
Synchronizing Perforce groups with LDAP groups
You can configure Perforce to automatically synchronize the contents of a given Perforce user group with that of an LDAP group. Protections are still assigned based on the identity of the Perforce group (using the p4 protect command), but which users are included in the Perforce group is determined by the membership of the LDAP group.
Synchronization can happen once or at specified intervals. See the description of the p4 ldapsync command in the P4 Command Reference for additional information.
Before you configure group synchronization, you must configure LDAP authentication for users as explained in Authentication options.
Note
If the LDAP server requires login for read-only queries, the LDAP
configuration must contain valid bind credentials in the LDAP spec's
SearchBindDN and SearchPasswd
fields.
To configure group synchronization, you must do the following:
-
Define the following fields in the Perforce
groupspec:-
LdapConfig: The name of an LDAP configuration created using the p4 ldap command.The LDAP configuration provides the hostname, port, and encryption for the LDAP connection; it also specifies how authentication is to be done using the
SearchBindDN,searchPasswd, andGroupSearchBaseDNfields. -
LdapSearchQuery: The search query to identify the group member records. -
LdapUserAttribute: The attribute that contains the group member's user id. This user name is added to the Perforce group.
-
-
Define a group owner for the Perforce group. The owner does not have to be a member of the corresponding LDAP group.
-
Use the p4 ldapsync command, specifying which Perforce group(s) should be synchronized, to test the anticipated results using a command like the following.
p4 ldapsync -g -n my-perforce-group1 my-perforce-group2
p4 ldapsync uses the context provided by the LDAP configuration to execute the search query and collect all the defined attributes from the results that are returned. The resultant list becomes the members list of the group.
-
If you are satisfied with the preview results, run p4 ldapsync again to synchronize the groups.
To schedule synchronization to occur at regular intervals, you must make the p4 ldapsync command run at startup time and specify the value of the interval. For details see the description of the p4 ldapsync command in P4 Command Reference.
The following examples, included in Synchronizing with Active Directory and Synchronizing with OpenLDAP, demonstrate two ways in which you can define group synchronization. These examples illustrate how configurations depend on how references to users and groups are stored on different servers:
-
OpenLDAP stores a list of memberUid's in its group records; these can often be used directly as Perforce user names.
-
Active Directory stores a list of member's full DN's in its group records, and the full DN of each group a user belongs to in its user records; in this case, you need to look for the user records that contain the back reference to the group instead of finding the group record directly.
Note the difference in the GroupBaseDn in the LDAP spec. In Active Directory, we're looking for users who are in the group; in OpenLDAP, we're looking for groups that contain users. This affects the path we're searching under.
In the following examples, both servers have user under the DN
ou=users,dc=example,dc=com. We will be creating a
Perforce group called development that is populated
from the LDAP group
cn=development,ou=groups,dc=example,dc=com.
Synchronizing with Active Directory
We begin with a sample LDAP configuration named
my-ad-example defined as follows:
Name: my-ad-example Host: ad.example.com Port: 389 Encryption: tls BindMethod: search SearchBaseDN: ou=users,dc=example,dc=com SearchFilter: (&(objectClass=user)(sAMAccountName=%user%)) SearchBindDN: cn=read-only,ou=users,dc=example,dc=com SearchPasswd: password SearchScope: subtree GroupBaseDN: ou=users,dc=example,dc=com GroupSearchScope: subtree
The group spec created by the command p4 group development, would then look like this:
Group: development
LdapConfig: my-ad-example
LdapSearchQuery: (&(objectClass=user)(memberOf=cn=development,ou=groups,
dc=example,dc=com))
LdapUserAttribute: sAMAccountName
Owners: super
Synchronizing with OpenLDAP
We begin with a sample LDAP configuration named
my-openldap-example defined as follows:
Name: my-openldap-example Host: openldap.example.com Port: 389 Encryption: tls BindMethod: search SearchBaseDN: ou=users,dc=example,dc=com SearchFilter: (&(objectClass=inetOrgPerson)(uid=%user%)) SearchBindDN: cn=read-only,ou=users,dc=example,dc=com SearchPasswd: password SearchScope: subtree GroupBaseDN: ou=groups,dc=example,dc=com GroupSearchScope: subtree
The group spec created by the command p4 group development, would then look like this:
Group: development LdapConfig: my-openldap-example LdapSearchQuery: (&(objectClass=posixGrooup)(cn=development)) LdapUserAttribute: memberUid Owners: super
Deleting groups
To delete a group, invoke
p4 group -d groupname
Alternately, invoke p4 group
groupname and delete all the users
from the group in the resulting editor form. The group will be deleted
when the form is closed.
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 the logic behind the 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 in Access Levels Required by Perforce Commands 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 determines whether the user is permitted to know if the file exists. 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, the user has permission to at least list the file, and Perforce proceeds to the second pass. Otherwise, if the first matching protection found is an exclusionary mapping, or if the top of the protections table is reached without a matching protection being found, the user has no permission to even list the file, and will receive a message such as
File not on client.Example 9. Interpreting the order of mappings in the protections table
Suppose the protections table is as follows:
write user * * //... read user edk * -//... read user edk * //depot/elm_proj/...
If Ed runs p4 print //depot/file.c, 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 list the file.
-
If the first pass is successful, Perforce makes a second pass at the protections table; 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, and file argument, and has an access level greater than or equal to the access level required by the given command, 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, the user has no permission to run the command, and receives a message such as:
You don't have permission for this operation
Access Levels Required by Perforce Commands
The following table lists the minimum access level required to run 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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The |
|
|
|
The |
|
|
|
|
|
|
|
The |
|
|
|
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 |
|
|
|
|
|
configure |
super |
|
|
copy |
list |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The |
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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
The
The |
|
|
|
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 user must have |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
The
The |
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Must be connected to a Perforce Proxy. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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. |
|
|
|
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 |
|
|
|
|
|
|
|
The |
|
|
|
|
|
|
|
|
|
|
|
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 |
|
|
|
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.
If the |
|
|
|
|
|
|
|
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. |
Commands that list files, such as p4 describe, list
only those files to which the user has at least list
access.
Some commands (for example, p4 change, when you edit a
previously submitted changelist) take a -f flag
that can only be used by Perforce superusers. See
Forcing operations with the -f flag for details.