Installing and Upgrading the Server

This chapter describes how to install the Perforce service or upgrade an existing installation. It contains information about the following topics:

  • Pre-requisites for installation
  • Where to obtain installation files
  • Installing on UNIX (or Mac OS X)
  • Installing on Windows
  • Default location of installed files
  • Upgrading your installation
  • License requirements

Many of the examples in this book are based on the UNIX version of the Perforce service. In most cases, the examples apply equally to both Windows and UNIX installations. The material for UNIX also applies to Mac OS X.

Warning

If you are upgrading an existing installation to Release 2013.3 or later, see the notes in Upgrading the Perforce service before proceeding.

Install architecture

The chapter “Overview” describes the two deployment options that are covered in this book. This chapter focuses on the installation of the server for connected clients. See the "Install" chapter of Using Helix for Distributed Versioning for information on how to install a server that supports clients who want to work disconnected.

Planning the installation

The following sections describe some of the issues you need to think about before installing and configuring the server.

Network

Perforce can run over any TCP/IP network. For remote users or distributed configurations, Perforce offers options like proxies and the commit/edge architecture that can enhance performance over a WAN. Compression in the network layer can also help. For additional information about network and performance tuning, see “Tuning Perforce for Performance”.

CPU

CPU resource consumption can be adversely affected by compression, lockless reads, or a badly designed protections table. In general, there is a trade-off between speed and the number of cores. A minimum of 2.4 GHZ and 8 cores is recommended. With greater speed, fewer cores will do: for example, a 3.2 GHZ and 4-core processor will also work.

For additional details, see CPU.

Memory

There are a couple of guidelines you can follow to anticipate memory needs:

  • Multiply the number of licensed users by 64MB.
  • Allocate 1.5 kilobytes of RAM per file in the depot.

In general Perforce performs well on machines that have large memory footprints that can be used for file system cache. I/O to even the fastest disk will be slower than reading from the file cache. These guidelines only apply for a single server.

For additional information about memory and performance tuning, see “Tuning Perforce for Performance”.

Disk space allocation

Perforce disk space usage is a function of three variables:

  • Number and size of client workspaces
  • Size of server database
  • Size of server’s archive of all versioned files

All three variables depend on the nature of your data and how heavily you use Perforce.

The client file space required is the size of the files that your users will need in their client workspaces at any one time.

The server’s database size can be calculated with a fair level of accuracy; as a rough estimate, it requires 0.5 kilobytes per user per file. (For instance, a system with 10,000 files and 50 users requires 250 MB of disk space for the database). The database can be expected to grow over time as histories of the individual files grow.

The size of the server’s archive of versioned files depends on the sizes of the original files stored and grows as revisions are added. A good guideline is to allocate sufficient space in your P4ROOT directory to hold three times the size of your users' present collection of versioned files, plus an additional 0.5KB per user per file to hold the database files that store the list of depot files, file status, and file revision histories.

The db.have file holds the list of files opened in client workspaces. This file tends to grow more rapidly than other files in the database. If you are experiencing issues related to the size of your db.have file and are unable to quickly switch to a server with adequate support for large files, deleting unused client workspace specifications and reducing the scope of client workspace views can help alleviate the problem.

Filesystem

File size and disk I/O are the key issues here. For more information, see File systems.

Filesystem performance

Perforce is judicious with regards to its use of disk I/O; its metadata is well-keyed, and accesses are mostly sequential scans of limited subsets of the data. The most disk-intensive activity is file check-in, where the Perforce server must write and rename files in the archive. Server performance depends heavily on the operating system’s filesystem implementation, and in particular, on whether directory updates are synchronous. Server performance is also highly dependent upon the capabilities of the underlying hardware’s I/O subsystem.

Although Perforce does not recommend any specific hardware configuration or filesystem, Linux servers are generally fastest (owing to Linux’s asynchronous directory updating), but they may have poor recovery if power is cut at the wrong time.

Performance in systems where database and versioned files are stored on NFS-mounted volumes is typically dependent on the implementation of NFS in question or the underlying storage hardware. Perforce has been tested and is supported using implementations that support the flock protocol.

Under Linux and FreeBSD, database updates over NFS can be an issue because file locking is relatively slow; if the journal is NFS-mounted on these platforms, all operations will be slower. In general (but in particular on Linux and FreeBSD), we recommend that the Perforce database, depot, and journal files be stored on disks local to the machine running the Perforce server process or that they be stored on a low-latency SAN device.

These issues affect only the Perforce server process (p4d). Perforce applications, (such as p4, the Perforce Command-Line Client) have always been able to work with client workspaces on NFS-mounted drives (for instance, workspaces in users' home directories).

Separate physical drives for server root and journal

Whether installing on UNIX or Windows, it is advisable to have your P4ROOT directory (that is, the directory containing your database and versioned files) on a different physical drive than your journal file.

By storing the journal on a separate drive, you can be reasonably certain that, if a disk failure corrupts the drive containing P4ROOT, such a failure will not affect your journal file. You can then use the journal file to restore any lost or damaged metadata. Separating the live journal from the db.* files can also improve performance.

Further details are available in “Backup and Recovery” and in Journal and archive location.

Protections and passwords

Until you define a Perforce superuser, every Perforce user is a Perforce superuser and can run any Perforce command on any file. After you start a new Perforce service, use:

$ p4 protect

as soon as possible to define a Perforce superuser. To learn more about how p4 protect works, see Authorizing access.

Without passwords, any user is able to impersonate any other Perforce user, either with the -u flag or by setting P4USER to an existing Perforce user name. Use of Perforce passwords prevents such impersonation. See the Helix Versioning Engine User Guide for details.

To set (or reset) a user’s password, either use p4 passwd username (as a Perforce superuser), and enter the new password for the user, or invoke p4 user -f username (also while as a Perforce superuser) and enter the new password into the user specification form.

The security-conscious Perforce superuser also uses p4 protect to ensure that no access higher than list is granted to unprivileged users, p4 configure to set the security level to a level that requires that all users have strong passwords, and p4 group to assign all users to groups (and, optionally, to require regular changes of passwords for users on a per-group basis, to set a minimum required password length for all users on the site, and to lock out users for predefined amounts of time after repeated failed login attempts).

Note

An alternate way to reduce security risk during initial setup or during a maintenance interval is to start the Perforce server using localhost:port syntax. For example:

$ p4d localhost:2019

This forces the server to ignore non-local connection requests.

For complete information about security, see “Securing the Server”.

Getting Perforce

Perforce requires at least two executables: the Perforce service (p4d on Unix, p4s.exe on Windows), and at least one Perforce application (such as p4 on UNIX, or p4.exe on Windows).

The Perforce service and applications are available from the Downloads page on the Perforce web site:

http://www.perforce.com/downloads/complete_list

Go to the web page, select the files for your platform, and save the files to disk. In addition to plain binaries, installers for Windows are also available at the above site. You are encouraged to use them.

Many components are also available as Linux packages. See instructions in the next section for installing OS-specific packages for select Linux distributions.

Linux package-based installation

The Perforce service is available in two distribution package formats: Debian (.deb) for Ubuntu systems, and RPM (.rpm) for CentOS and RedHat Enterprise Linux (RHEL).

Using distribution packages greatly simplifies the installation, update, and removal of software, as the tools that manage these packages are aware of the dependencies for each package.

You can install packages for the Perforce service on the following Linux (Intel x86_64) platforms:

  • Ubuntu 12.04 LTS
  • Ubuntu 14.04 LTS
  • Ubuntu 16.04 LTS
  • CentOS or Red Hat 6.x
  • CentOS or Red Hat 7.x

During the course of the installation, you will be asked to make choices about case sensitivity and Unicode settings. Please read the following sections now to understand the consequences of your selections:

Make sure, before you start the install, that you have root level access to the server that will host your Perforce service.

Installation

  1. Configure the Perforce package repository.

    As root, run one of the following:

    1. For Ubuntu 12.04:

      Create the file /etc/apt/sources.list.d/perforce.list with the following content:

      deb http://package.perforce.com/apt/ubuntu/ precise release
    2. For Ubuntu 14.04:

      Create the file /etc/apt/sources.list.d/perforce.list with the following content:

      deb http://package.perforce.com/apt/ubuntu/ trusty release
    3. For Ubuntu 16.04:

      Create the file /etc/apt/sources.list.d/perforce.list with the following content:

      deb http://package.perforce.com/apt/ubuntu/ xenial release
    4. For CentOS/RHEL 6:

      Create the file /etc/yum.repos.d/perforce.repo, with the following content:

      [perforce]
      name=Perforce
      baseurl=http://package.perforce.com/yum/rhel/6/x86_64/
      enabled=1
      gpgcheck=1
    5. For CentOS/RHEL 7:

      Create the file /etc/yum.repos.d/perforce.repo, with the following content:

      [perforce]
      name=Perforce
      baseurl=http://package.perforce.com/yum/rhel/7/x86_64/
      enabled=1
      gpgcheck=1
  2. Import the Perforce package signing key.

    Run one of the following:

    1. For Ubuntu:

      $ wget -qO - https://package.perforce.com/perforce.pubkey | sudo apt-key add -
    2. For CentOS/RHEL (run this command as root):

      # rpm --import https://package.perforce.com/perforce.pubkey

    For information about verifying the authenticity of the signing key, see: https://www.perforce.com/perforce-packages

  3. Install the appropriate Perforce service package.

    The Perforce service is divided into multiple packages, so you can install just the components you need. The component package names are:

    • helix-p4d
    • helix-p4dctl
    • helix-proxy
    • helix-broker
    • helix-cli

    The helix-p4d package installs the main component of a Perforce service, p4d, as well as the command line interface, the service controller, and a configuration script to set them up.

    At minimum, you need to install the helix-p4d package. To install a different package, substitute its name for helix-p4d in the commands below.

    Run one of the following:

    1. For Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get install helix-p4d
    2. For CentOS/RHEL (run this command as root):

      # yum install helix-p4d

    The files contained in the package are installed, and status information describing the main elements that have been installed is displayed.

  4. Run the post-installation configuration script.

    If you installed the helix-p4d package, and if installation was successful, proceed on to Post-installation configuration.

Post-installation configuration

After the helix-p4d package has been installed, additional configuration is required. Perform the following steps:

  1. Use the configure-helix-p4d.sh script to configure a Perforce service.

    Note

    The configure-helix-p4d.sh script can be used in a few different ways. The steps below outline the most straightforward configuration using interactive mode, but you can review the options by running:

    $ sudo /opt/perforce/sbin/configure-helix-p4d.sh -h

    Run in interactive mode:

    $ sudo /opt/perforce/sbin/configure-helix-p4d.sh

    In interactive mode, the configuration script begins by displaying a summary of default settings and those which have optionally been set with a command line argument.

  2. Provide information to the configuration script.

    After the summary, the configuration script prompts for information it needs to set up your Perforce service.

    Note

    If you already have a Perforce service configured, and you supply its service name, then the configuration script only prompts for settings that you can change on an existing service.

    At each prompt, you can accept the proposed default value by pressing Enter, or you can specify your own value.

    The list below contains details about the options for each prompt:

    1. The Service Name:

      The name used when managing this service with p4dctl, for instance when starting and stopping the service.

      This name is also used to set the Perforce serverid attribute on the underlying p4d instance, to distinguish it from others that may be in your overall installation.

    2. The Server Root (P4ROOT):

      The directory where versioned files and metadata should be stored.

    3. The Unicode Mode for the server:

      This is off by default.

      Warning

      If you turn Unicode mode on, you will not be able to turn it off. Be sure you are familiar with Unicode functionality when selecting this mode. See Setting up and managing Unicode installations for information.

    4. The Case Sensitivity for the server:

      This is on by default.

      See Case sensitivity and multi-platform development for information.

    5. The Server Address (P4PORT):

      This specifies the host and port where the Perforce service should listen, and whether to communicate in plaintext or over SSL. For more information, see Communicating port information.

    6. Superuser login:

      The desired userid for a new user to be created with super level privileges.

      For more information about superusers, see Access levels.

    7. Superuser password:

      The desired password to be set for the new superuser.

      Due to the unlimited privileges granted to this user, a strong password is required.

    After you answer all prompts, the script begins configuration according to your choices. As it runs, the script displays information about the configuration taking place.

    After the configuration has completed successfully, a summary is displayed with details about what was done, and where settings are stored.

    You can now connect to the service, or you can manage the service using the p4dctl utility. For more information, see Perforce Server Control (p4dctl).

Updating

Important

The package update commands with apt-get or yum do not complete the process of updating your Perforce service. Packages for Linux simplify only certain steps of that process.

Updating packages without completing the rest of the update process leaves your Perforce service in a precarious state. Make sure to read and understand the entire process before updating any packages.

  1. Review the general update process.

    1. See Upgrading the Perforce service for details on the general process for how to update a Perforce service, on any platform. You should read and thoroughly understand this section before continuing.
    2. Packages for Linux help you accomplish only specific steps from the general process. If you are attempting to update your Perforce service using packages, you should still follow the general process linked above, but with the package specific modifications below:

      1. You may be able to stop, checkpoint, and start your Perforce service using p4dctl:

        $ sudo -u perforce p4dctl [stop|checkpoint|start] servicename
      2. You do not need to manually retrieve the new component binaries (such as p4d) from the Perforce website; the package update commands with apt-get or yum accomplish this step.

        Platform-specific package update commands are below.

      3. You still need to upgrade the Perforce service database to use the new versions of components delivered by the packages.

        As a convenience, 2016.1 and newer packages attempt to present tailored instructions and commands on-screen for upgrading those Perforce service databases that are discovered automatically.

  2. Determine if an updated package is available.

    Note

    To update a different package, substitute its name for helix-p4d in the commands below.

    Run one of the following:

    1. For Ubuntu:

      $ sudo apt-get update
      $ sudo apt-cache madison helix-p4d
    2. For CentOS/RHEL (run this command as root):

      # yum --showduplicates list helix-p4d
  3. Install an updated package.

    Note

    To update a different package, substitute its name for helix-p4d in the commands below.

    The command to update is the same used to install initially.

    Run one of the following:

    1. For Ubuntu:

      $ sudo apt-get update
      $ sudo apt-get install helix-p4d
    2. For CentOS/RHEL (run this command as root):

      # yum install helix-p4d

    Important

    Failure to complete all update steps in the general process referenced above could result in continued downtime for your Perforce service.

UNIX non-package installation

Although you can install p4 and p4d in any directory, on UNIX, the Perforce applications typically reside in /usr/local/bin, and the Perforce service is usually located either in /usr/local/bin or in its own server root directory. You can install Perforce applications on any machine that has TCP/IP access to the p4d host.

To limit access to the Perforce service’s files, ensure that the p4d executable is owned and run by a Perforce user account that has been created for the purpose of running the Perforce service.

For an example Unix installation see:

http://answers.perforce.com/articles/KB_Article/Example-Unix-Installation

Note

To maximize performance, configure the server root (P4ROOT) to reside on a local disk and not an NFS-mounted volume. Perforce’s file-locking semantics work with NFS mounts on Solaris 2.5.1 and later; some issues still remain regarding file locking on noncommercial implementations of NFS (for instance, Linux and FreeBSD). It is best to place metadata and journal data on separate drives

These issues affect only the Perforce server process (p4d). Perforce applications (such as p4, the Perforce Command-Line Client) have always been able to work with client workspaces on NFS-mounted drives, such as client workspaces located in users' home directories.

To start using Perforce:

  1. Download the p4 and p4d applications for your platform from the Perforce web site.
  2. Make the downloaded p4 and p4d files executable.
  3. Create a server root directory to hold the Perforce database and versioned files.
  4. Tell the Perforce service what port to listen to by specifying a TCP/IP port to p4d.
  5. Start the Perforce service (p4d).
  6. Set the p4d port and address for Perforce applications by setting the P4PORT environment variable.

Downloading the files and making them executable

On UNIX (or Mac OS X), you must make the p4 and p4d binaries executable. After you download the software, use the chmod command to make them executable, as follows:

$ chmod +x p4
$ chmod +x p4d

Creating a Perforce server root directory

The Perforce service stores all user-submitted files and system-generated metadata in files and subdirectories beneath its own root directory. This directory is called the server root.

To specify a server root, either set the environment variable P4ROOT to point to the server root, or use the -r server_root flag when invoking p4d. Perforce applications never use the P4ROOT directory or environment variable; p4d is the only process that uses the P4ROOT variable.

Because all Perforce files are stored by default beneath the server root, the contents of the server root can grow over time. See Disk space allocation for information about diskspace requirements.

The Perforce service requires no privileged access; there is no need to run p4d as root or any other privileged user. For more information, see Running p4d as an unprivileged user.

The server root can be located anywhere, but the account that runs p4d must have read, write, and execute permissions on the server root and all directories beneath it. For security purposes, set the umask(1) file-creation-mode mask of the account that runs p4d to a value that denies other users access to the server root directory.

Telling Perforce applications which port to connect to

The p4d service and Perforce applications communicate with each other using TCP/IP. When p4d starts, it listens (by default) for plaintext connections on port 1666. Perforce applications like p4 assume (also by default) that the corresponding p4d is located on a host named perforce, listening on port 1666, and that communications are performed in plaintext.

If p4d is to listen on a different host or port and/or use a different protocol, either specify the configuration with the -p protocol:host:port flag when you start p4d (as in, p4d -p ssl:perforce:1818), or by the contents of the P4PORT environment variable.

Plaintext communications are specified with tcp:host:port and SSL encryption is specified with ssl:port. (To use SSL, you must also supply or generate an x509 certificate and private key, and store them in a secure location on your server. See Using SSL to encrypt connections to a Helix server for details.)

The preferred syntax for specifying the port is the following:

protocol:host:port

There are situations, for example if you are using multiple network cards, where you might want to specify the port on which to listen using syntax like the following:

P4PORT=ssl::1666

The use of the double colon directs the server to bind to all available network addresses and to listen on port 1666. This can be useful if the host has multiple network addresses.

Note

To enable IPv6 support, specify the wildcard address with two colons when starting p4d. For example:

$ p4d -p tcp64:[::]:1818

starts a Perforce service that listens for plaintext connections, on both IPv6 and IPv4 transports, on port 1818. Similarly,

$ p4d -p ssl64:[::]:1818

starts a Perforce service that requires SSL and listens on IPv6 and IPv4, and

$ p4d -p ssl6:[::]:1818

starts a Perforce service that requires SSL connections, and listens for IPv6 connections exclusively.

See IPv6 support and mixed networks for more information about IPv6 and IPv4 transports.

Unlike P4ROOT, the environment variable P4PORT is used by both the Perforce service and the Perforce applications, so it must be set both on the machine that hosts the Perforce service and on individual user workstations.

Communicating port information

Perforce applications need to know on what machine the p4d service is listening, on which TCP/IP port p4d is listening, and whether to communicate in plaintext or over SSL.

Set each Perforce user’s P4PORT environment variable to protocol:host:port, where protocol is the communications protocol (beginning with ssl: for SSL, or tcp: for plaintext), host is the name of the machine on which p4d is running, and port is the number of the port on which p4d is listening. For example:

P4PORT Behavior

tcp:dogs:3435

Perforce applications connect in plaintext to the Perforce service on host dogs listening on port 3435.

tcp64:dogs:3435

Perforce applications connect in plaintext to the Perforce service on host dogs listening on port 3435. The application first attempts to connect over an IPv6 connection; if that fails, the application attempts to connect via IPv4.

ssl:example.org:1818

Perforce applications connect via SSL to the Perforce service on host example.org listening on port 1818.

<not set>

Perforce applications connect to the Perforce service on a host named or aliased perforce listening on port 1666. Plaintext communications are assumed.

If you have enabled SSL, users are shown the server’s fingerprint the first time they attempt to connect to the service. If the fingerprint is accurate, users can use the p4 trust command (either p4 trust -y, or p4 -p ssl:host:port trust -i fingerprint) to install the fingerprint into a file (pointed to by the P4TRUST environment variable) that holds a list of known/trusted Perforce servers and their respective fingerprints. If P4TRUST is unset, this file is .p4trust in the user’s home directory.

IPv6 support and mixed networks

As of Release 2013.1, Perforce supports connectivity over IPv6 networks as well as over IPv4 networks.

Behavior and performance of networked services is contingent not merely upon the networking capabilities of the machine that hosts the service, nor only on the operating systems used by the end users, but also on your specific LAN and WAN infrastructure (and the state of IPv6 support for every router between the end user and the Perforce versioning service).

To illustrate just one possible scenario, a user working from home; even if they have an IPv6-based home network, their ISP or VPN provider may not fully support IPv6. We have consequently provided several variations on P4PORT to provide maximum flexibility and backwards compatibility for administrators and users during the transition from IPv4 to IPv6.

P4PORT protocol value Behavior in IPv4/IPv6 or mixed networks

<not set>

Use tcp4: behavior, but if the address is numeric and contains two or more colons, assume tcp6: If the net.rfc3484 configurable is set, allow the OS to determine which transport is used.

tcp:

Use tcp4: behavior, but if the address is numeric and contains two or more colons, assume tcp6: If the net.rfc3484 configurable is set, allow the OS to determine which transport is used.

tcp4:

Listen on/connect to an IPv4 address/port only.

tcp6:

Listen on/connect to an IPv6 address/port only.

tcp46:

Attempt to listen/connect to an IPv4 address. If this fails, try IPv6.

tcp64:

Attempt to listen/connect to an IPv6 address. If this fails, try IPv4.

ssl:

Use ssl4: behavior, but if the address is numeric and contains two or more colons, assume ssl6: If the net.rfc3484 configurable is set, allow the OS to determine which transport is used.

ssl4:

Listen on/connect to an IPv4 address/port only, using SSL encryption

ssl6:

Listen on/connect to an IPv6 address/port only, using SSL encryption.

ssl46:

Listen on/connect to an IPv4 address/port. If that fails, try IPv6. After connecting, require SSL encryption.

ssl64:

Listen on/connect to an IPv6 address/port. If that fails, try IPv4. After connecting, require SSL encryption.

In mixed environments it is good practice to set the net.rfc3484 configurable to 1:

$ p4 configure set net.rfc3484=1

Doing so ensures RFC3484-compliant behavior for users who do not explicitly specify the protocol value; that is, if the client-side configurable net.rfc3484 is set to 1, and P4PORT is set to example.com:1666, or tcp:example.com:1666, or ssl:example.com:1666, the user’s operating system will automatically determine, for any given connection, whether to use IPv4 or IPv6 transport.

In multi-server environments, net.rfc3484, when set server-side, also controls the behavior of of host resolution when initiating server-to-server (or proxy, broker, etc.) communications.

Running p4d as an unprivileged user

Perforce does not require privileged access. For security reasons, do not run p4d as root or otherwise grant the owner of the p4d process root-level privileges.

Create an unprivileged UNIX user (for example, perforce) to manage p4d and (optionally) a UNIX group for it (for example, p4admin). Use the umask(1) command to ensure that the server root (P4ROOT) and all files and directories created beneath it are writable only by the UNIX user perforce, and (optionally) readable by members of the UNIX group p4admin.

Under this configuration, the Perforce service (p4d), running as UNIX user perforce, can write to files in the server root, but no users are able to read or overwrite its files. To grant access to the files created by p4d (that is, the depot files, checkpoints, journals, and so on) to trusted users, you can add the trusted users to the UNIX group p4admin.

Running from inetd on UNIX

Under a normal installation, the Perforce service runs on UNIX as a background process that waits for connections from users. To have p4d start up only when connections are made to it, using inetd and p4d -i, add the following line to /etc/inetd.conf:

p4dservice stream tcp nowait username /usr/local/bin/p4d p4d -i -r p4droot

and then add the following line to /etc/services:

p4dservice nnnn /tcp

where:

  • p4dservice is the service name you choose for this Perforce server
  • /usr/local/bin is the directory holding your p4d binary
  • p4droot is the root directory (P4DROOT) to use for this Perforce server (for example, /usr/local/p4d)
  • username is the UNIX user name to use for running this Perforce server
  • nnnn is the port number for this Perforce server to use

The "extra" p4d on the /etc/inetd.conf line must be present; inetd passes this to the OS as argv[0]. The first argument, then, is the -i flag, which causes p4d not to run as a background process, but rather to serve the single client connected to it on stdin/stdout. (This is the convention used for services started by inetd.)

This method is an alternative to running p4d from a startup script. It can also be useful for providing special services; for example, at Perforce, we have a number of test servers running on UNIX, each defined as an inetd service with its own port number.

There are caveats with this method:

  • inetd may disallow excessive connections, so a script that invokes several thousand p4 commands, each of which spawns an instance of p4d via inetd can cause inetd to temporarily disable the service. Depending on your system, you might need to configure inetd to ignore or raise this limit.
  • There is no easy way to disable the server, since the p4d executable is run each time; disabling the server requires modifying /etc/inetd.conf and restarting inetd.
  • To use Perforce with this license, you will need to request a server license that does not specify a port. Contact Perforce licensing for more information.

Note

For information about using systemd to launch services and daemons at boot time see http://answers.perforce.com/articles/KB/10832.

Starting the Perforce service

After you set p4d's P4PORT and P4ROOT environment variables, start the service by running p4d in the background with the command:

$ p4d &

Although the example shown is sufficient to run p4d, you can specify other flags that control such things as error logging, checkpointing, and journaling.

Example 1. Starting the Perforce service

You can override P4PORT by starting p4d with the -p flag (in this example, listen to port 1818 on IPv6 and IPv4 transports), and P4ROOT by starting p4d with the -r flag. Similarly, you can specify a journal file with the -J flag, and an error log file with the -L flag. A startup command that overrides the environment variables might look like this:

$ p4d -r /usr/local/p4root -J /var/log/journal -L /var/log/p4err -p tcp64:[::]:1818 &

The -r, -J, and -L flags (and others) are discussed in “Backup and Recovery”. To enable SSL support, see Using SSL to encrypt connections to a Helix server. A complete list of flags is provided in the Perforce Server (p4d) Reference.

For information about the files that have been installed, see Installed files.

Stopping the Perforce service

To shut down the Perforce service, use the command:

$ p4 admin stop

Only a Perforce superuser can use p4 admin stop.

Restarting a running Perforce service

To restart a running Perforce service (for example, to read a new license file), use the command:

$ p4 admin restart

Only a Perforce superuser can use p4 admin restart. On UNIX platforms, you can also use kill -HUP to restart the service.

Windows installation

To install Perforce on Windows, use the Perforce installer (perforce.exe) from the Downloads page of the Perforce web site:

http://www.perforce.com/downloads/complete_list

Use the Perforce installer program to install or upgrade the Perforce service, Perforce proxy, broker, or the Perforce Command-Line Client. Other Perforce applications on Windows, such as the Perforce Visual Client (P4V), as well as third-party plug-ins, may be downloaded and installed separately.

For an example of how to install Perforce on Windows, see:

http://answers.perforce.com/articles/KB_Article/Example-Windows-Installation

Note

If you have Administrator privileges, it is usually best to install Perforce as a service. If you don’t, install it as a server.

Windows services and servers

In this manual, the terms Perforce Service and p4d are used interchangeably to refer to "the process which provides versioning services to Perforce applications" unless the distinction between a Windows server process or a service process is relevant.

The Perforce versioning service (p4d) can be configured to run as a Windows service (p4s.exe) process that starts at boot time, or as a server (p4d.exe) process that you invoke manually from a command prompt. To run a task as a Windows server, the user must be logged in because shortcuts in a user’s startup folder cannot be run until that user logs in.

The Perforce service (p4s.exe) and the Perforce server (p4d.exe) executables are copies of each other; they are identical apart from their filenames. When run, the executables use the first three characters of the name with which they were invoked (either p4s or p4d) to determine their behavior. (For example, invoking copies of p4d.exe named p4smyservice.exe or p4dmyserver.exe invoke a service and a server, respectively.)

By default, the Perforce installer configures Perforce as a Windows service..

Note

On Windows, directory permissions are set securely by default; when Perforce runs as a Windows server, the server root is accessible only to the user who invoked p4d.exe from the command prompt. When Perforce is installed as a service, the files are owned by the LocalSystem account, and are accessible only to those with Administrator access.

To allow the Perforce service to run under a regular user account, make sure that the user has read/write access to the registry key and that the user has access to the directory structure under P4ROOT. For additional information see the following article:

http://kbportal.perforce.com/article/3925

Installing the Perforce service on a network drive

By default, the Perforce service runs under the local System account. Because the System account has no network access, a real userid and password are required in order to make the Perforce service work if the metadata and depot files are stored on a network drive. The Perforce service is then configured with the supplied data and run as the specified user instead of System.

If you are installing your server root on a network drive, the Perforce installer (perforce.exe) requests a valid combination of userid and password at the time of installation. This user must have administrator privileges.

Although the Perforce service runs reliably using a network drive as the server root, there is still a marked performance penalty due to increased network traffic and slower file access. Consequently, Perforce recommends that the depot files and Perforce database reside on a drive local to the machine on which the Perforce service is running.

Starting and stopping the Perforce service

If you install Perforce as a service under Windows, the service starts whenever the machine boots. Use the Services applet in the Control Panel to control the Perforce service’s behavior.

To stop a Perforce service, use the command:

$ p4 admin stop

Only a Perforce superuser can use p4 admin stop.

For older revisions of Perforce, shut down services manually by using the Services applet in the Control Panel.

For information about the files that have been installed, see Installed files.

Multiple Perforce services under Windows

By default, the Perforce installer for Windows installs a single Perforce server as a single service. If you want to host more than one Perforce installation on the same machine (for instance, one for production and one for testing), you can either manually start Perforce servers from the command line, or use the Perforce-supplied utility svcinst.exe, to configure additional Perforce services.

Warning

Setting up multiple services to increase the number of users you support without purchasing more user licenses is a violation of the terms of your Perforce End User License Agreement.

Understanding the precedence of environment variables in determining Perforce configuration is useful when configuring multiple Perforce services on the same machine. Before you begin, read and understand Windows configuration parameter precedence.

To set up a second Perforce service:

  1. Create a new directory for the Perforce service.
  2. Copy the server executable, service executable, and your license file into this directory.
  3. Create the new Perforce service using the svcinst.exe utility, as described in the example below. (The svcinst.exe utility comes with the Perforce installer, and can be found in your Perforce server root.)
  4. Set up the environment variables and start the new service.

We recommend that you install your first Perforce service using the Perforce installer. This first service is called Perforce and its server root directory contains files that are required by any other Perforce services you create on the machine.

Example 2. Adding a second Perforce service.

You want to create a second Perforce service with a root in C:\p4root2 and a service name of Perforce2. The svcinst executable is in the server root of the first Perforce installation you installed in C:\perforce.

Verify that your p4d.exe executable is at Release 99.1/10994 or greater:

C:\> p4d -V

(If you are running an older release, you must first download a more recent release from http://www.perforce.com and upgrade your server before continuing.)

Create a P4ROOT directory for the new service:

C:\> mkdir c:\p4root2

Copy the server executables, both p4d.exe (the server) and p4s.exe (the service), and your license file into the new directory:

C:\> copy c:\perforce\p4d.exe c:\p4root2
C:\> copy c:\perforce\p4d.exe c:\p4root2\p4s.exe
C:\> copy c:\perforce\license c:\p4root2\license

Use Perforce’s svcinst.exe (the service installer) to create the Perforce2 service:

C:\> svcinst create -n Perforce2 -e c:\p4root2\p4s.exe -a

After you create the Perforce2 service, set the service parameters for the Perforce2 service:

C:\> p4 set -S Perforce2 P4ROOT=c:\p4root2
C:\> p4 set -S Perforce2 P4PORT=1667
C:\> p4 set -S Perforce2 P4LOG=log2
C:\> p4 set -S Perforce2 P4JOURNAL=journal2

Finally, use the Perforce service installer to start the Perforce2 service:

$ svcinst start -n Perforce2.

The second service is now running, and both services will start automatically the next time you reboot.

Windows configuration parameter precedence

Under Windows, Perforce configuration parameters can be set in many different ways. When a Perforce application (such as p4 or P4V), or a Perforce server program (p4d) starts up, it reads its configuration parameters according to the following precedence:

  1. For Perforce applications or a Perforce server (p4d), command-line flags have the highest precedence.
  2. For a Perforce server (p4d), persistent configurables set with p4 configure.
  3. The P4CONFIG file, if P4CONFIG is set.
  4. User environment variables.
  5. System environment variables.
  6. The Windows user registry (or OS X user preferences) (set by p4 set).
  7. The Windows system registry (or OS X system preferences) (set by p4 set -s).

When a Perforce service (p4s) starts up, it reads its configuration parameters from the environment according to the following precedence:

  1. Persistent configurables set with p4 configure have the highest precedence.
  2. Windows service parameters (set by p4 set -S servicename).
  3. System environment variables.
  4. The Windows system registry (or OS X user preferences) (set by p4 set -s).

User environment variables can be set with any of the following:

  • The MS-DOS set command
  • The AUTOEXEC.BAT file
  • The User Variables tab under the System Properties dialog box in the Control Panel

System environment variables can be set with:

  • The System Variables tab under the System Properties dialog box in the Control Panel.

Starting and stopping the Perforce server

The server executable, p4d.exe, is normally found in your P4ROOT directory. To start the server, first make sure your current P4ROOT, P4PORT, P4LOG, and P4JOURNAL settings are correct; then run: %P4ROOT%\p4d

To start a server with settings different from those set by P4ROOT, P4PORT, P4LOG, or P4JOURNAL, use p4d command-line flags. For example:

C:\> C:\test\p4d -r c:\test -p 1999 -L c:\test\log -J c:\test\journal

starts a Perforce server process with a root directory of c:\test, listening to port 1999, logging errors to c:\test\log, and with a journal file of c:\test\journal. The p4d command-line flags are case-sensitive.

To stop the Perforce server, use the command:

C:\> p4 admin stop

For information about the files that have been installed, see Installed files.

Support for long file names

Support for long file names is enabled by default in Perforce server versions 2015.2 or newer. For older versions of the Perforce server, you can enable long filename support on the server with the filesys.windows.lfn configurable.

Note

The server root or client root cannot be a long path.

Set filesys.windows.lfn to 1 to support filenames longer than 260 characters on Windows platforms. A file name length of up to 32,767 characters is allowed. Each component of the path is limited to 255 characters.

To set on the server, use a command like the following:

C:\> p4 configure set filesys.windows.lfn=1

Depending on the depth of your workspace path, you might also need to set this configurable on the client and/or proxy (which acts as a client). To set the configurable for a proxy, use a command like the following:

C:\> p4 set -S "Perforce Proxy" P4DEBUG=filesys.windows.lfn=1

Installed files

Installation adds three types of files to the Perforce server host:

  • Database files
  • The Journal file
  • The Perforce binary

The database files and the Journal file are placed in the root directory of the Perforce server. Eventually, as users and administrators work with Perforce other files are added to the Perforce root directory (P4ROOT): user’s archived files, checkpoint file, and log files.

The Perforce binary is also installed as shown in the table below

Operating system Location

Linux download

Wherever the administrator puts it. Usually /usr/local/bin/p4d or /opt/perforce/bin/p4d

SDP for CentOS

/opt/perforce/bin/p4d

SDP for Ubuntu

/opt/perforce/bin/p4d

Windows download

Where the administrator puts it. By default it is downloaded to the following directory: C:\Program Files\Perforce\Server\p4d

Mac OS X

Where the administrator puts it. Usually /usr/bin/p4d or /user/local/bin/p4d

Upgrading the Perforce service

You must back up your Perforce installation (see Backup procedures) as part of any upgrade process.

Warning

Before you upgrade the Perforce service, always read the release notes associated with your upgraded installation.

In order to upgrade from 2013.2 (or earlier) to 2013.3 (or later), you must restore the database from a checkpoint. See Checkpoints for database tree rebalancing for an overview of the process and Upgrading p4d - between 2013.2 and 2013.3 for instructions specific to this upgrade.

In replicated and distributed environments (see Helix Versioning Engine Administrator Guide: Multi-site Deployment), all replicas must be at the same release level as the master. Any functionality that requires an upgrade for the master requires an upgrade for the replica, and vice versa.

Using old Perforce applications after an upgrade

Although older Perforce applications generally work with newer versions of Perforce, some features in new server releases require upgrades to Perforce applications. In general, users with older applications are able to use features available from the Perforce versioning service at the user application’s release level, but are not able to use the new features offered by subsequent upgrades to the service.

Licensing and upgrades

To upgrade Perforce to a newer version, your Perforce license file must be current. Expired licenses do not work with upgraded versions of Perforce.

Upgrading p4d

Follow the instructions in this section if both your old and new versions are 2013.3 or later, or if both old and new versions are 2013.2 or earlier.

Read the Release Notes for complete information on upgrade procedures.

Warning

In order to upgrade from 2013.2 (or earlier) to 2013.3 (or later), you must restore the database from a checkpoint. See Checkpoints for database tree rebalancing for an overview of the process, and Upgrading p4d - between 2013.2 and 2013.3 instructions specific to this upgrade.

In general, Perforce upgrades require that you:

  1. Stop the Perforce service (p4 admin stop).
  2. Make a checkpoint and back up your old installation. (see Backup procedures)
  3. Verify your files, see Verifying files during server upgrades for more information.
  4. Run the p4d -xv and p4d -xx commands to ensure that db.* files are OK before the upgrade.
  5. Replace the p4d executable with the upgraded version.

    On UNIX, replace the old version of p4d with the new version downloaded from the Perforce website. On Windows, use the Perforce installer (perforce.exe); the installer automatically replaces the executable.

  6. Some upgrades (installations with more than 1000 changelists, or upgrades with certain database changes) may require that you manually upgrade the database by running:

    p4d -r server_root -J journal_file -xu

    This command may take considerable time to complete. You must have sufficient disk space to complete the upgrade.

  7. Restart the Perforce service with your site’s usual parameters.

If you have any questions or difficulties during an upgrade, contact Perforce technical support.

Upgrading p4d - between 2013.2 and 2013.3

Follow the instructions in this section if your old version is 2013.2 or earlier and your new version is 2013.3 or later.

Perforce 2013.3 contains major changes to the Perforce database implementation. These changes allow for increased concurrency and scalability, and increase the size limit for the db.* database files to 16TB.

Although the db.* database file format has changed, the checkpoint and journal file formats are identical. In order to upgrade from 2013.2 (or earlier) to 2013.3 (or later), you must restore the database from a checkpoint. To do this:

  1. Stop the Perforce service (p4 admin stop).
  2. Make a checkpoint and back up your old installation. (see Backup procedures)
  3. If a file called tiny.db exists in your old server root, you must back it up separately by running the following command with the old p4d:

    p4d -xf 857 > tiny.ckp

  4. Remove the old db.* files, or preferably, move them to a safe location in the event that the upgrade fails.

    mv your_root_dir /db.* /tmp

    There must be no db.* files in the P4ROOT directory when you rebuild a database from a checkpoint. Although the old db.* files will not be used again, it’s good practice not to delete them until you’re certain your upgrade was successful.

  5. Remove the rdb.lbr file, if it exists.

    The rdb.lbr file keeps track of files that need to be transferred to the (local) replica, and may become out of date while the upgrade is underway. Note that this file only exists if your Perforce service was configured as a replica.

  6. Replace the old (2013.2 or earlier) p4d executable with the new (2013.3 or later) p4d executable.

    Do not run p4d -xu after replacing p4d at this time. In this upgrade scenario, you are not upgrading an existing database, you have removed it completely and will rebuild it from the checkpoint that you just took.

  7. Use the upgraded p4d to replay the checkpoint and rebuild the new database tables:

    p4d -r $P4ROOT -jr checkpoint_file

  8. If your site uses localized server messages from a message file obtained through Perforce technical support, retrieve the original message.txt file and re-create db.message in the new database format by running the following command with the new p4d:

    p4d -jr /fullpath/message.txt

    See Localizing server error messages for more information.

  9. If you created a tiny.ckp file as part of your backup process, restore tiny.db by running the following command with the new p4d:

    $ p4d -xf 857 tiny.ckp
  10. Run p4d -xu against the Perforce database to update the database schema:

    $ p4d -r $P4ROOT -J myJournal -xu
  11. Restart the Perforce service and resume operations.

Verifying files by signature

Perforce administrators can use the p4 verify filenames command to validate stored MD5 digests of each revision of the named files. The signatures created when users store files in the depot can later be used to confirm proper recovery in case of a crash: if the signatures of the recovered files match the previously saved signatures, the files were recovered accurately. If a new signature does not match the signature in the Perforce database for that file revision, Perforce displays the characters BAD! after the signature.

It is good practice to run p4 verify before performing your nightly system backups, and to proceed with the backup only if p4 verify reports no corruption.

For large installations, p4 verify can take some time to run. The server is also under heavy load while files are being verified, which can impact the performance of other Perforce commands. Administrators of large sites might want to perform p4 verify on a weekly basis, rather than a nightly basis.

If you ever see a BAD! signature during a p4 verify command, your database or versioned files might be corrupt, and you should contact Perforce Technical Support.

Verifying files during server upgrades

It is good practice to use p4 verify as follows before and after server upgrades:

  1. Before the upgrade, run:

    $ p4 verify -q //...

    to verify the integrity of your server before the upgrade.

  2. Take a checkpoint and copy the checkpoint and your versioned files to a safe place.
  3. Perform the server upgrade.
  4. After the upgrade, run:

    $ p4 verify -q //...

    to verify the integrity of your new system.

Release and license information

The Perforce versioning service is licensed according to how many standard users it supports. There are three types of Perforce users: standard users, operator users, and service users.

  • A standard user is a traditional user of Perforce.

    Standard users are the default, and each standard user consumes one Perforce license.

  • An operator user is intended for human or automated system administrators.

    An operator user does not require a Perforce license.

  • A service user is used for server-to-server authentication, whether in the context of remote depots (see Remote depots and distributed development) or in distributed environments.

    Service users do not require licenses, but are restricted to automated inter-server communication processes in replicated and multi-server environments.

Licensing information is contained in a file called license in the server root directory. The license file is a plain text file supplied by Perforce Software. Without the license file, the service limits itself to either 20 users and 20 client workspaces (and unlimited files), or to an unlimited number of users and workspaces (but with a limit of 1000 files).

You can update an existing license file without stopping Perforce by using the p4 license command. See Adding new licensed users for details.

  • If the service is running, any user can use p4 info to view basic licensing information. Administrators can use p4 license -u to obtain more detailed information about how many users and files are in use.
  • If the service is down, you can also obtain licensing information by running p4d -V from the server root directory where the license file resides, or by specifying the server root directory either on the command line (p4d -V -r server_root) or in the P4ROOT environment variable.

The server version is also displayed when you invoke p4d -V or p4 -V.