Perforce Server (p4d) Reference

Synopsis

Start the Perforce service or perform checkpoint/journaling (system administration) tasks.

Syntax

p4d [ options ]
p4d.exe [ options ]
p4s.exe [ options ]
p4d -j? [ -z | -Z ] [ args ... ]

Description

The first three forms of the command invoke the background process that manages the Perforce versioning service. The fourth form of the command is used for system administration tasks involving checkpointing and journaling.

On UNIX and Mac OS X, the executable is p4d.

On Windows, the executable is p4d.exe (running as a server) or p4s.exe (running as a service).

Exit Status

After successful startup, p4d does not normally exit. It merely outputs the following startup message: 

Perforce server starting...

and runs in the background.

On failed startup, p4d returns a nonzero error code.

Also, if invoked with any of the -j checkpointing or journaling options, p4d exits with a nonzero error code if any error occurs.

Options

Server options Meaning

-d

Run as a daemon (in the background)

-f

Run as a single-threaded (non-forking) process

-i

Run from inetd on UNIX

-q

Run quietly (no startup messages)

--pid-file[=file]

Write the PID of the server to a file named server.pid in the directory specified by P4ROOT, or write the PID to the file specified by file. This makes it easier to identify a server instance among many.

The file parameter can be a complete path specification. The file does not have to reside in P4ROOT.

-xi

Irreversibly reconfigure the Perforce server (and its metadata) to operate in Unicode mode. Do not use this option unless you know you require Unicode mode. See the Release Notes and Internationalization Notes for details.

-xu

Run database upgrades and exit.

This will no longer run automatically if there are fewer than 1000 changelists. Upgrades must be run manually unless the server is a DVCS personal server; in this case, any upgrade steps are run automatically.

-xv

Run low-level database validation and quit.

-xvU

Run fast verification; do not lock database tables, and verify only that the unlock count for each table is zero.

-xD [ serverID ]

Display (or set) the server’s serverID (stored in the server.id file) and exit.

General options Meaning

-h, -?

Print help message.

-V

Print version number.

-A auditlog

Specify an audit log file. Overrides P4AUDIT setting. Default is null.

-Id description

A server description for use with p4 server. Overrides P4DESCRIPTION setting.

-In name

A server name for use with p4 configure. Overrides P4NAME setting.

-J journal

Specify a journal file. Overrides P4JOURNAL setting. Default is journal. (Use -J off to disable journaling.)

-L log

Specify a log file. Overrides P4LOG setting. Default is STDERR.

-p port

Specify a port to listen to. Overrides P4PORT. Default 1666.

-r root

Specify the server root directory. Overrides P4ROOT. Default is current working directory.

-v subsystem=level

Set trace options. Overrides value P4DEBUG setting. Default is null.

-C1

Force the service to operate in case-insensitive mode on a normally case-sensitive platform.

--pid-file[=name]

Write the server’s PID to the specified file.

Default name for the file is server.pid
Checkpointing options Meaning

-c command

Lock database tables, run command, unlock the tables, and exit.

-jc [ prefix ]

Journal-create; checkpoint and .md5 file, and save/truncate journal.

In this case, your checkpoint and journal files are named prefix.ckp.n and prefix.jnl.n respectively, where prefix is as specified on the command line and n is a sequence number. If no prefix is specified, the default filenames checkpoint.n and journal.n are used. You can store checkpoints and journals in the directory of your choice by specifying the directory as part of the prefix.

Warning

If you use this option, it must be the last option on the command line.

-jd file

Journal-checkpoint; create checkpoint and .md5 file without saving/truncating journal.

-jj [ prefix ]

Journal-only; save and truncate journal without checkpointing.

-jr file

Journal-restore; restore metadata from a checkpoint and/or journal file.

If you specify the -r $P4ROOT option on the command line, the -r option must precede the -jr option.

-jv file

Verify the integrity of the checkpoint or journal specified by file as follows:

  • Can the checkpoint or journal be read from start to finish?
  • If it’s zipped can it be successfully unzipped?
  • If it has an MD5 file with its MD5, does it match?
  • Does it have the expected header and trailer?

This command does not replay the journal.

Use the -z option with the -jv option to verify the integrity of compressed journals or compressed checkpoints.

-z

Compress (in gzip format) checkpoints and journals.

When you use this option with the -jd option, Perforce automatically adds the .gz extension to the checkpoint file. So, the command:

p4d -jd -z myCheckpoint

creates two files: myCheckpoint.gz and myCheckpoint.md5.

-Z

Compress (in gzip format) checkpoint, but leave journal uncompressed for use by replica servers. That is, it applies to -jc, not -jd.

Journal restore options Meaning

-jrc file

Journal-restore with integrity-checking. Because this option locks the database, this option is intended only for use by replica servers started with the p4 replicate command.

-jrF file

Allow replaying a checkpoint over an existing database. (Bypass the check done by the -jr option to see if a checkpoint is being replayed into an existing database directory by mistake.)

-b bunch -jr file

Read bunch lines of journal records, sorting and removing duplicates before updating the database. The default is 5000, but can be set to 1 to force serial processing. This combination of options is intended for use with by replica servers started with the p4 replicate command.

-f -jr file

Ignore failures to delete records; this meaning of -f applies only when -jr is present. This combination of options is intended for use with by replica servers started with the p4 replicate command. By default, journal restoration halts if record deletion fails.

As with all journal-restore commands, if you specify the -r $P4ROOT option on the command line, the -r option must precede the -jr option.

-m -jr file

Schedule new revisions for replica network transfer. Required only in environments that use p4 pull -u for archived files, but p4 replicate for metadata. Not required in replicated environments based solely on p4 pull.

-s -jr file

Record restored journal records into regular journal, so that the records can be propagated from the server’s journal to any replicas downstream of the server. This combination of options is intended for use in conjunction with Perforce technical support.

Replication and multi-server options Meaning

-a host:port

In multi-server environments, specify an authentication server for licensing and protections data. Overrides P4AUTH setting. Default is null.

-g host:port

In multi-server environments, specify a changelist server from which to obtain changelist numbers. Overrides P4CHANGE setting. Default is null.

-t host:port

For replicas, specify the target (master) server from which to pull data. Overrides P4TARGET setting. Default is null.

-u serviceuser

For replicas, authenticate as the specified serviceuser when communicating with the master. The service user must have a valid ticket before replica operations will succeed.

Journal dump/restore filtering Meaning

-jd file db.table

Dump db.table by creating a checkpoint file that contains only the data stored in db.table

This command can also be used with non-journaled tables.

-k db.table1,db.table2,... -jd file

Dump a set of named tables to a single dump file.

-K db.table1,db.table2,... -jd file

Dump all tables except the named tables to the dump file.

-P serverid -jd file

Specify filter patterns for p4d -jd by specifying a serverid from which to read filters (see p4 help server, or use the older syntax described in p4 help export.)

This option is useful for seeding a filtered replica.

-k db.table1,db.table2,... -jr file

Restore from file, including only journal records for the tables named in the list specified by the -k option.

-K db.table1,db.table2,... -jr file

Restore from file, excluding all journal records for the tables named in the list specified by the -K option.

Certificate Handling Meaning

-Gc

Generate SSL credentials files for the server: create a private key and certificate file in P4SSLDIR, and then exit.

Requires that P4SSLDIR be set to a directory that is owned by the user invoking the command, and that is readable only by that user. If config.txt is present in P4SSLDIR, generate a self-signed certificate with specified characteristics.

-Gf

Display the fingerprint of the server’s public key, and exit.

Administrators can communicate this fingerprint to end users, who can then use the p4 trust command to determine whether or not the fingerprint (of the server to which they happen to be connecting) is accurate.

Configuration options Meaning

-cshow

Display the contents of db.config without starting the service. (That is, run p4 configure show allservers, but without a running service.)

-cset server#var=val

Set a Perforce configurable without starting the service, optionally specifying the server for which the configurable is to apply. For example, 

p4d -r . "-cset replica#P4JOURNAL=off"
p4d -r .  "-cset replica#P4JOURNAL=off replica#server=3"

It is best to include the entire variable=value expression in quotation marks.

-cunset server#var

Unset the specified configurable.

Usage Notes

  • On all systems, journaling is enabled by default. If P4JOURNAL is unset when p4d starts, the default location for the journal is $P4ROOT. If you want to manually disable journaling, you must explicitly set P4JOURNAL to off.
  • Take checkpoints and truncate the journal often, preferably as part of your nightly backup process.
  • Checkpointing and journaling preserve only your Perforce metadata (data about your stored files). The stored files themselves (the files containing your source code) reside under P4ROOT and must be also be backed up as part of your regular backup procedure.
  • It is best to keep journal files and checkpoints on a different hard drive or network location than the Perforce database.
  • If your users use triggers, don’t use the -f (non-forking mode) option; the Perforce service needs to be able to spawn copies of itself ("fork") in order to run trigger scripts.
  • After a hardware failure, the options required for restoring your metadata from your checkpoint and journal files can vary, depending on whether data was corrupted.
  • Because restorations from backups involving loss of files under P4ROOT often require the journal file, we strongly recommend that the journal file reside on a separate filesystem from P4ROOT. This way, in the event of corruption of the filesystem containing P4ROOT, the journal is likely to remain accessible.
  • The database upgrade option (-xu) can require considerable disk space. See the Release Notes for details when upgrading.

Related Commands

To start the service, listening to port 1999, with journaling enabled and written to journalfile.

p4d -d -p 1999 -J /opt/p4d/journalfile

To checkpoint a server with a non-default journal file, the -J option (or the environment variable P4JOURNAL) must match the journal file specified when the server was started.

Checkpoint with:

p4d -J /p4d/jfile -jc

or

P4JOURNAL=/p4d/jfile ; export P4JOURNAL; p4d -jc

To create a compressed checkpoint from a server with files in directory P4ROOT

p4d -r $P4ROOT -z -jc

To create a compressed checkpoint with a user-specified prefix of “ckp” from a server with files in directory P4ROOT

p4d -r $P4ROOT -z -jc ckp

To restore metadata from a checkpoint named checkpoint.3 for a server with root directory P4ROOT

p4d -r $P4ROOT -jr checkpoint.3

(The -r option must precede the -jr option.)

To restore metadata from a compressed checkpoint named checkpoint.3.gz for a server with root directory P4ROOT

p4d -r $P4ROOT -z -jr checkpoint.3.gz

(The -r option must precede the -jr option.)