Skip to main content
Put a PBX or media server, such as Asterisk or FreeSWITCH, behind Routr as a Peer. Routr handles registration, routing, and load balancing. The PBX keeps doing media work: IVRs, voicemail, conferences, and recordings.

​
How a Peer works

A Peer is a trusted SIP endpoint identified by a username and an address of record (AOR). When the PBX registers with the Peer’s username, Routr stores its contact under the Peer’s AOR. Every PBX instance that registers with the same username joins the same AOR, and Routr spreads calls across them using the Peer’s load-balancing settings. Peers take part in three routing types:
peer-to-agent routing (the PBX calling an Agent registered with Routr) is not supported yet.

​
Prerequisites

​
Connect the PBX

1

Create credentials for the PBX

Create the credentials the PBX uses to authenticate. Every instance of the same PBX group uses the same set.
2

Create the Peer

Create a Peer with the same username, an AOR, the credentials, and a load-balancing algorithm.
The prompts map to these fields:Least Sessions needs the Location Service to run with Redis. The routr-one image keeps registrations in memory, so keep Round Robin there. See Scale the Location Service with Redis.In a file-based deployment, the same Peer looks like this:
config/resources/peers.yaml
3

Register the PBX with Routr

Configure an outbound registration on the PBX. It must:
  • Send REGISTER to Routr’s address and SIP port (for example 192.168.1.3:5060).
  • Use the Peer’s username as the user part of the From header.
  • Answer Routr’s 401 challenge with digest authentication, using the Peer’s credentials.
  • Refresh the registration before it expires.
In Asterisk, this is an outbound registration plus an endpoint with authentication in pjsip.conf. In FreeSWITCH, it is a gateway with register=true in a Sofia profile. Repeat the same configuration on every instance you want in the group.
The Load balancing Asterisk tutorial runs two Asterisk containers that register as one Peer.
4

Route calls to the Peer

Agents reach the Peer by dialing its username, for example sip:asterisk@sip.local. Routr looks up the Peer’s AOR and picks a registered instance.To send PSTN calls to the PBX, set the Number’s AOR link to the Peer’s AOR.
Enter sip:asterisk@sip.local at the AOR Link prompt. In YAML, set spec.location.aorLink: sip:asterisk@sip.local.
5

Place outbound calls from the PBX

To call the PSTN, the PBX sends an INVITE to Routr with these properties:
  • The From user is the Peer’s username.
  • The Request-URI user is the destination number. It must not match an existing Number or Agent.
  • An X-DOD-Number header carries the caller ID number in E.164 format, for example X-DOD-Number: +17066041487.
  • It answers Routr’s 401 challenge with the Peer’s credentials.
Routr finds the Number whose telUrl is tel: followed by the X-DOD-Number value, then sends the call through that Number’s Trunk. It sets P-Asserted-Identity and Remote-Party-ID from the Number and authenticates with the Trunk’s outbound credentials.In Asterisk or FreeSWITCH, add the header in the dialplan before the call leaves for Routr.

​
Verify

Confirm the Peer exists with the expected AOR and username, then make one call of each type.
An Agent that dials the Peer’s username reaches the PBX, a call to the Number reaches the PBX, and a call from the PBX with X-DOD-Number reaches the PSTN.

​
Troubleshooting

Routr removes X-DOD-Number and other platform headers from calls that arrive from the PSTN, so an outside caller can’t set them.

Peers reference

Every Peer field.

Load balancing

Round-robin, least-sessions, and session affinity.

Routing types

How Connect decides where a call goes.

SIP headers

X-DOD-Number and the other headers Routr reads and writes.