Perforce server administration for studios without a dedicated admin

Perforce server administration when nobody is the full-time admin

Perforce is built to hold every asset and revision of a large Unreal production, and it gives administrators precise control over who can do what. In a studio of twenty people that control usually lands on a lead programmer or a technical artist who also has a milestone to ship. The tasks are not hard one by one. What makes them risky is that they are rare, they are server-wide, and some cannot be undone.

• Onboarding and offboarding: creating Perforce users, resetting passwords, adding people to groups.
• Depots and streams: creating a stream depot with its mainline, cleaning up an old depot.
• Server settings: configurables that some changes need a restart for, and a few that should not be touched from a form at all.
• Clean-up: p4 obliterate to remove content that should never have been submitted. It is permanent: after it runs, the server has no record that those files ever existed.
• Support: finding the command that has been running for an hour and stopping it.
• Accountability: knowing afterwards who changed what, and why.

The usual answer is P4Admin or the command line, used by whoever remembers how. The risk is not the tool: it is that a server-wide change made by one person, from memory, leaves no reason attached and no one who looked at it before it applied.

How Gameheim handles Perforce server administration

Each Perforce project in Gameheim has a P4 Administration area for its server. Commands run through the Gameheim agent on the administrator's machine, with that person's Perforce credentials, so the Perforce server stays the authority: if your Perforce account cannot do something, Gameheim cannot do it for you either.

Access follows Perforce access levels

The area opens for users whose Perforce access on the server is at least admin. Some cards need super. Your effective level is the lower of two things: what the Perforce server reports for you, and a ceiling set in Gameheim. Leads and admins of the organization have the highest ceiling automatically. For anyone else, a lead opens Team, clicks Panel access and enables the member up to a chosen level. The ceiling never grants more than Perforce does.

Dual approval for destructive changes

An organization can turn on Dual approval in Settings > Organization. When it is on, deleting a Perforce user, group or depot, saving permissions, saving the typemap and changing a small set of sensitive configurables do not apply immediately: they become a request that another eligible person must approve. Obliterate always goes through approval, whether the setting is on or off.

• You cannot approve your own request.
• The approver must be an explicit member of the project and have the Perforce level the action needs: admin for group deletion and obliterate, super for the others.
• Requests expire after the Approval TTL (72 hours by default, from 24 to 336). An expired request can be resubmitted from My requests.
• Approvers see pending requests on the Dual approval page (Inbox), open to organization leads and admins, and through a shield badge in the top bar.

Every admin action lands in the project Audit log with its outcome, so the question "who did this" has an answer. See Audit log and account security for the organization-wide log.

How to administer a Perforce server in Gameheim

1. 1

   Open P4 Administration from the workspace

   Open P4 Workspace and click P4 Administration. The link appears once Gameheim has confirmed your access. The header shows the server address and Your access: with your effective level.

2. 2

   Decide on dual approval before you need it

   A lead or admin opens Settings > Organization, finds the Dual approval card, sets Require for destructive actions to enabled, adjusts Approval TTL if needed and clicks Save. Do this while nothing is urgent: it is much easier to agree on who approves before the first incident.

3. 3

   Manage users and groups

   In Members (page P4 Users) click New user, pick the Type (Standard, Operator or Service) and set an Initial password. The password is shown once after creation and is not stored in the cloud; tick Force change on first login for people. In Teams (page P4 Groups) click New group and list Owners, Users and Subgroups.

4. 4

   Create a stream depot

   In Depots (page P4 Depots) click New depot. Gameheim creates a stream depot and can Also create initial streams of type Mainline, Development, Release, Task or Virtual, each with its parent. Creating, editing and deleting depots needs super.

5. 5

   Review what happened

   Open Audit log and filter by action, actor or target. Each row shows When, Action, Actor, Target and Outcome. Rows that changed permissions can be reverted from there.

Perforce admin tasks in Gameheim: every card and who can use it

Onboarding and offboarding Perforce users

From the command line, a super user creates an account and hands it over in three commands, then adds it to a group:

p4 user -f jane          # fill in Email and FullName, save
p4 passwd jane           # set the initial password
p4 admin resetpassword -u jane   # force a change at first login
p4 group artists         # add jane under Users:

Offboarding takes more care, because a Perforce user owns more than a login:

1. Check for work still open with p4 opened -u jane, and shelve or revert what the team needs to keep.
2. List the workspaces with p4 clients -u jane and delete the ones nobody needs with p4 client -d -f <workspace>.
3. List the groups with p4 groups jane, remove the user from each with p4 group, and look for protections lines that name the user.
4. Delete the user with p4 user -d -f jane. Submitted changelists stay in history under that name.

Editing the Perforce protections table without locking people out

The protections table decides who can read, write or administer each depot path. It is read from top to bottom and a later line can override an earlier one, so a single misplaced line can remove access for a whole group. The safe manual routine:

1. Save a copy first: p4 protect -o > protect-backup.txt.
2. Edit with p4 protect. Each line reads access level, user or group, name, host, path. A path starting with - removes access instead of granting it.
3. Check the effect on a real person before telling the team: p4 protects -m -u jane //depot/Game/... prints the highest access that user has on that path.
4. If something is wrong, load the copy back with p4 protect -i < protect-backup.txt.

Changing Perforce configurables safely

From a shell, p4 configure show lists the values that are set, p4 configure set name=value changes one and p4 configure unset name returns it to the default; all three need super. Nothing in the command tells you whether a setting takes effect at once or only after a restart: that is in the configurables reference, and it is the reason to write the old value down before changing it.

The Server configurables page lists every active configurable with its current value and source, and sorts each into one of three tiers:

• Safe: edit and save, applied directly.
• Restart: takes effect only after a server restart, so saving asks you to acknowledge that first. Configurables Gameheim does not recognize are treated as Restart, to be cautious.
• Danger: read-only in the browser, with a note to apply the change from the P4 command line. These are the settings where a wrong value can take the server down, and they deserve a maintenance window and a shell.

Every change can carry a reason, which appears in the audit log and, when approval is needed, in the approval request. View history shows earlier values of a configurable.

How to obliterate files in Perforce without regretting it

p4 obliterate permanently removes files and their history. Run without -y it only reports what it would remove, and Perforce recommends always doing that first. If you only want files gone from the head revision, p4 delete is the reversible choice. From the command line, the careful routine is:

1. Make sure a recent checkpoint exists, from your scheduled backup or with p4 admin checkpoint. It is the only way back.
2. Preview: p4 obliterate //depot/Game/Content/OldLevel/.... Without -y nothing is removed.
3. Read the report and narrow the path until it lists only what you mean to remove. A path one level too high can take a whole project with it.
4. Run the same command, unchanged, with -y.

p4 obliterate //depot/Game/Content/OldLevel/...      # report only
p4 obliterate -y //depot/Game/Content/OldLevel/...   # permanent

Monitoring: active sessions, topology and the message of the day

• Active sessions shows the running commands on the server (PID, owner, client, host, command, runtime, status) and can be filtered. To stop one, a super user clicks Terminate session and types the PID to confirm, so the wrong row cannot be killed by a misclick. The list relies on the Perforce monitor configurable being enabled.
• Topology lists the servers that make up the installation, their services and replica lag. It refreshes when you ask, or every 30 seconds while the tab is visible if you turn that on. A single-server install without server records shows no entries, which is normal.
• Message of the Day reads and edits the message P4V clients see on connect. Clients see a change on their next connection.

The command-line equivalent for running commands, if you need it from a shell: turn monitoring on once, list the running commands with their arguments, then stop one by its ID. Terminating needs super access.

p4 configure set monitor=1
p4 monitor show -al
p4 monitor terminate 12345

Permission snapshots, reverts and the project audit log

Every write to the protections table from Gameheim first takes an encrypted snapshot. Snapshots lists them with the time, rows and reason. A super user can revert to one; the current state is captured first, so a revert can itself be reverted.

Snapshots are kept while they are among the last 100 or younger than 90 days. Older ones expire unless flagged with Flag as milestone (useful for a pre-launch baseline), and expired snapshots are purged 30 days later. The audit entries that reference them are never deleted.

In Audit log the Outcome column tells apart a change that applied (APPLIED), one Gameheim refused (DENIED_BY_CLOUD), one the Perforce server refused (DENIED_BY_P4) and one that failed on the server (FAILED_P4).

Frequently asked questions