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

P4 CLI Reference | 2025.1

# p4 topology

Reports the P4 servers that are connected directly and indirectly to the innermost server, including an indicator of the server this command is running on.

## Syntax

    p4 [g-opts] topology [-a | -t numOfDays] [-F filter] [-T field,...]
    p4 [g-opts] topology -D date [-y] [-e] [-s serverAddress]
    p4 [g-opts] topology -d [-y] -s serverAddress -i serverID [-p targetAddress]
    p4 [g-opts] topology -d [-y] -c date [-e]
    p4 [g-opts] topology -d [-y] -l lastSeenDate [-e]
    p4 topology -m [-y] -s serverAddress -i serverID -S newServerAddress -I newServerID
    p4 topology -m [-y] -s serverAddress -i serverID -p targetAddress -S newServerAddress -I newServerID -P newTargetAddress

Syntax conventions

## Description

This command:

- Reports the P4 servers that are connected directly and indirectly to the innermost server.

- Includes an indicator of the server this command is running on, such as `Topology command was run on server - 127.0.0.1:1677`

- Relies on the Topology table of the database schema.

These servers can be connected directly or indirectly. The types of servers listed are: standard, commit, edge (including edge-to-edge chaining), read-only replica, forwarding replica, standby, build, proxy, and broker.

By default, the command reports only the latest configurations based on the P4 Server address, Target server address, and serverID for each service.

### Output format

Command | Format of the output
--- | ---
`p4 topology` | untagged, used by the Perforce admin for a quick validation
`p4 -ztag topology` | tagged (see `-z tag` under Global options)
`p4 -ztag -Mj topology` | JSON (see `-Mj tag` under Global options)

## Options

`-a` | (Optional) Display all the configurations of the services that are captured in the Topology table. With the `-a` option, the output does not exclude records that have been superseded, such as an older standard server entry after that server has been converted to a commit-server. See Example of -a to see all records as well as db.topology in P4 Schema Documentation.
`-d` | Defaults to a preview of marking a record as deleted, which: does not remove the record from the topology table excludes that record from the output of `p4 topology`, but such records are included in the output of `p4 topology -a` If there are multiple entries with the same server address, destination address, and server id, the operation is performed on the server record with the latest timestamp of its creation. To execute the operation, include the `-y` option. See Mark records as deleted based on creation date and Mark records as deleted records based on lastSeenDate.
`-D` | Defaults to a preview of the permanent deletion of the record based on the date in Linux epoch format. This date does not necessarily correspond to a `creationDate` or a `lastSeenDate`. To see the date in this format, use the `p4 -ztag topology` command. See Delete records of a date. To permanently delete the specified records from the table, include the `-y` option.
`-c creationDate` | Specify the creation date in Linux epoch format. The creationDate represents the first time the server record was entered into the Topology table.
`-l lastSeenDate` | Specify the last seen date in Linux epoch format. The lastSeenDate represents the last time the server record was updated.
`-e` | Include all the records earlier than, and including, the specified `-d date`.
`-y` | Can be used with `-d`, `-D`, and `-m` to perform the action rather than show a preview.
`-s serverAddress` | The server address.
`-p` | The existing target address.
`-i` | The existing server ID as opposed to -I, the new server ID when using the `-m` option.
`-S` | The new server address when using the `-m` option.
`-P` | The new target address.
`-I` | The new server ID.
`-m` | Ensures that the move operation marks the specified source server record as being moved to the target server. If the topology record has the target address, it is mandatory to provide both the source target address `-p` and the new target address `-P`. Defaults to a preview. To execute the operation, include the `-y` option.
`-t numberOfDays` | Display the configurations recorded during the specified number of `numberOfDays` prior to, and including, today. Any positive integer is valid. See Limit time with -t. The `-t` option internally uses the value of the `LastSeenDate` field. Whereas `Date` represents the first time that the topology command reported a specific service, `LastSeenDate` is the most recent time that the topology command reported a specific service.
`-F filter` | List only those records that match the criteria specified by `filter`. See Filter for fields with -F. The filter pattern can be a regular expression. Topology uses the same filtering as p4 fstat. See Filter with -F on the `p4 fstat` page.
`-T field` | Limits output to the specified fields, where the specified fields are in a comma-separated list. See Limit fields with -T .
`g-opts` | See Global options, especially `-ztag` and `-ztag -Mj`.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
N/A | N/A | `super` available to an operator user

Output that includes `0.0.0.0` indicates that the host address is unspecified. In such a case, P4 Server listens on all the available IPV4 addresses on the host. For example, if a host has two IP addresses, `192.168.1.1` and `10.1.2.1`, and a P4 Server running on this host listens on `0.0.0.0`, the server is listening on both IP addresses.

## Examples

### Limit time with -t

`p4 topology -t 7` outputs results for the current day as well as six days prior to the current day.

### Filter for fields with -F

`p4 topology -F "^ServerAddress=127.0.0.1* ^ServerAddress=0.0.0.0*"` uses a regular expression that filters out any results where the ServerAddress begins with `127.0.0.1` or `0.0.0.0`

### Limit fields with -T

If `p4 -ztag topology` outputs

... ServerAddress 127.0.0.1:10868
... Date 1645786193
... ServerID oldstandard
... Type standard
... LastSeenDate 1645788650
... ReportingServer true

`p4 topology -T ReportingServer,ServerID` limits output to the specified fields:

... ServerID oldstandard
... ReportingServer true

### Delete records of a date

First, run `p4 -ztag topology` to get output that includes the Linux epoch date of each record, such as

`... Date 1633567679`

Second, preview the permanent deletion of the records with that date:

`p4 topology -D 1633567679`

and note that the output includes this comment:

`# This is in preview mode. For actual deletion, use '-y'.`

Finally, confirm that you want to permanently delete all the records of the specified date:

`p4 topology -y -D 1633567679`

### Delete a record of a date

To delete a specific record of that date, include the server address:
p4 topology -y -D 1633567679 -s 127.0.0.1:26385

Example of deleting records prior to and including a specified date

### Delete prior records

To delete records prior to and including a specified date, include the -e option

`p4 topology -y -e -D 1633567679`

### Mark records as deleted based on creation date

`p4 topology -d -c 1664451396 -y`

### Mark records as deleted records based on lastSeenDate

`p4 topology -d -l 1664451395 -y`

### Example of -a to see all records

The output of `p4 topology -a` can be a superset of the output of `p4 topology` because the `-a` option includes records that have been superseded. In this example, a server restart is associated with the conversion of that server's type from `standard` to `commit-server`. With the `-a` option, records that are marked for deletion are included.

p4 topology -a | p4 topology
--- | ---
127.0.0.1:4444 standard 2022/05/18 13:59:55 commit-server 2022/05/18 13:59:55 | 127.0.0.1:4444 standard 2022/05/18 13:59:55 commit-server 2022/05/18 13:59:55
127.0.0.1:4444 standard 2022/05/18 13:59:53 standard 2022/05/18 13:59:53 | (This entry does not appear without `-a` because it is superseded by the server type conversion.)

Your search for returned results