Using the broker as a load-balancing router

You can configure the broker to act as a load-balancing router among edge servers. When you configure a broker to act as a router, the broker creates a db.routing file. This file provides a mapping of client workspaces and users to specific servers. In effect, this file routes a given incoming command to the appropriate server, such as the commit server or a specific edge server.

Tip

Depending on your use case, using a different approach might be preferable. See Multi-server architectures.

Configuring the broker as a router

To configure the broker as a router:

  1. 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. For example:

  2. 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 = [email protected];
    router;
  3. Include altserver statements to specify the edge servers of the commit server that is the target server of the broker-router. For example:

altserver: edgeserv1
{
    target = edgeserve1.example.com:1669;
}
altserver: edgeserv2
{
    target = edgeserve2.example.com:1668;
}
Note
  • altserver names must match the server IDs

  • If you are using the broker to route messages for a commit-edge architecture, you must list the altserver names of all existing edge servers

Routing policy and behavior

When a command arrives at the broker, the broker uses the mapping to determine where the command should be routed. The routing logic attempts to bind a user to a server where that user already has client workspaces. You can modify the routing choice on the p4 command line by using the following argument to override routing for that command.

-Zroute=serverID

If a client and user have no binding to an existing edge server, an existing altserver is chosen at random.

To route requests to the commit server

Use a destination form similar to this:

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 = [email protected];
router;
destination target;

To cause new users to be bound to a new edge server

Use a destination form similar to this:

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 = [email protected];
router;
destination "myNewEdge";

where "myNewEdge" has already been defined as an altserver.

To force a command to be routed to the commit server

Use an action=redirect rule with a destination target statement:

command: regex pattern
{
    action=redirect;
    destination target;
}

where target is the commit server.

To reset the mapping

To reset the mapping, remove the db.routing file. For example, when you move clients to a different workspace or edge server, you need to remove the db.routing file from the home directory of the broker (see the directory setting of the broker config file).

To remove the file, you might first need to shut down the p4broker process.