Tutorial: Getting Started with Routr SIP Server

Pedro Sanders
4 min readMay 24, 2019

--

Routr is a good starting point for fast deployment of multi-tenant VoIP networks. Every day we strive to make this tool more comfortable to use. In this tutorial, I cover the basics to get you started with Routr.

Content

  • Prerequisites
  • Installing the Server and Tooling
  • Configuring the Server
  • Verifying the configuration
  • Configuring the SIP devices
  • Initiating a call

Prerequisites

To complete this tutorial, you need to have two SIP phones connected in the same network. You are also going to need a fresh installation of the Routr SIP Server. Finally, if you would like to call outside the local network, you are also going to need a SIP service provider.

Installing the Server and Tooling

To install Routr SIP Server follow these simple steps:

➊ Obtain a binary of the server for your OS at Github

➋ Extract the content in a folder of your choice

tar xvfz routr-*.tar.gz
cd routr-*

➌ Start the server by running the command ./routr— the output looks similar to the image below.

Starting Routr SIP Server

Optionally, if you want to install the command line tool you can do so by running the following in your console: npm i -g routr-ctl

Configuring the Server

By default, Routr SIP Server ships with configuration examples with a basic VoIP scenario. In this section, I cover some relevant information about the configuration files.

Configuring a Gateway and DID

A Gateway is an IP entity that allows call termination. Your SIP provider can give pertinent information to configure this resource. The main parameters you are looking for are registration-host and its credentials — the following YAML example represents a Gateway resource in Routr.

- apiVersion: v1beta1
kind: Gateway
metadata:
name: Provider Inc
spec:
regService:
host: sip.provider.net
credentials:
username: 'youruser'
secret: 'yoursecret'
transport: udp

To configure your DID or virtual number, you must open and edit the fileconfig/dids.yml. In the example below, notice how your reference the Gateway by using the field metadata.gwRef.

To successfully configure your DID you must provide a valid telUrl formatted, precisely, as sent by the SIP provider, and an aorLink pointing to an existing Agent or Peer.

- apiVersion: v1beta1
kind: DID
metadata:
gwRef: gweef506
geoInfo:
city: Columbus, GA
country: USA
countryISOCode: US
spec:
location:
telUrl: 'tel:17066041487'
aorLink: 'sip:1001@sip.local'

Configuring a new Domain

Routr is a Domain centric SIP Server. A Domain resource is used to group several Agents in the same context. The Domain URI can be an arbitrary name, but we recommend using a fully qualified domain name (FQDN).

EgressPolicy is required to allow calls outside the Domain

- apiVersion: v1beta1
kind: Domain
metadata:
name: Local Office
spec:
context:
domainUri: sip.local
egressPolicy:
rule: .*
didRef: dd50baa4

Configuring the Agents

For this scenario, we need two resources of type Agent. These, ultimately represent your SIP devices.

Pay close attention to the credentials block since it contains the username and secret for both Agents.

- apiVersion: v1beta1
kind: Agent
metadata:
name: John Doe
spec:
credentials:
username: '1001'
secret: '1234'
domains: [sip.local]
- apiVersion: v1beta1
kind: Agent
metadata:
name: Janie Doe
spec:
credentials:
username: '1002'
secret: '1234'
domains: [sip.local]

Verifying the configuration

To verify the configuration, issue one the following command for the corresponding resource:

  • rctl get agents
  • rctl get gateway
  • rctl get domain
  • rctl get did

Your output should look similar to the image below:

Getting information about Routr resources

Configuring the SIP devices

Use the information in the Agent resource file to configure your SIP device.

We are using “Telephone” for this example. You might use any softphone you wish. Keep in mind that the configuration will look slightly different.

Account information on Telephone
Telephone advanced settings

Now, we need to ensure that both devices have registered on Routr. For that, you can use the rctl locate command. If everything went well you should look something like this:

Initiating a call

Our final step is to call one SIP devices from the other. Use the destination URI to reach the other device. For example, 1001@sip.local

For calls outside the Domain, use the number you want to call with the Domain of the callee (i.e.: 7853178060@sip.local)

What’s Next?

You can check out the documentation to see more examples. If you have any questions, start an issue on Github or contact us via:

--

--

Pedro Sanders

Founder at @fonoster · Building the Open-Source alternative to Twilio · Posts about my journey with COSS & SaaS.