Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 Server Administration Documentation | 2025.2

# Set a depot location

You can set the location of a depot both when you first create it, and later on, if you want to move it to a different location.

If you want all the depot data to be moved to a single new file system, see Single new file system.

If you want the depot data to be spread over multiple file systems or multiple directory paths, see Multiple file systems or directory paths.

If you want to use cloud storage, consider S3 storage.

In any case, Consider symlinks.

To reduce downtime for your users, consider a synchronizing utility like Rsync for Unix-based systems or robocopy for Windows to copy the versioned files in advance. This means that when you perform depot mapping, you only need to do an incremental update.

## Single new file system

This section assumes that you want all the depot data to be located on a single new file system.

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

Copy

    1
    2
    3
    4
    5
    6
    p4 -ztag depot -o eng
    ... Depot eng
    ... Date 2022/11/16 15:03:40
    ... Description Default depot
    ... Type local
    ... Map eng/...

Depot `Map` fields can also be specified as an absolute path (see line 7):

Copy

    1
    2
    3
    4
    5
    6
    7
    p4 -ztag depot -o system
    ... Depot system
    ... Owner sysop
    ... Date 2023/04/13 14:34:30
    ... Description Created by sysop.
    ... Type local
    ... Map /p4/depot_data/system/...

### The server.depot.root configurable

The `server.depot.root` configurable is an alternative to the default of depot directory paths being relative to the `P4ROOT` directory. You can set this configurable to assign an absolute path, with respect to which a relative address given in the `Map` field of a depot form is evaluated. Setting the configurable takes effect immediately.

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 multi-server environment with replica and edge servers, set `server.depot.root` so it only applies to those servers you want it to.

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

### Changing the depot file directories

To change the depot file directories by using the `server.depot.root` configurable:

1. Make a backup all depot directories.

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

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

       list user * * -//...
       list group * * -//...
       super user usernameOfSuperUser * //...

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` directory.

5. Set the `server.depot.root` configurable. Isolate the `server.depot.root` setting to a specific server. To do that, the server must have a configured `serverName`. See p4 serverid in the P4 CLI Reference.

6. Run the `p4 verify -q //...` command.

## Multiple file systems or directory paths

If you want the depot data to be spread over multiple file systems or multiple directory paths, be aware that this involved more work because:

- Each depot must have the `Map` field changed.

- File system management is more complex and there is risk of one or more file systems not being mounted.

- Replica, edge and standby servers must have the directory structures denoted in the depot's `Map` field.

Run the command:

    p4 -ztag depot -o depot

and the output shows the filesystem path where a depot's versioned files are stored. See the `Map` field in that depot's specification (line 5).

Copy

    1
    2
    3
    4
    5
    ... 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. However, this location can be changed and mapped to either a different path relative to `P4ROOT`, or to an absolute path outside of `P4ROOT`.

### Changing a depot directory

1. Make a backup all depot directories.

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

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

   `list user * * -//...
   list group * * -//...
   super user usernameOfSuperUser * //...`

3. Get a list of 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 `p4 depot depotName` command.

   Replace the value of the `Map` field `depotName/...` by `path/depotName/...` (where `path` is the full path of the new location where the `depotName` directory is located. For example:

   `Map: depot1/...`

   to:

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

   If P4 Server is being run under WIndows, include the drive letter as a part of the path and make sure that the path ends in with a forward or backslash (`/`) and the Perforce ellipses wildcard (`...`) of three dots.

7. Run the command `p4 verify -q //depot1/...` where `depot1` is replaced by the depot moved.

8. Use p4 protect to remove the mapping protections you added in Step (2).

9. Restart P4 Server.

## S3 storage

Your organization might find it economical to store the content of depots by using:

- Amazon S3, the Simple Storage Service of Amazon Web Services.

- An S3-compatible API, such as that of MinIO.

- A cloud provider's storage offering, such as DigitalOcean's Space Object Storage, Tencent Cloud Object Storage, Google Cloud Storage, or S3Proxy for Microsoft Azure Blob Storage.

This feature is supported for depots of all types except remote depots. The central server The one server that is innermost in a multi-server deployment. In the server specification form field for Services, the central server might be specified as “standard” or “commit-server”. If edge servers are part of the multi-server deployment, the central server must be a commit server. See also 'upstream server'., each replica A P4 Server that automatically maintains a full or partial copy of the central server's metadata and that might contain related file content. The replica copies by using 'p4 pull' or 'p4 journalcopy'. A replica can be used as a backup server for disaster recovery., standby, and edge server A server that is part of a commit-edge environment that can independently support work in progress for locally-bound clients, thereby reducing the load on the commit server. must be able to resolve to the same S3 bucket that is defined in the depot spec.

Depending on factors such as network latency and bandwidth, you might not find S3 buckets to perform well enough to be practical.

You can create an S3 data source as a place to store files for a P4 Server depot. Create a depot specification that sets the `Address` field to map to the S3 datasource. The location of the S3 bucket and the credentials are stored in the depot spec on a per-depot basis using the `Address` field in the following format:

    Address: s3,region:us-east-1,bucket:p4d-depot,accessKey:,secretKey:******

where:

- `s3` must be at the start of the address.

- The settings are comma-separated, with a colon to separate the key and value.

The S3 data source requires the following AWS Identity and Access Management (IAM) permissions of the Amazon S3 API Reference: `s3:GetObject`, `s3:PutObject`, and `s3:DeleteObject`.

Supported keys are:

Key | Note
--- | ---
`url` | `https://bucketname.s3.amazonaws.com` Some S3 implementations might not require this key.
`region` | Some S3 implementations might not require this key.
`bucket` | Required
`accessKey` | Required
`secretKey` | Required
`token` | Depending on bucket security, this key might be optional.
profile | Fetch the S3 account's credentials from the .aws/credentials file for the specified profile.
role | Fetch the S3 account's credentials from the specified EC2 role.

Only one of the credential mechanisms can be specified:

- accesskey/secretkey/token

- profile

- role

### Create an S3-backed depot

1. Create a new depot by using the `p4 depot` command, and set the depot’s `Type`. For example,

       p4 depot -t stream s3DepotName

2. In the depot specification,

   - Do not change the value of the `Map` field because it will not be used.

   - Create a new field for the address, and enter the s3 information and credentials as a comma-separated list of `key:value` pairs according to the requirements of your S3 storage provider.

#### Examples

Different storage providers might have different requirements. For the most complete, correct, and current requirements, check with your storage provider.

AWS:

    Address: s3,region:us-west-2,bucket:my-s3bucket,accessKey:******,secretKey:******

Digital Ocean:

    Address: s3,url:https://my-s3bucket.sfo3.digitaloceanspaces.com,bucket:my-s3bucket,accessKey:******,secretKey:******

MinIO:

    Address: s3,url:https://server:port/my-s3bucket,bucket:my-s3bucket,accessKey:******,secretKey:******

Google Cloud Storage:

    Address: s3,url:https://storage.googleapis.com/my-s3bucket,bucket:my-s3bucket,accessKey:******,secretKey:******

P4 Server does not back up or restore versioned files. Check with your cloud storage provider about the availability and data resiliency of your versioned files.

### S3 error handling

In 2025.2 and later, S3 type errors can be handled in conjunction with two configurables: s3.credentialerror.retry and s3.error.retry. The configurables have defaults to retry if certain common errors occur. You can customize which HTTP status and AWS errors cause the retry attempts to occur.

For example, if the default setting in `s3.credentialerror.retry` of a HTTP status code of `400` with a code of `InvalidSessionException` is always failing, even when retried, thus causing a delay before the transaction times out and fails, you can set `s3.credentialerror.retry` to
`[ 400, "ExpiredToken", "TokenRefreshRequired", "" ]`

These two configurables thus make it possible to address two situations:

1. The error is missing, but a set of retries might enable the user to avoid intermittent command failures.

2. An error is listed in the defaults, but retries never succeed. To avoid delays in reporting the failure, set the configurable to the default settings minus that error.

## Consider symlinks

Make sure all file systems are mounted correctly on source and target, and take into account any depots referenced using symlinks. Symlinks are outside the control of P4 Server and need to be considered when changing the location and copying of depots.

## If using tiny.db

If the lightweight document-oriented database, tiny.db, is being used to store any file revisions, take a checkpoint of the `tiny.db` file, correct the content to match the changes to the depot spec's `Map` field or `server.depot.root`, and restore using this manually-updated `tiny.db` checkpoint.

Your search for returned results