p4 group

Add or delete users from a group, or set the maxresults, maxscanrows, maxlocktime, and timeout limits for the members of a group.

Syntax conventions

p4 [g-opts] group [-a | -A] groupname
p4 [g-opts] group -d [-a | -F] groupname
p4 [g-opts] group -o groupname
p4 [g-opts] group -i [-a | -A]

Description

A group is a list of Helix Server users. Use groups to:

  • set access levels in the p4 protect form
  • limit the maximum amount of data that can be retrieved from Helix Server by particular users with a single command
  • set the timeout period for p4 login tickets
  • provide information for the p4 ldapsync command

To delete a group, use p4 group -d groupname, or call p4 group groupname and remove all the users from the resulting form.

To force deletion and remove the group from the protections table and from all groups, use the -F option with the -d option.

Tip

The same name can be used for a group and a user because user and group names occupy separate namespaces. For example, alexandria, charlotte, or victoria can refer both to:

  • the group whose members are located in a city named Alexandria, Charlotte, or Victoria
  • the user named Alexandria, Charlotte, or Victoria
Important

As shown in Example of a group specification, service users required for inter-server communication should be a member of a group with the Timeout: field set to unlimited. Otherwise, a service user's ticket can become invalid, which would prevent replication. For more information on service users, see Types of users in the p4 user topic.

Form Fields

Field Name Type Description

Group:

Read-only

The name of the group, as entered on the command line.

Description: Writable A description about this group (optional). If your company has many groups, it might be useful to add a description.

MaxResults:

Writable

The maximum number of results that members of this group can access from the service from a single command. The default value is unset. See Usage Notes.

MaxScanRows:

Writable

The maximum number of rows that members of this group can scan from the service from a single command. The default value is unset. See Usage Notes.

MaxLockTime:

Writable

The maximum length of time (in milliseconds) that any one operation can lock any database table when scanning data. The default value is unset. See Usage Notes.

MaxOpenFiles:

Writable

The maximum number of files that a member of a group can open using a single command. See Usage Notes.

Timeout:

Writable

The duration (in seconds) of the validity of a session ticket created by p4 login. The default value is 43,200 seconds (12 hours).

If a user belongs to multiple groups, unset is ignored and the largest timeout value of that user's groups takes effect.

To create a ticket that does not expire, set the Timeout: field to unlimited. See Usage Notes.

PasswordTimeout:

Writable

The length of time (in seconds) that passwords for users in this group remain valid.

If the value is unset, the password never expires.

  • A user that belongs to no group gets the default value of unset.
  • A user that belongs to multiple groups gets largest PasswordTimeout value of those groups.

See Usage Notes.

LdapConfig

Writable

The LDAP configuration to use when populating the group’s user list from an LDAP query. See p4 ldapsync.

LdapSearchQuery

Writable

The LDAP query used to identify the members of the group. See p4 ldapsync.

LdapUserAttribute

Writable

The LDAP attribute that represents the user’s username. See p4 ldapsync.

LdapUserDNAttribute: Writable The LDAP attribute in the group object that contains the DN (distinguished name) of the user object.

Subgroups:

Writable, multi-line

Names of other Helix Server groups. To add all users in a previously defined group to the group you’re presently working with, include the group name in the Subgroups: field of the p4 group form. Every member of any previously defined group you list in the Subgroups: field will be a member of the group you’re now defining.

Owners:

Writable, multi-line

Names of other Helix Server users.

Group owners without super access are permitted to administer this group, provided that they use the -a option.

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.

Note

The specified owner does not have to be a Helix Server user. You might want to use an arbitrary name if the user does not yet exist, or if you have deleted the user and need a placeholder until you can assign the spec to a new user.

Users:

Writable, multi-line

The Helix Server usernames of the group members. Each user name must be typed on its own line and be indented.

Options

-a

Allow a (non-superuser) group owner to administer the group. The user must be listed in the Owner: field of the group.

-A

Allow a user with admin access to add a new group. Existing groups cannot be modified when this option is used.

-d groupname

Delete group groupname. The members of the group are affected only if their access level or maxresults value changes as a result of the group’s deletion.

-F groupname

Used only with the -d option, forces the deletion of the specified group, and also removes the group from the protections table and from all groups.

-i

Read the form from standard input without invoking the user’s editor. The new group specification replaces the previous one.

-o

Write the form to standard output without invoking the user’s editor.

g-opts

See Global options.

Usage Notes

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

N/A

N/A

super
(admin for p4 group -A)
(list for p4 group -o or -a)

  • Referring to a (nonexistent) user in a group definition does not create the user, nor does it consume a license. To create users, use the p4 user command.
  • Ticket Timeout and PasswordTimeout values for users who belong to multiple groups are calculated the same way as maxresults values: the largest timeout value for all the groups of which the user is a member (including unlimited, but ignoring unset). Users in no groups have the default ticket Timeout value of 43200 and PasswordTimeout value of unset. To create a ticket that does not expire, set the Timeout to unlimited.
  • If you are using the PasswordTimeout: field to implement password aging, a 30-day timeout is 2,592,000 seconds.
  • As the number of files in the depot grows, certain commands can significantly slow down the service if called with no parameters, or if called with non-restrictive arguments. For example, p4 print //depot/... will print the contents of every file in the depot on the user’s screen, and p4 filelog //depot/... will attempt to retrieve data on every file in the depot at every revision.

    The Helix Server superuser can limit the amount of data that Helix Server returns to the user by setting the MaxResults value for groups of users. The superuser can also limit the amount of data scanned (whether returned to the user or not) by setting the MaxScanRows value, and the length of time any database table can be locked in by any single operation by setting the MaxLockTime value. Equally, the MaxOpenFiles field can be set to specify the maximum number of files that a group member can open at any given time.

    If any of the MaxResults, MaxScanRows, MaxLockTime, or MaxOpenFiles limits are violated, the request fails and the user is asked to limit the query.

    If a user belongs to multiple groups, the service computes her MaxResults value to be the maximum of the MaxResults for all the groups of which the user is a member (removing the limit if it encounters a setting of unlimited, but ignoring any settings still at the default value of unset). If a particular user is not in any groups, her MaxResults value is unset. (The user’s MaxScanRows, MaxLockTime, and MaxOpenFiles limits are computed in the same way.)

    The speed of most hardware should make it unnecessary to ever set a MaxResults value below 10,000, a MaxScanRows value below 50,000, or a MaxLockTime value below 1,000.

    A user can also set these limits by specifying them on a per-command basis for some commands. Values set for individual commands override values set using p4 group. To disable overriding p4 group settings, set server.commandlimits=2.

  • To unload a workspace or label, a user must be able to scan all the files in the workspace’s have list and/or files tagged by the label. Administrators should set MaxScanRows and MaxResults high enough that users will not need to ask for assistance with p4 unload or p4 reload operations.
  • To display a group’s maxresults, maxscanrows, maxlocktime, and timeout limits, use p4 groups -v groupname.
  • Use p4 help maxresults to obtain the list of commands that are affected by any of the four limiting values.
  • See also the following topics in Helix Core Server Administrator Guide:

Example of a group specification

This example shows the best practice of putting service users in a group, and making sure that the service users are never blocked by the expiration of their connection or password.

$ p4 group service_users

Add service1 to the list of Users: in the group, and set the Timeout: and PasswordTimeout: values to unlimited.

Group:            service_users
Description:      This group is responsible for x,y,z and works in locations A and B
Timeout:          unlimited
PasswordTimeout:  unlimited
Subgroups:
Owners:
Users:
        service1

Related Commands

To modify users' access levels

p4 protect

To view a list of existing groups

p4 groups

To synchronize LDAP and Helix Server groups

p4 ldapsync