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

P4 Server Administration Documentation | 2025.2

# Command handler specifications

Command handlers enable you to specify how the P4 Broker responds to different commands issued by different users from within different environments. When users run commands, the P4 Broker searches for matching command handlers and uses the first match found. If no command handler matches the user’s command, the command is forwarded to the target P4 Server for normal processing.

The general syntax of a command handler specification is outlined in the sample `broker.conf`:

Copy

    command: commandpattern
    {
    # Conditions for the command to meet (optional)
    # Note that with the exception of 'flags', these are regex patterns.
      flags           = required-flags;
      args            = required-arguments;
      user            = required-user;
      workspace       = required-client-workspace;
      prog            = required-client-program;
      version         = required-version-of-client-program;

      # What to do with matching commands (required)
      action  = pass | reject | redirect | filter | respond ;

      # How to go about it
      destination = altserver;            # Required for action = redirect
      execute = /path/to/filter/program;  # Required for action = filter
      message = rejection-message;        # Required for action = reject
    }

The `commandpattern` parameter can be a regular expression and can include the `.*` wildcard. For example, a `commandpattern` of `user.*` matches both the `p4 user` and `p4 users` commands. See Regular expression synopsis.

The following table describes the parameters in detail.

Parameter | Meaning
--- | ---
`flags` | A list of options that must be present on the command line of the command being handled. This feature enables you to specify different handling for the same `p4` command, depending on which options the user specifies. Note that only single-character options can be specified here. Multi-character options, and options that take arguments should be handled by a filter program.
`args` | A list of arguments that must be present on the command line of the command being handled.
`user` | The name of the user who issued the command.
`workspace` | The P4 Server client workspace setting in effect when the command was issued.
`prog` | The P4 Server client application through which the user issued the command. This feature enables you to handle commands on a per-application basis.
`version` | The version of the P4 Server application through which the user issued the command.
`action` | Defines how the P4 Broker handles the specified commands. Valid values are: `pass`, `reject`, `redirect`, `filter`, or `respond`.
`destination` | For redirected commands, the name of the replica to which the commands are redirected. The destination must be the name of a previously defined alternate (replica) server listed in the `altserver` setting. You can implement load-balancing by setting the destination to the keyword `random`. Commands are randomly redirected to any alternate (replica) server that you have already defined. You can also set destination to the `address:port` of the server where you want commands redirected.
`execute` | The path to a filter program to be executed. For details about filter programs, see Filter programs.
`message` | A message to be sent to the user, typically before the command is executed. This can be used with any of the above actions.
`checkauth` | Authenticates the connection. If set to `true`, the P4 Broker checks that the user has access to the P4 Server before performing the action by running `p4 protects -m` with the user's connection. If set to `false`, or if not set, P4 Broker does not perform the check. If a filter program is run, the highest level permission that the user has is passed in as the `maxPerm` parameter. For details about filter programs, see Filter programs.

### Example command handler

The following command handler prevents user `joe` from invoking `p4 submit` from the `buildonly` client workspace.

Copy

    command: submit
    {
        user = joe;
        workspace = buildonly;
        action = reject;
        message = "Submit failed: Please do not submit from this workspace.";
    }

## Regular expression synopsis

A regular expression, or regex, is a sequence of characters that forms a search pattern for use in pattern matching with strings. The following is a short synopsis of the regex facility available in command handler specifications.

A regular expression is formed from zero or more branches. Branches are separated by `|`. The regex matches any string that matches at least one of the branches.

A branch is formed from zero or more pieces, concatenated together. A branch matches when all of its pieces match in sequence, that is, a match for the first piece, followed by a match for the second piece, and so on.

A piece is an atom possibly followed by a quantifier: `*`, `+`, or `?`. An atom followed by `*` matches a sequence of 0 or more instances of the atom. An atom followed by `+` matches a sequence of 1 or more instances of the atom. An atom followed by `?` matches a sequence of 0 or 1 instances of the atom.

An atom is:

- A subordinate regular expression in parentheses that matches that subordinate regular expression.
- A range:
  - . - matches any single character
  - ^ - matches the beginning of the string
  - $ - matches the end of the string
  - a `\` followed by a single character - matches that character
  - or a single character with no other significance - matches that character.

A range is a sequence of characters enclosed in square brackets (`[]`), and normally matches any single character from the sequence.

If the sequence begins with `^`, it matches any single character that is not in the sequence.

If two characters in the sequence are separated by `-`, this is shorthand for the full list of ASCII characters between them (for example, `[0-9]` matches any decimal digit, `[a-z]` matches any lowercase alphabetical character). To include a literal `]` in the sequence, make it the first character (following a possible `^`). To include a literal `-`, make it the first or last character.

## Filter programs

When the `action` for a command handler is `filter`, the P4 Broker executes the program or script specified by the `execute` parameter and performs the action returned by the program. Filter programs enable you to enforce policies beyond the capabilities provided by the broker configuration file.

The P4 Broker invokes the filter program by passing command details to the program’s standard input in the following format:

Command detail | Definition
--- | ---
`command:` | User command
`brokerListenPort:` | Port on which the broker is listening
`brokerTargetPort:` | Port on which the target server is listening
`clientPort:` | P4PORT setting of the client
`clientProg:` | Client application program
`clientVersion:` | Version of client application program
`clientProtocol:` | Level of client protocol
`apiProtocol:` | Level of api protocol
`maxLockTime:` | Maximum lock time (in ms) to lock tables before aborting
`maxMemory:` | Maximum megabytes of memory a command can consume
`maxOpenFiles:` | Maximum number of files a command can open
`maxPerm` | Highest permission (if `checkauth` is set)
`maxResults:` | Maximum number of rows of result data to be returned
`maxScanRows:` | Maximum number of rows of data scanned by a command
`workspace:` | Name of client workspace
`user:` | Name of requesting user
`clientIp:` | IP address of client
`proxyIp:` | IP address of proxy (if any)
`cwd:` | Client’s working directory
`argCount:` | Number of arguments to command
`Arg0:` | First argument (if any)
`Arg1:` | Second argument (if any)
`clientHost:` | Hostname of the client
`brokerLevel:` | The internal version level of the broker.
`proxyLevel:` | The internal version level of the proxy (if any).

Non-printable characters in command arguments are sent to filter programs as a percent sign followed by a pair of hex characters representing the ASCII code for the non-printable character in question. For example, the tab character is encoded as `%09`.

Your filter program must read this data from STDIN before performing any additional processing, regardless of whether the script requires the data. If the filter script does not read the data from STDIN, "broken pipe" errors can occur, and the broker rejects the user’s command.

### Message formats for the filter program response

Your filter program must respond to the Broker on standard output (stdout) with data in one of the four following formats, where the values for the `action` are case-sensitive.

    action: PASS
    message: a message for the user (optional)

    action: REJECT
    message: a message for the user (required)

    action: REDIRECT
    altserver: (an alternate server name)
    message: a message for the user (optional)

    action: RESPOND
    message: a message for the user (required)

    action: CONTINUE

### Action keyword

The `action` keyword is always required and tells the Broker how to respond to the user’s request. The available `action`s are:

Action | Definition
--- | ---
`PASS` | Run the user’s command unchanged. A `message` for the user is optional.
`REJECT` | Reject the user’s command and return an error message. A `message` for the user is required.
`REDIRECT` | Redirect the command to a different (alternate) replica server. An `altserver` is required. See Configuring alternate servers to work with central authorization servers for details. A `message` for the user is optional. To implement this action, the broker makes a new connection to the alternate server and routes all messages from the client to the alternate server rather than to the original server. This is unlike HTTP redirection where the client is requested to make its own direct connection to an alternate web server.
`RESPOND` | Do not run the command; return an informational message. A `message` for the user is required.
`CONTINUE` | Defer to the next command handler matching a given command. For information on using multiple handlers, see the Perforce Knowledge Base article, How the Broker can process multiple command handlers.

If the filter program returns a response that does not comply with any of the four message formats above, the user’s command is rejected. If errors occur during the execution of your filter script code cause the Broker to reject the user’s command, the Broker returns an error message.

Broker filter programs have difficulty handling multi-line message responses. You must use syntax like the following to have new lines be interpreted correctly when sent from the broker:

    message="\"line 1\nline 3\nline f\n\""

That is, the string must be quoted twice.

## Next step

Alternate server definitions

Your search for returned results