Perforce Public Knowledge Base - Moving Depot Files To A Different Location
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

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

  1. Use the server.depot.root configurable (introduced in 2014.1)

  2. Modify the depot Map: path

  3. Use symlinks to modify one or more depot paths


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 depot
... 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 P4ROOT, so in this case if P4ROOT of the server were /p4/1/root, the depot files for the eng depot would be located at:

​/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 you choose to use 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 so you know what to expect. 

  • 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.  

  • Your 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 your depot directories.

  2. To prevent users from accessing the depots while you are moving them, you can 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 * * -//...
    super user <username> * //...

    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.

  3. Get a list of all your 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 you to copy the bulk of the versioned files in advance, and then incrementally update at the time you change the Map.  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.root setting 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 you provide for this specific server. Once the server specification has been created, use its name with the p4 serverid command:
    p4 serverid server-name
    which 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. 


    We now 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, you'll have copied all depot directories from the old location under P4ROOT 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

At this point, it's recommended to use p4 verify:

p4 verify -q //... 

to ensure you don't start seeing MISSING errors right away which would suggest the depot files weren't copied to the right location or the server.depot.root configuration doesn't match where the depot files were copied. You can 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 doesn't immediately report MISSING files which would suggest a configuration issue with server.depot.root or the file copy operation. Once you're satisfied with the p4 verify results, reverse 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 your depot directory:
  1. Backup all your depot directories.
     
  2. To prevent users from accessing the depots while you are moving them, you can 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 * * -//...
    super user <username> * //...
    
    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.
     
  3. Get a list of all your existing depots:
    p4 -ztag depots
    
    
  4. For each depot reported, the map field gives you the current location of the depot directory. 
  1. Copy each depot directory from its existing location to its new location.
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 you to copy the bulk of the versioned files in advance, and then incrementally update at the time you change the Map.  See Moving a Helix Server for xcopy and rsync flags.
  1. Update the map field of each depot specification by running the command:
p4 depot <depot_name> 
And 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, you can change
Map:     depot1/...
to
Map: E:\Users\perforce\depot1\...
Note: If the Helix Server is being run under a WIndows OS, you will need to 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 (...).
  1. Run the command:
p4 verify -q //...
If you immediately see "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.
  1. Either remove the mapping protections added previously:
p4 protect

Or, switch P4PORT back to the original setting 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, you might have one particular depot or depot subdirectory with a terabyte of large files that needs to be stored on a different volume.

Some words of caution. Because symlinks for depot storage location are not tracked by the Helix Server and are subject to being moved, deleted, modified, or forgotten about by system administrators, Perforce does not recommend using them as a general solution.

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

Important:

If you are using 'tiny.db' to store some of the smaller (tiny) file revisions, you will need to take 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'. You will need to 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. 
Related Links

Feedback

 

Was this article helpful?


   

Feedback

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

Characters Remaining: 255