Perforce 2013.1: System Administrator's Guide

Chapter 11

The Perforce Broker

What is the Broker?

The Perforce Broker (P4Broker) enables you to implement local policies in your Perforce environment by allowing you to restrict the commands that can be executed, or redirect specific commands to alternate (replica) Perforce servers.

The Perforce Broker is a server process that mediates between Perforce client applications and Perforce servers, including proxy servers. For example, Perforce client applications can connect to a proxy server that connects to the broker, which then connects to a Perforce server. Or, Perforce client applications can connect to a broker configured to redirect reporting-related commands to a read-only replica server, while passing other commands through to a master server.

From the perspective of the end user, the broker is transparent: users connect to a Perforce Broker just as they would connect to any other Perforce Server.

System requirements

To use the Perforce Broker, you must have:

•	A Perforce server at release 2007.2 or higher (2012.1 or higher to use SSL).

•	Perforce applications at release 2007.2 or higher (2012.1 or higher to use SSL).

The Perforce Broker is designed to run on a host that lies close to the Perforce Server (P4D), preferably on the same machine.

Installing the Broker

To install P4Broker, do the following:

1.	Download the p4broker executable from the Perforce website,

2.	Copy it to a suitable directory on the host (such as /usr/local/bin), and ensure that the binary is executable:

chmod +x p4broker

Running the Broker

After you have created your configuration file (see Configuring the Broker), start the Perforce Broker from the command line by issuing the the following command:

p4broker -c config_file

Alternatively, you can set P4BROKEROPTIONS before launching the broker and use it to specify the broker configuration file (or other flags) to use.

For example, on Unix:

$ export P4BROKEROPTIONS="-c /usr/perforce/broker.conf" $ p4broker -d

and on Windows:

> p4 set -s P4BROKEROPTIONS="-c c:\p4broker\broker.conf" > p4broker

The Perforce Broker reads the specified broker configuration file, and on Unix platforms the -d flag causes the Perforce Broker to detach itself from the controlling terminal and run in the background.

To configure the Perforce Broker to start automatically, create a startup script that sets P4BROKEROPTIONS runs the appropriate p4broker command. On Windows systems, you can also P4BROKEROPTIONS and run the broker as a service. For more information, see "Installing P4Broker on Windows and Unix systems" on the Perforce Knowledge Base:

http://kb.perforce.com/article/998

Enabling SSL support

To encrypt the connection between a Perforce Broker and its end users, your broker must have a valid private key and certificate pair in the directory specified by its P4SSLDIR environment variable. Certificate and key generation and management for the broker works the same as it does for the Perforce Server. See Key and certificate management. The users' Perforce applications must be configured to trust the fingerprint of the broker.

To encrypt the connection between a Perforce Broker and a Perforce Server, your broker must be configured so as to trust the fingerprint of the Perforce Server. That is, the user that runs p4broker (typically a service user) must create a P4TRUST file (using p4 trust) that recognizes the fingerprint of the Perforce Server.

P4Broker flags

Flag	Meaning
-c file	Specify a configuration file. Overrides P4BROKEROPTIONS setting.
-C	Output a sample configuration file.
-d	Run as a daemon (in the background)
-f	Run as a single-threaded (non-forking) process
-h	Print help message
-q	Run quietly (no startup messages)
-V	Print broker version
-v subsystem=level	Set server trace flags. Overrides value P4DEBUG setting. Default is null.
-Gc	Generate SSL credentials files for the broker: create a private key (privatekey.txt) and certificate file (certificate.txt) in P4SSLDIR, and then exit. Requires that P4SSLDIR be set to a directory that is owned by the user invoking the command, and that is readable only by that user. If config.txt is present in P4SSLDIR, generate a self-signed certificate with specified characteristics.
-Gf	Display the fingerprint of the broker's public key, and exit. Administrators can communicate this fingerprint to end users, who can then use the p4 trust command to determine whether or not the fingerprint (of the server to which they happen to be connecting) is accurate.

Configuring the Broker

P4Broker is controlled by a broker configuration file. The broker configuration file is a text file that contains rules for

Specifying which commands that individual users can use

Defining commands that are to be redirected to specified replica server.

To generate a sample broker configuration file, issue the following command:

p4broker -C > p4broker.conf

You can edit the newly-created p4broker.conf file to specify your requirements.

Format of broker configuration files

A broker configuration file contains three sections:

•	Global settings: settings that apply to all broker operations

•	Alternate server definitions: the addresses and names of replica servers to which commands can be redirected in specified circumstances

•	Command handler specifications: specify how individual commands should be handled; in the absence of a command handler for any given command, the Perforce Broker permits the execution of the command

Global settings

The following settings apply to all operations you specify for the broker.

Setting	Meaning	Example
target	The default Perforce Server (P4D) to which commands are sent unless overridden by other settings in the configuration file.	target = host:port;
listen	The address on which the Perforce Broker listens for commands from Perforce client applications.	listen = [host:]port;
directory	The home directory for the Perforce Broker. Other paths specified in the broker configuration file must be relative to this location.	directory = path;
logfile	Path to the Perforce Broker logfile.	logfile = path;
debug-level	Level of debugging output to log.	debug-level = server=1;
admin-name	The name of your Perforce Administrator. This is displayed in certain error messages.	admin-name = "P4 Admin";
admin-email	An email address at which users can contact their Perforce Administrator.	admin-email = admin@example.com;
admin-phone	The telephone number of the Perforce Administrator.	admin-phone = nnnnnnn;
redirection	The redirection mode to use: selective or pedantic. In selective mode, redirection is permitted within a session until one command has been executed against the default (target) server. From then on, all commands within that session run against the default server and are not redirected. In pedantic mode, all requests for redirection are honored. The default mode is selective.	redirection = selective;
service-user	An optional user account by which the broker authenticates itself when communicating with a target server.	service-user = svcbroker;
ticket-file	An optional alternate location for P4TICKETS files.	ticket-file = /home/p4broker/.p4tickets;
compress	Compress connection between broker and server. Over a slow link such as a WAN, compression can increase performance. If the broker and the server are near to each other (and especially if they reside on the same physical machine), then bandwidth is not an issue, and compression should be disabled to spare CPU cycles.	compress = false;

Command handler specifications

Command handlers enable you to specify how the broker responds to different commands issued by different users from within different environments. When users run commands, the Perforce 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 Perforce Server for normal processing.

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

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 ;   # 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 include the ".*" wildcard. For example, a commandpattern of "user.*" matches both the "p4 user" and "p4 users" commands.

The following table describes the parameters in detail.

Parameter	Meaning
flags	A list of flags 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 flags the user specifies. Note that only single character flags may be specified here. Multi-character flags, and flags 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 Perforce client workspace setting in effect when the command was issued.
prog	The Perforce 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 Perforce application through which the user issued the command.
action	Defines how the Perforce 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. 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.
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; this may be used with any of the above actions.

For example, the following command handler prevents user joe from invoking p4 submit from the buildonly client workspace.

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

Filter Programs

When the action for a command handler is filter, the Perforce 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 Perforce 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
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
maxScanRows:	maximum number of rows of data scanned by a command
maxResults:	maximum number of rows of result data to be returned
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)

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.

Your filter program must respond to the Broker on standard output (stdout) with data in one of the four following formats:

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)

Note	The values for the action are case-sensitive.

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

Action	Definition
PASS	Run the user's command unchanged. A message for the user is optional.
REJECT	Reject the user's command; 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.
RESPOND	Do not run the command; return an informational message. A message for the user is required.

If the filter program returns any response other than something complying with 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.

Alternate server definitions

The Perforce Broker can direct user requests to an alternate server to reduce the load on the default server. These alternate servers must be replicas of the target server.

To set up and configure a replica server, see Chapter 10, Perforce Replication. The broker works with both metadata-only replicas and with replicas that have access to both metadata and versioned files.

There is no limit to the number of alternate replica servers you can define in a broker configuration file.

The syntax for specifying an alternate server is as follows:

altserver name { target=host:port }

The name assigned to the alternate server is used in command handler specifications. See Command handler specifications.

Configuring alternate servers to work with central authorization servers

Alternate servers require users to authenticate themselves when they run commands. For this reason, the Perforce Broker must be used in conjunction with a central authorization server (P4AUTH) and Perforce Servers at version 2007.2 or later. For more information about setting up a central authorization server, see Centralized authorization server (P4AUTH).

When used with a central authorization server, a single p4 login request can create a ticket that is valid for the user across all servers in the Perforce Broker's configuration, enabling the user to log in once. The Perforce Broker assumes that a ticket granted by the target server is valid across all alternate servers.

If the target server in the broker configuration file is a central authorization server, the value assigned to the target parameter must precisely match the setting of P4AUTH on the alternate server machine(s). Similarly, if an alternate sever defined in the broker configuration file is used as the central authorization server, the value assigned to the target parameter for the alternate server must match the setting of P4AUTH on the other server machine(s).