Perforce Public Knowledge Base - Moving Depot Files To A Different Location
× PRODUCTS SOLUTIONS CUSTOMERS LEARN SUPPORT
Downloads Company Partners Careers Contact Free Trials
Menu Search
Perforce
Reset Search
 

 

Article

Moving Depot Files To A Different Location

« Go Back

Information

 
Problem

How do I move my Helix Server versioned depot files (under P4ROOT) to a different directory?

Solution

Warning: Moving a depot folder incorrectly and without understanding all of the implications can break replication, backup processes, and potentially cause data loss. If there are any questions or concerns about this process, please contact Perforce support for assistance.

There are three major approaches to moving the versioned depot files under P4ROOT:

Method 1: Use the server.depot.root configurable

The server.depot.root configurable is used to specify the location of the base directory for depot file storage for depots with relative Map: fields. An example of a depot with a relative Map: field:

p4 -ztag depot -o eng
... Depot eng
... Date 2011/05/16 15:03:40
... Description Default depot
... Type local
... Map eng/...

Depot Map: fields can also be specified as an absolute path:

p4 -ztag depot -o system
... Depot system
... Owner sysop
... Date 2017/04/13 14:34:30
... Description Created by sysop.
... Type local
... Map /p4/depot_data/system/...

By default, the base directory for depot file storage for depots with relative Map: fields is the Perforce server root directory (P4ROOT). For example, if the P4ROOT is /p4/1/root, the depot files for the eng depot are located:

/p4/1/root/eng/...

Important notes to consider when using the server.depot.root configurable:

  • The server.depot.root configurable setting takes affect immediately; new files submitted after the configurable is set will be written to the new server.depot.root location so it's important to follow the specific steps below if using server.depot.root.

  • The server.depot.root configurable only applies to relative depot Map: fields. Absolute paths in the depot Map: field are unaffected by the server.depot.root setting. Check all depot Map: field settings by running p4 -ztag depots before reconfiguring.

  • In distributed Perforce environments where Perforce replica and edge servers are present, care must be taken to set server.depot.root so it only applies to the intended servers in the distributed environment.

  • Any backup process must take the server.depot.root location into account and not assume depot files exist in the default P4ROOT location.

To change the depot file directories using the server.depot.root configurable, follow these steps:

  1. Backup all depot directories.

  2. Prevent users from accessing the depots while moving them.
    Set protections to prevent write access by entering the command:

    p4 protect

    Add the following mappings at the end of the Protections field:

    list user * * -//...
    list group * * -//...
    super user <username> * //...

    where <username> is the Perforce username of the super user.

    An alternative is to set the server to localhost mode by setting P4PORT to localhost:port_number, and then restart the Helix Server. This will prevent any connections from hosts other than the Helix Server, effectively locking everyone out of the machine.

    Note: The localhost mode requires either direct access to the Helix Server hardware, or access using a remote desktop or SSH.

    Another alternative is to start Perforce on an "unadvertised" port, say, 1669 instead of 1666.  On Windows, run

    p4 set -S Perforce P4PORT=1669

    and restart the Perforce service.  Then connect Perforce to <Perforce server>:1669 instead of 1666.

  3. Get a list of all existing depots:

    p4 -ztag depots
    
  4. For each depot reported with a relative Map: path, copy the depot directory from its existing location under P4ROOT to its new location under the chosen server.depot.root.

    This is typically the longest operation and as such could increase down-time. Using a synchronizing utility like rsync -avz (under most Unix based systems) or xcopy or Robocopy (for Windows) can reduce the impact of this step. They allow copying the bulk of the versioned files in advance, and then incrementally update at the time the Map is changed. See Moving a Helix Server for xcopy and rsync flags.

  5. Set the server.depot.root configurable

    Best practice is to isolate the server.depot.root setting to a specific server. To do that, the server must have a configured serverName. Run p4 -ztag info to check for an existing serverName. In the case where a serverName already exists:

    p4 -ztag info
    ... serverName commit

    Use it in the p4 configure set command to isolate the server.depot.rootsetting to the named server:

    ​p4 configure set commit#server.depot.root=/p4/depot_data

    If a serverName is not currently configured, create a server specification by running:

    p4 server server-name

    Adding a Description to describe the server, and accepting all other default values.

    Note: Server-name here is a random name provided this specific server. Once the server specification has been created, use its name with the p4 serverid command:

    p4 serverid server-name

    This sets both the ServerID and serverName for the server:

    p4 -ztag info
    ... serverName server-name
    ... ServerID server-name
    

    Note: The p4 serverid command creates a small text file named server.id in the server's P4ROOT directory. The server.id file must be backed up as part of normal backup procedures and restored for any restoration that occurs so the Helix Server can read the server.id file on startup and configure properly. Another option would be to run p4d -xD server-name from the P4ROOT directory as part of the restore procedure before starting the server which will write the server.id file to P4ROOT.

    Use the configured serverName to set server.depot.root:

    p4 configure set server-name#server.depot.root=/p4/depot_data

At the end of the process, All depot directories from the old location under P4ROOT will now be copied to the new location as configured by server.depot.root.

For example, a server with P4ROOT at /p4/1/root with two depots, eng and qa, defined with relative Map: paths, old depot directories under P4ROOT:

/p4/1/root/eng
/p4/1/root/qa

Will have been copied to newly configured server.depot.root location:

/p4/depot_data/eng
/p4/depot_data/qa

And server.depot.root set to /p4/depot_data.

  1. At this point, it is recommended to use p4 verify:
p4 verify -q //... 

This checks for any MISSING errors which suggest the depot files were not copied to the right location or the server.depot.root configuration does not match where the depot files were copied. Let the p4 verify run to completion to ensure the server can locate depot files for all revisions but that will take time to complete as the verify computes checksums for all files stored in the Helix Server. The other option is just to let p4 verify run for a short time (it;'s safe to ctrl-C the p4 verify to stop it) and ensure it does not immediately report MISSING files which would suggest a configuration issue with server.depot.root or the file copy operation. Once the p4 verify results are clear of errors, un-apply step 2 above to open up the server to users again.

Method 2: Modify the depot Map: path

The filesystem path where a depot's versioned files are stored is specified by the Map field in that depot's specification.

$ p4 -ztag depot -o depot
... Depot depot
... Date 2011/05/16 15:03:40
... Description Default depot
... Type local
... Map depot/...

By default, the depot directory location is given as a path relative to the P4ROOT directory and is named the same as the depot itself, however, this location can be changed and mapped to either a different path relative to P4ROOT, or to an absolute path outside of P4ROOT.

To change a depot directory:

Note: This is typically the longest operation, which could significantly increase down-time. Using a synchronizing utility like rsync -avz (under most Unix based systems) or xcopy or Robocopy (for Windows) can reduce the impact of this step. They allow the bulk of the versioned files to be copied in advance, and then incrementally update at the time the change is made to the depot mapping.

See Moving a Helix Server for xcopy and rsync flags.

  1. Backup all depot directories.

  2. Prevent users from accessing the depots while moving them.
    Set protections to prevent write access by entering the command:

    p4 protect

    Add the following mappings at the end of the Protections field:

    list user * * -//...
    list group * * -//...
    super user <username> * //...
    

    where <username> is the Perforce username of the super user.

    An alternative is to set the server to localhost mode by setting P4PORT to localhost:port_number, and then restart the Helix Server. This will prevent any connections from hosts other than the Perforce server, effectively locking everyone out of the machine.

    Note: The localhost mode requires either direct access to the Helix Server hardware, or access using a remote desktop or SSH.

    Another alternative is to start Perforce on an "unadvertised" port, say, 1669 instead of 1666.  On Windows, run

    p4 set -S Perforce P4PORT=1669

    and restart the Perforce service.  Then connect Perforce to <Perforce server>:1669 instead of 1666.

  3. List all existing depots:

    p4 -ztag depots
  4. For each depot reported, the map field gives the current location of the depot directory.

  5. Copy each depot directory from its existing location to its new location.

  6. Update the map field of each depot specification by running the command:

    p4 depot <depot_name>

    Replace the value of the Map field <depot_name>/... by <path>/<depot_name>/... (where <path> is the full path of the new location where the <depot_name> directory is located). For example:

    Map: depot1/...

    To:

    Map: E:\Users\perforce\depot1\...

    Note: If the Helix Server is being run under a WIndows OS, include the drive letter as a part of the path. The path should always end in with a forward or backslash (/) and the Perforce ellipses wildcard (...).

  7. Run the command

    p4 verify -q //depot1/...

    where depot1 is replaced by the depot moved.

    If there are "MISSING" errors, there is likely a problem with the path. This is most commonly a typo in the Map field, or a typo in the path itself.

    Note: The verify command can be safely cancelled with control-C.

  8. Either remove the mapping protections added previously:

    p4 protect

    Or,  switch P4PORT back to the original setting if changed and restart Perforce

Method 3: Use Symlinks

It is possible to use symlinks to move the storage location of one or more depot paths. Whereas the first two suggestions above rely on native Helix Server functionality, use of symlinks introduces Operating System specific functionality that is independent of Perforce -- and must be accounted for outside of Perforce.

Symlinks can be used to move the entire depot location, or just a subdirectory. For example, there might be one particular depot or depot subdirectory with a terabyte of large files that needs to be stored on a different volume.

Symlinks are supported on Unix, MacOS and recent versions of Windows. The behavior of symlinks in the environment should be transparent to the Helix Server, compatible with any backup tools, and documented by a Helix system administrator. Failure to account for any of these items could lead to loss of server data.

Important:

If 'tiny.db' is being used to store some of the smaller (tiny) file revisions, there are further steps to ensure the 'move' is completed successfully. The tiny.db. file itself is stored in the P4ROOT folder, but the full path to the the file revision is stored inside 'tiny.db', using the directory structure present prior to changes to the depot spec's 'map' field or 'server.depot.root'. Take a checkpoint of 'tiny.db', correct the content, and restore using this manually-updated tiny.db checkpoint.

Please contact support for assistance with this process if there are any questions.

Related Links

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255