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 Enabling SSL support. 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, and must set P4TRUST, specifying the path to that file (P4TRUST cannot be specified in the broker configuration file).

For complete information about enabling SSL for the broker, see:
http://answers.perforce.com/articles/KB/2596

You can issue the p4 info to determine whether you are connected to a broker or not. When connected to a broker, the Broker address and Broker version appear in the output:

$ p4 info
User name: bruno
Client name: bruno-ws
Client host: bruno.host
Client root: /Users/bruno/Workspaces/depot
Current directory: /Users/bruno/Workspaces/depot/main/jam
Peer address: 192.168.1.40:55138
Client address: 192.168.1.114
Server address: perforce:1667
Server root: /perforce/server/root
Server date: 2014/03/13 15:46:52 -0700 PDT
Server uptime: 92:26:02
Server version: P4D/LINUX26X86_64/2014.1/773873 (2014/01/21)
ServerID: master-1666
Broker address: perforce:1666 Broker version: P4BROKER/LINUX26X86_64/2014.1/782990
Server license: 10000 users (support ends 2016/01/01)
Server license-ip: 192.168.1.40
Case Handling: sensitive

When connected to a broker, you can use the p4 broker command to see a concise report of the broker’s info:

$ p4 broker
Current directory: /Users/bruno/Workspaces/depot/main/jam
Client address: 192.168.1.114:65463
Broker address: perforce:1666
Broker version: P4BROKER/LINUX26X86_64/2014.1/782990

To apply the IP address of a broker user’s workstation against the protections table, prepend the string proxy- to the workstation’s IP address.

For instance, consider an organization with a remote development site with workstations on a subnet of 192.168.10.0/24. The organization also has a central office where local development takes place; the central office exists on the 10.0.0.0/8 subnet. A Perforce service resides in the 10.0.0.0/8 subnet, and a broker resides in the 192.168.10.0/24 subnet. Users at the remote site belong to the group remotedev, and occasionally visit the central office. Each subnet also has a corresponding set of IPv6 addresses.

To ensure that members of the remotedev group use the broker while working at the remote site, but do not use the broker when visiting the local site, add the following lines to your protections table:

list    group    remotedev     192.168.10.0/24              -//...
list    group    remotedev     [2001:db8:16:81::]/48        -//...

write   group    remotedev     proxy-192.168.10.0/24         //...
write   group    remotedev     proxy-[2001:db8:16:81::]/48   //...

list    group    remotedev     proxy-10.0.0.0/8             -//...
list    group    remotedev     proxy-[2001:db8:1008::]/32   -//...

write   group    remotedev     10.0.0.0/8                    //...
write   group    remotedev     [2001:db8:1008::]/32          //...

The first line denies list access to all users in the remotedev group if they attempt to access Perforce without using the broker from their workstations in the 192.168.10.0/24 subnet. The second line denies access in identical fashion when access is attempted from the IPV6 [2001:db8:16:81::]/48 subnet.

The third line grants write access to all users in the remotedev group if they are using the broker and are working from the 192.168.10.0/24 subnet. Users of workstations at the remote site must use the broker. (The broker itself does not have to be in this subnet, for example, it could be at 192.168.20.0.) The fourth line denies access in identical fashion when access is attempted from the IPV6 [2001:db8:16:81::]/48 subnet.

Similarly, the fifth and sixth lines deny list access to remotedev users when they attempt to use the broker from workstations on the central office’s subnets (10.0.0.0/8 and [2001:db8:1008::]/32). The seventh and eighth lines grant write access to remotedev users who access the Perforce server directly from workstations on the central office’s subnets. When visiting the local site, users from the remotedev group must access the Perforce server directly.

When the Perforce service evaluates protections table entries, the dm.proxy.protects configurable is also evaluated.

dm.proxy.protects defaults to 1, which causes the proxy- prefix to be prepended to all client host addresses that connect via an intermediary (proxy, broker, broker, or edge server), indicating that the connection is not direct.

Setting dm.proxy.protects to 0 removes the proxy- prefix and allows you to write a single set of protection entries that apply both to directly-connected clients as well as to those that connect via an intermediary. This is more convenient but less secure if it matters that a connection is made using an intermediary. If you use this setting, all intermediaries must be at release 2012.1 or higher.

A broker configuration file contains three sections:

The broker configuration requires specification of the target setting, which identifies the Perforce service to which commands are to be sent, the listen address, which identifies the address where the broker listens for commands from Perforce client applications, and the optional altserver alternate server address, which identifies a replica, proxy, or other broker connected to the Perforce service.

The host specification uses the format protocol:host:port, where protocol is the communications protocol (beginning with ssl: for SSL, or tcp: for plaintext), host is the name or IP address of the machine to connect to, and port is the number of the port on the host.

The host field can be the hosts' hostname or its IP address; both IPv4 and IPv6 addresses are supported. For the listen setting, you can use the * wildcard to refer to all IP addresses, but only when you are not using CIDR notation.

If you use the * wildcard with an IPv6 address, you must enclose the entire IPv6 address in square brackets. For example, [2001:db8:1:2:*] is equivalent to [2001:db8:1:2::]/64. Best practice is to use CIDR notation, surround IPv6 addresses with square brackets, and to avoid the * wildcard.

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

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

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."
}

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

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

The Perforce Broker can direct user requests to an alternate server to reduce the load on the target server. These alternate servers must be replicas (or brokers, or proxies) connected to the intended target server.

To set up and configure a replica server, see “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=[protocol:]host:port }

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

To configure the broker as a router, add the router statement to the top level of the broker configuration. The target server of the broker-router should be a commit or master server.

target      = commitserv.example.com:1666;
listen      = 1667;
directory   = /p4/broker;
logfile     = broker.log;
debug-level = server=1;
admin-name  = "Perforce Admins";
admin-phone = 999/911;
admin-email = perforce-admins@example.com;
router;

You must then include altserver statements to specify the edge servers of the commit server (or the workspace servers of the depot master) that is the target server of the broker-router.

altserver: edgeserv1
{
    target = edgeserve1.example.com:1669;
}

If you are using the broker to route messages for a commit-edge architecture, you must list all existing edge serves as altservers.

When a command arrives at the broker, the broker looks in its db.routing table to determine where the command should be routed. The routing logic attempts to bind a user to a server where they already have clients. You can modify the routing choice on the p4 command line using the following argument to override routing for that command.

-Zroute=serverID

Routing logic uses a default destination server, chosen at random, if a client and user have no binding to an existing edge server. That is, requests are routed to an existing altserver that is randomly chosen unless a specific destination is given.