Cross-Platform Perforce Server Migration

How do you migrate a Perforce server installation from one platform to another?

Problem

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

Solution

This article describes how to migrate your Perforce Server between platforms with different case-sensitivity, architecture and/or text file formats. For information on how to move your Perforce Server between machines with identical case-sensitivities, architectures and text file formats, please consult How do you move a Perforce Server installation from one machine to another?

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

1. Update your license
   If the IP address of the new machine is different from the old machine and you are a licensed Perforce customer, you must get a new license file to reflect the new IP address. Contact us for an updated license.
2. Install Perforce
   If you have not already done so, install the Perforce Server software on the new machine. You should use the same release on the new machine as on the original machine; however, you can update to the latest patch of that release. For more information on how to install Perforce, consult our System Administrator's Guide.
3. Verify the archive files
   To ensure that you don't have any missing or corrupted archive files to begin with, run the following command on the original server (if you have multiple depots you need to verify each depot):

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

   If you encounter any errors, please contact us for assistance.
4. Compute missing checksums
   To provide signatures for any files that do not already have them, run the following command on the original server (if you have multiple depots you need to verify each depot):

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

   This will allow all revisions of all files to be checked following the migration.
5. Stop the server
   Run "p4 admin stop" to shut down the original Perforce Server. This will prevent access to the server while you relocate it.
6. Verify the database
   Run the following command on the original server to ensure that there is no corruption in your database:

   p4d -r P4ROOT -xv

   This will 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 us for assistance. Please note: this command is undocumented, as it is very rarely needed. All undocumented commands may be changed or discontinued without notice.
7. Take a checkpoint
   Run the following command on the original server to take a checkpoint:

   p4d -r P4ROOT -jc

   It is important to specify the correct path to the Perforce Server's root directory (P4ROOT). For more information on how to take a checkpoint, consult our System Administrator's Guide.
8. Backup the checkpoint and depot subdirectories
   The following steps modify the metadata and archive files; therefore, it is critical that you backup the original server's checkpoint and all of its depot subdirectories before proceeding.
9. Copy the server root directory
   If you're moving from a case-sensitive server to a case-insensitive server, skip this step. You will perform it later (in step 12). Copy your license file, case-consistent checkpoint and all depot subdirectories from the original server to the new server. Do not copy the db.* files. You can use tar and cp or any other method you are comfortable with.
10. Resolve case-related problems
    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 causes huge problems on a case-sensitive one. Conversely, filenames that differ only by case are allowed on case-sensitive platforms, but collide and cause corruption 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: ftp.perforce.com/perforce/tools/p4-migrate/ (select the folder that corresponds with the platform that your dataset currently resides on). You will also need to download the p4migrate documentation.
11. Convert line-endings
    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". If you are moving between two platforms with the same text file format (such as Solaris to Linux), you can skip this step. You can convert line-endings with a short perl script. Run the following command from the target Perforce Server's root directory (P4ROOT):

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

    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. 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" -o -name ".*,v" \) -print \
     -exec perl -p -i -e 's/\n/\r\n/' \{} \;

12. Copy the server root directory
    If you are you moving from a case-insensitive server to a case-sensitive server, ignore this step. You copied your server root directory in step 9. Copy your license file, case-consistent checkpoint and all depot subdirectories from the original server to the new server. Do not copy the db.* files. You can use tar and cp or any other method you are comfortable with.
13. Restore from checkpoint
    Run the following command on the target server to receate the 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 our System Administrator's Guide.
14. Start 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 will deny remote connections), or start the server on a non-standard port. For example:

    p4d -r P4ROOT -p localhost:1666
     or:
    p4d -r P4ROOT -p 6666

    For more information on how to configure and start Perforce, consult our System Administrator's Guide.
15. 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 you encounter any errors, confirm that the archive files were successfully copied into the correct location and, if necessary, contact us for assistance.
16. 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 our System Administrator's Guide for more information on how to configure and start Perforce.
    

In addition to the steps detailed above, be advised that you will need to account for your automated processes. For example, you might need to update or migrate: custom triggers, daemons (such as the review daemon or p4thumb) and cronjobs or scheduled tasks (such as your backup routine).

If the hostname of the new machine is different, users must change their P4PORT settings. If you run your Perforce 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 Perforce 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.