This article describes how to move a Helix server between machines with identical case-sensitivity, architecture and text file format.
Prior to moving a Helix server, consider these questions; if the answer to any of them is "No", a cross-platform migration must be performed:
If all three items are true, a Helix server can be safely moved using the method described below. If not, please consult Cross-Platform Helix Server Migration.
To move a Helix server between machines with identical case-sensitivity, architecture, and text file format do the following:
Update the license file.
If the IP address of the new machine is different from the old machine and the Helix Server license is current, obtain a new license file to reflect the new IP address. Fill out a Change of Server Request at:
Or contact firstname.lastname@example.org.
Install Perforce on the new machine.
Install the Helix server software on the new machine. Use the same release on the new machine as on the original machine; however, it is recommended to use the latest patch of that release. In other words, if the old server is running 2016.2, the new server should run the latest version of 2016.2. For more information on how to install the Helix Server, consult the Helix System Administrator's Guide.
Current versions of Helix Server can be obtained from:
Below this path are the major release directories, where r16.2 is an abbreviation for Helix Server 2016.2 release. In each of the release directories there are platform specific builds for Helix. For example, the 2016.2 version of the 64-bit Windows installer is located in:
For Windows installations, download and install helix-versioning-engine.exe (32-bit) or helix-versioning-engine-x64.exe (64-bit) to populate the registry and the Helix Server root directory (P4ROOT). The installer will create new database (db.*) files and start a Service. You will need to ensure you stop this service before being able to erase the database tables. Erase these new database files as they will be recreated in the the "Rebuild database files" step.
For *nix installations, download the appropriate version of P4D then run
chmod 755 p4d
This will make the p4d file executable.
If you would like to run a newer release of Helix Server, it is recommended to complete the move of Helix to the new server first using the steps in this article. Then in a separate step upgrade using the steps in the "Upgrading a Helix Server" article.
Verify the archive files.
To ensure there are no missing or corrupted archive files, run the following command on the original server:
p4 verify -q //... > verify.errors
Note: For Windows stderr format use instead the command:
p4 verify -q //... > verify.errors 2>&1
Examine the verify.errors file for errors. Ideally this file will be empty (no errors found). If any errors or listed, please contact Perforce Support at email@example.com for assistance, or see our Knowledge Base articles, "How to Handle p4 verify BAD Errors" and "MISSING! errors from p4 verify".
Compute missing checksums.
To provide signatures for any files that do not already have them, run the following command on the original server:
p4 verify -qu //... > verify.update
p4 verify -qu //... > verify.update 2>&1
This will allow all revisions of all files to be checked using "p4 verify" following the move.
Stop the server.
Run "p4 admin stop" to shut down the original Helix server. This will prevent access to the server while it is relocated.
p4 admin stop
Copy over the versioned files.
The versioned files are usually located in directories under the root directory but may reside elsewhere. Files and directories can be moved using rsync, tar, ftp, a network copy, or any other method that preserves the files as they were on the original server.
On Unix servers, run rsync (or the equivalent).
cd <Perforce original root>
rsync -avz ./depot perforce@gabriel:/home/perforce
Where "./depot" is one of the directories to be copied on the original server, "perforce@gabriel" would be replaced with the user and hostname of the new server, and "/home/perforce" is the Helix Server root directory on the new server.
Copy over all the versioned file directories.
Note: It is possible to copy most of the files before the server move, then update the versioned files later. To update the versioned files, run the same rsync command. The rsync flags used by this command will only transfer files updated since the command was last run.
On Windows servers, run xcopy (or the equivalent):
cd <Perforce original root>
xcopy *.* S:\perforce /s /d /c /e /i /h /y
Where "S:\perforce" is the network drive that contains the corresponding directory on the new server. Copy over all the versioned file directories.
Note: It is possible to copy most of the files earlier, then update the versioned files later using the /d or /d:mm-dd-yyyy flags and arguments. To find out more about the xcopy command, select the "Windows | Start | Help and Support" menu item.
If you do not know where the versioned files are located, run the command:
For each depot listed, run the command:
p4 depot -o depot
And look at the Map: field for the depot versioned files location.
Install the new license file.
Copy the new license file into the new Helix Server P4ROOT in place of the old license file.
Rebuild the database files.
Rebuild the database (db.*) files in Helix Server root directory of the new machine. The creation and restore of a checkpoint provides a rudimentary check of the database and it also rebalances the database for better performance as seen in Checkpoints for database tree rebalancing. Erase any existing db.* files. *.lbr files, any journal or log, any state file, and server.locks directory on the new machine before restoring a checkpoint. Be absolutely sure you are erasing new db.* files and not production db.* files.
To take a checkpoint, run the command:
cd <old server P4ROOT>
p4d -r P4ROOT -J D:\perforce\journal -jc
Where D:\perforce\journal is replaced with the directory path and name of the journal.
After the checkpoint operation completes successfully, copy the checkpoint file from the original server to the P4ROOT directory on the new server.
On UNIX, open a terminal window and restore the checkpoint using:
cd <new server P4ROOT>
rm -r server.locks
p4d -r P4ROOT -jr checkpoint
On Windows, open a command prompt and restore the checkpoint using
cd <new server P4ROOT>
rmdir /s server.locks
p4d -r . -jr checkpoint
Note: All database files are to be removed on the new server; the original db.* files are on the old server for safekeeping.
If your server is 2014.2, 2015.1, 2015.2, or 2016.1, you will also need to copy the ldap directory from the master to the replica if you use LDAP or Active Directory.
Start the new server privately
This step is optional, but recommended. To prevent unwanted connections while performing work on the new server, use "localhost" for the P4PORT setting when starting the server. This will deny remote connections while allowing access from the server host itself. Alternately, start the server on a non-standard port such as "1234".
For example, open a command prompt and run:
p4d -r <P4ROOT> -p localhost:1234/code>
p4d -r <P4ROOT> -p 1234
Where <P4ROOT> is the directory of the database (db.*) files. This will start the server listening for network connections, the command prompt will not return. For more information on how to configure and start a Helix Server, consult the Helix System Administrator's Guide.
In a separate command prompt window perform a "sanity check" of the server with the command:
p4 -p localhost:1234 changes -t -m 10
This command will verify that the last changes submitted to the original Helix Server are on the new machine. Make sure the dates, times, and changelist numbers look reasonable.
Re-verify the archive files
To ensure that all archive files were copied successfully, run p4 verify on the new server using the same command(s) as in step three above. If any errors are encountered, confirm that the archive files were successfully copied into the correct location and, if necessary, contact Support for assistance.
Restart the new server
Stop and restart the new server using the production host and port number to allow full access. To stop the server, run the "p4 admin stop" command as in step five. On Windows, start the server under Services. On Unix, start the server using startup scripts copied over from the old server. Consult the Helix System Administrator's Guide for more information on how to configure and start a Helix Server.
Stop the old server or change the port number on the old server so users will not accidentally connect to the wrong server.
For example, on the the old Windows server, stop the service and run
p4 set -S Perforce P4PORT=1234
In addition to the steps detailed above, check for any automated processes that might access the Helix Server. Check for the following to see if any need to be updated, migrated, and tested:
If you encounter any problems, simply restart your old server and make sure the users point to the original IP address or name.
Check for any changes in executable and script paths and dependencies such as the same version of Perl or derived APIs like P4Perl
Check daemons such as the review daemon or p4thumb.
Cron jobs or scheduled tasks
Check automated backup or checkpointing scripts.
Check Helix Server startup script(s) (Linux or Unix) or the launchd plist file (Mac OS X).
Anti-virus software and backup scripts
Remember to exclude the database (db.*) and versioned files directories.
Change Helix Proxy servers, Replica servers, P4Broker servers, P4DTG servers, and so on to point to the new server.
DNS IP adddresses and reverse DNS entries.
Note: If the name server name or alias name of the new machine is different, users will likely need to change their P4PORT settings to point to <new server>:<port>. Helix client software defaults to connecting to a server named "perforce" at port 1666. So, if the Helix Server is run on the default port of 1666 with a name service alias for the machine running the server also set to "perforce", users never need to set P4PORT. In that case, when changing the machine running the Helix Server, have the IT department update the company name server (DNS) and reverse DNS entries so that the name record "perforce" refers to the new machine rather than the old. This will make the move completely transparent to the Helix users.
Let users know you have migrated to the new server and let users know of any changes to the IP address, server name, and port number so they can change their P4V, Eclipse, Visual Studio, P4EXP, and other Perforce clients.