Perforce Public Knowledge Base - Cross-Platform Perforce Server Migration
Reset Search
 

 

Article

Cross-Platform Perforce Server Migration

« Go Back

Information

 
Problem

How do I migrate a Perforce Helix Server between platforms with different case-sensitivity, architecture and/or text file formats?

Solution

Note: This article covers the migration of a Helix Server, that is, moving the same release of the Helix Server to a new machine. 
If you would like to upgrade your Server, you should perform your migration first, then in a separate step, continue on to Upgrading a Perforce Server.

This article describes how to migrate your Helix Server between platforms with different case-sensitivity, architecture, or text file formats. It can also be used to migrate a Perforce server by restoring a checkpoint. 

For information on how to move your Helix Server between platforms with the same case-sensitivity, architectures and text file formats, please consult Moving a Perforce Server.

For information on how to migrate your Helix Server between platforms with different case-sensitivity and retain non-native case handling (for example, case insensitive Linux), please consult Moving from Windows to Linux, Retaining Case-Insensitive Behavior.

Warning: Unix-to-Windows (or case-sensitive to case-insensitive) migrations are NOT SUPPORTED due to the potential for data loss.

1. Update your license on new machine

If the IP address of the new machine is different from the old machine, and you are a Perforce customer with a currently unexpired license, you must obtain a new license file from Perforce to reflect the new IP address. Fill out a Change of Server form to request an updated license.

2. Choose server binary for the new machine

If you don't already know your current release number, you can use the command p4 info to find out which release you are currently running. If your server release is within the Standard Maintenance Support period:

https://www.perforce.com/maintenance-support

You can download the same release of the server for your new machine from our ftp site: 

ftp://ftp.perforce.com/perforce/

However, if you are currently running say 2013.1 on your old machine and wish to use the same old version, you can contact our Sales team in extending Maintenance Support and contact our Support team in obtaining the same release of the server for your new machine.

Alternatively, you may consider migrating and upgrading to the latest supported version at the same time. This may means extra caution and testing in ensuring both the migration and upgrade are completed successfully.
 

3. Install P4D on new machine

If you have not already done so, install P4D on the new machine. Again, do not install a P4D release that is newer than the release you are currently running on your old machine.

On Linux

As the Unix perforce user, place p4d into the new directory and make p4d executable:

$ chmod 755 p4d

Go to the new P4ROOT directory and erase any database files (that is, any files named db.*).

On Windows

Install perforce.exe or perforce64.exe as downloaded and follow installation screens to install a new blank Perforce database and populate the registry.
Stop the Perforce service. Go to the P4ROOT directory and erase any database files (that is, any files named db.*).

Important: make sure you erase these newly created empty database (db.*) files and not your production db.* files!

For more information on how to install and update the Helix Server, consult the installation section of the System Administrator's Guide.

4. Verify the archive files on old machine

Use the p4 verify command to confirm that you do not have any missing or corrupted archive files on your old machine. Run the following command on the old machine:

$ p4 verify -q //... > verify.errors

Note: for Windows stderr format use instead the command:

p4 verify -q //... > verify.errors 2>&1

It is recommended that you fix any MISSING! errors or BAD! errors, or please contact Perforce Technical Support for assistance.

5. Compute missing checksums on old machine

Use p4 verify to provide signatures for any files that do not already have them. Run the following command on the old machine:

$ p4 verify -qu //... > verify.update

Note: for Windows stderr format use instead the command:

p4 verify -qu //... > verify.update 2>&1

This allows all revisions of all files to be checked following the migration.

6. Stop the server on old machine

Run p4 admin stop to shut down the Helix Server running on the old machine. This prevents access to the server while you relocate it.

7. Validate the database on old machine

Use the p4d command on the old machine ensure that there is no corruption in your database. P4ROOT is the directory that contains your your database files such as db.rev and db.protect. Run this command on the old machine:

$ p4d -r P4ROOT -xv

The -xv flag causes p4d to check the structure of each table in the database. It is important to identify and repair any corruption before proceeding. If you encounter any errors, please contact Perforce Technical Support for assistance.

Note: p4d -xv is listed under options in the p4d command's 'help' message, which you can access via this command:

$ p4d -h

8. Take a checkpoint on old machine

Use the p4d command on the old machine to take a checkpoint:

$ p4d -r P4ROOT -jc

Note: It is important to specify the correct path to the Helix Server's root directory (P4ROOT). To find out the P4ROOT directory on the old machine, first run the p4 info command:

$ p4 info

In the output of p4 info, look for the line that reads Server root: followed by a directory path. This directory is your P4ROOT.

For more information on how to take a checkpoint, consult the System Administrator's Guide section on Backup Procedures.

9. Make a backup of the checkpoint and depot subdirectories on old machine

The following steps modify the metadata and archive files; therefore, it is very important that you make a backup of the old machine's checkpoint and all of its depot subdirectories before proceeding. Hereafter, if any problems occur during the migration, you can simply abort the migration and restart the server on the old machine.

10. Copy the essential server root directory files from old machine to new machine

Note: If you are moving from a case-sensitive server to a case-insensitive server, skip this step. You will perform it later (in step 13).

Note: You can use rsync, tar, cp, copying to network drive, or any other method you are comfortable with to copy these important files and directories from the old machine to the new machine.

Copy the following from the old machine's P4ROOT location to the new machine's P4ROOT location:

  • Your new license file
  • Your checkpoint
  • Any trigger scripts and dependencies
  • Any startup scripts
  • All versioned files

It is critical that you copy all depot directories and subdirectories containing *,v files and *,d directories as these contain all versions of your source files.

Depot directories may not always reside under P4ROOT, so it's important to find all your depots wherever they may be. Use the p4 depots with the command with the -Ztag option to list your existing depots in an easy-to-read format:

$ p4 -Ztag depots

In the output of this command, look for any map line that that shows a path that is not in the format

depot/...

This will indicate the location of versioned files that are not in your P4ROOT location.

Do not copy:

  • database files (db.*) (these will be recreated from a restored checkpoint)
  • lbr files (*.lbr)
  • server.locks (a directory)
  • journal (the running journal)
  • log files

This will make sure you start with a fresh journal and fresh logs.

11. Resolve case-related problems

Note: If you are moving between two platforms with the same case-sensitivity (such as Solaris to Linux), you can skip this step; otherwise, you must resolve case-related problems before proceeding.

Inconsistent use of case is fine on a case-insensitive platform; it results in serious issues on a case-sensitive one. Conversely, filenames that differ only by case are allowed on case-sensitive platforms, but collide and cause corruption and data loss in case-insensitive environments. A Perforce tool called p4migrate can help you to find and resolve any case-related problems in your repository. You can download p4migrate from our ftp site (select the folder that corresponds with the platform of your new machine):

You will also need to download the p4migrate documentation.

Note: When moving from the Mac OS to Windows or Linux, you may need to perform an archive re-name, which is not implemented in p4migrate on the Mac. Use p4migrate on the new machine to complete archive renaming.

12. Convert line-endings of versioned files

Note: If you are moving between two platforms with the same text file format (such as Solaris to Linux, or Windows 32-bit to Windows 64-bit), you can skip this step.

If you are migrating between platforms with different text file formats (such as Windows to UNIX), you must convert line-endings on all depot files ending in ,v. You can convert line-endings with a short perl script. Run the following command from the target Helix Server's root directory (P4ROOT):

$ find . -type f -name '*,v' -print -exec perl -p -i -e 's/\r\n/\n/g' {} \;

The command syntax might be different depending on the specific platform and shell that you are using, but the above command should work in the majority of cases.

WARNING: Unix-to-Windows (or case-sensitive to case-insensitive) migrations are NOT SUPPORTED due to the potential for data loss.

If you are moving from UNIX to Windows, you should perform the conversion on UNIX before you copy the server root directory. You must also reverse the substitution like so:

$ find . -type f -name '*,v' -print -exec perl -p -i -e 's/\n/\r\n/g' {} \;

You should also note that some versions of find ignore files beginning with a dot (.bashrc, .htaccess, and so on). In this case, you may need to update the find command as follows to find files beginning with a dot:

$ find . -type f -name '*,v' -or -name '.*,v' -print -exec perl -p -i -e 's/\n/\r\n/g' {} \;

13. Copy the essential server root directory files from old machine to new machine

Note: If you are moving from a case-insensitive server to a case-sensitive server, ignore this step. You copied your server root directory in step 10.

Note: You can use tar, cp, copying to network drive, or any other method you are comfortable with to copy these important files and directories from the old machine to the new machine.

Copy the following from the original server P4ROOT to the new server P4ROOT location:

  • Your new license file
  • Your checkpoint
  • Any trigger scripts and dependencies
  • Any startup scripts
  • All versioned files

It is critical that you copy all depot directories and subdirectories containing *,v files and *,d directories as these contain all versions of your source files.

Depot directories may not always reside under P4ROOT, so it's important to find all your depots wherever they may be. Use the p4 depots with the command with the -Ztag option to list your existing depots in an easy-to-read format:

$ p4 -Ztag depots

In the output of this command, look for any map line that that shows a path that is not in the format

depot/...

This will indicate the location of versioned files that are not in your P4ROOT location.

Do not copy:

  • database files (db.*) (these will be recreated from a restored checkpoint)
  • lbr files (*.lbr)
  • server.locks (a directory)
  • journal (the running journal)
  • log files

This will make sure you start with a fresh journal and fresh logs.

14. Restore from checkpoint on the new machine

Run the following p4d command on the target server to recreate the database (db.*) files from the original server's checkpoint (free of case-inconsistencies and conflicts):

$ p4d -r P4ROOT -jr checkpoint.n

For more information on how to restore from a checkpoint, consult the System Administrator's Guide section on recovery procedures.

15.Test the new server privately

This step is optional, but recommended. To prevent unwanted connections while you are working on the new server, prepend localhost to the P4PORT setting when you start the server (this denies remote connections), or start the server on an unadvertised non-standard port.

For example, localhost will not allow connections from other machines.

$ p4d -r P4ROOT -p localhost:1666 -L log -J journal

Or, choose port 6666 so users expecting 1666 will not connect:

$ p4d -r P4ROOT -p 6666

For more information on how to configure and start the server, consult the System Administrator's Guide.

With the Server started privately, run sanity checks. For example, use the p4 changes command to check whether changelist numbers and times are reasonable.

$ p4 -p 6666 changes -t -m5

16. Re-verify the archive files on the new machine

To ensure that all archive files were copied successfully to the new machine, run p4 verify on the new server using the proper port number:

$ p4 -p 6666 verify -q //... > verify.errors

Note: for Windows stderr format use instead the command:

p4 -p 6666 verify -q //... > verify.errors 2>&1

If you encounter any errors, confirm that the archive files were successfully copied into the correct location and, if necessary, please contact Perforce Technical Support for assistance.

17. Restart the new server

You can now stop and restart the new server for everyone on your network to access. To stop the server, run the p4 admin stop command as in step five. Consult the System Administrator's Guide for more information on how to configure and start the Helix Server.

Note: If the hostname of the new machine is different from that of the old machine , users must change their P4PORT settings to point to the new hostname. You may want to consider changing your DNS server to point to the new machine. If you run your Helix Server on the default port of 1666 and set up a hostname of "perforce" as an alias for the machine running the server, users never need to set P4PORT. In that case, when you change the machine running the Helix Server, you can update your name server so "perforce" refers to the new machine rather than the old. This will make the move completely transparent to your users.

Related Links

Feedback

 

Was this article helpful?


   

Feedback

Please tell us how we can make this article more useful.

Characters Remaining: 255