Upgrade overview

Previous Helix Core applications continue to work with newer versions of Helix Core server. However, to enable your users to benefit from the features introduced in subsequent versions of the server, you must upgrade the server.

Upgrading the server is a two-step process

Upgrading the server is a two-step process:

  1. Installing a more recent P4D version.

  2. Running the commands that update the Helix Core Server database to make it compatible with that P4D version.

The examples that follow apply to both Windows and Linux/macOS installations.

(Recommended) Verify files before and after a server upgrade

Both before and after you upgrade the server, we recommend that you use the p4 verify command:

Before After

  1. Verify the integrity of submitted file revisions by running

    p4 verify -q //...

  2. Verify the integrity of shelved files (if any) by running:

    p4 verify -qS //...

  3. Take a checkpoint. (See Checkpoint files)
  4. Copy the checkpoint and your versioned files to a safe place.
  5. Perform the two-step server upgrade process.

  1. Verify the integrity of submitted file revisions by running
    p4 verify -q //...

  2. Verify the integrity of shelved files (if any) by running
    p4 verify -qS //...

To learn more, see p4 shelve in the Helix Core Command-Line (P4) Reference.

Upgrade status

To check on the status of upgrade steps on a single server, use p4 upgrades

To check on the status of the specified upgrade step on a server and its upstream servers, use p4 upgrades -g

Check the log file

Additional information about the status of the upgrade process can be found in the Helix Core Server log file. For information about locating the log file, see P4LOG.

Windows upgrade

You can perform an upgrade manually or by using the installer. Most customers find it convenient to use the installer.

If you are upgrading manually and running the Windows service (p4s.exe), make sure that the binary is also updated by copying p4d.exe to p4s.exe.

Before you upgrade

  1. Make sure that your license file is current.

  2. Back up your Helix Core Server installation. See Backup procedure.

  3. Run p4 info and make a note of the value for Server root because this is the value of P4ROOT that the upgrade procedure requires.

  4. Read the release notes associated with your upgraded installation.

  5. If running the Helix Versioning Engine as a service (p4s.exe) and upgrading manually rather than using the Windows installer, make sure that binary is also updated by copying p4d.exe to p4s.exe.

  6. For upgrade steps, read the following:

    1. (Recommended) Verify files before and after a server upgrade.

    2. The instructions for the Helix Core Server version you are upgrading from and your environment (multi-server or single server).
      For example,

Linux upgrade

Host with multiple versions

It is possible for more than one Helix Core Server to run on the same Linux host.

Version management

If the server has been installed using a package, and you want to prevent unintended upgrades to a higher version, consider pinning or locking the version:

APT policy with Pin more /etc/apt/preferences.d/p4d
Package: helix-p4d
Pin: version 2019.2.*
Pin-Priority: 1000
Yum with versionlock

See https://www.cyberciti.biz/faq/centos-redhat-fedora-yum-lock-package-version-command/

The --exclude directive allows for wildcards, whereas the yum versionlock command will not allow patch upgrades.

Alternatively, you can install a specific base package in a way that allows the package manager to automatically install the latest patch. For example,

apt-get install helix-p4d-base-r19.2
sudo update-alternatives --config helix-p4d

If you want to allow for version differences between the p4d servers running on the same Linux host, you can use Helix Core Server Control (p4dctl) and set the version for each specific server. For example,

  • on server1, you might update the execute parameter in the p4dctl config to point to /opt/perforce/sbin/p4d.23.1
  • on server2, you might update the execute parameter in the p4dctl config to point to /opt/perforce/sbin/p4d.22.2

If the server is managed by p4dctl

If the server is managed by Helix Core Server Control (p4dctl), ensure that the database upgrade command is run with the correct user and environment. Where sections of this guide mention upgrading the database by using the p4d -r P4ROOT -J P4JOURNAL -xu command, use this command instead:

p4dctl exec -t p4d service-name -- -xu

This applies whether the server was created by configure-helix-p4d.sh or the server was manually configured to use p4dctl.

For more information, see exec in p4dctl commands.

Before you upgrade

Important

14 August 2023 is the expiration date of the Perforce packaging key, but this key has been renewed until 11 June 2026 UTC. Package managers do not allow installation with an expired key. To ensure you have the renewed key, follow the instructions at Perforce Packages.

  1. Make sure that your license file is current.

  2. Back up your Helix Core Server installation. See Backup procedure.

  3. Run p4 info and make a note of the value for Server root because this is the value of P4ROOT that the upgrade procedure requires.

  4. If you have an installation of Helix Core Git Connector, upgrade your Git Connector installation before upgrading your Helix Core servers. See Upgrading Git Connector.

  5. Read the release notes associated with your upgraded installation.

  6. If you are upgrading from a version of Helix Core Server prior to 2019.1 and have a large number of ktext files (+k and +ko text files with RCS keyword expansion), contact Perforce Support for guidance on making the upgrade process faster.

  7. For upgrade steps, read

    1. (Recommended) Verify files before and after a server upgrade.

    2. The instructions for the Helix Core Server version you are upgrading from and your environment (multi-server or single server).

      For example,