Setup Manual

Prelude

This file serves to document how to set up TandmX on your Asterisk node. You are either expected to read this document with no knowledge of Asterisk and follow it to the letter, or alternatively have Asterisk experience and know where to deviate appropriately.

If you just want a simple TandmX setup, you only need to read Chapter 1 - Initial Configuration and ignore all other chapters. The other chapters will describe more complex arrangements, such trunks and NAT.

Chapter 1 - Initial Configuration

In this chapter, we will go through the quick and simple configuration of a brand new installation of Asterisk for use with the TandmX network.

TandmX is a mostly decentralised network of VoIP servers based on Asterisk, and each node must be configured to communicate with all other nodes. This communication is achived via the internet, connecting to the TandmX servers in order to receive call routing information.

Prerequisites

Definitions

Once Asterisk is installed, there will be a directory in which all of the Asterisk configuration files are kept. For Ubuntu, this is /etc/asterisk. This may also apply to other distributions too, but failing that, consult your distribution's Asterisk package documentation.

The contents of this directory may at first appear quite daunting, however you only need to make very small (and templated) modifications in addition to adding and replacing some files.

The following files have been provided to you as templates:

You'll have received the following information from a TandmX administrator:

Setup (10 min)

  1. Copy all of the files you have been provided into your Asterisk configuration directory (the one we defined as /etc/asterisk earlier for Ubuntu users), replacing existing ones where necessary (unless you know what you're doing)
  2. Extract sample-audio.zip and place the custom directory, contained within, in the Asterisk configuration directory (so it ends up being at /etc/asterisk/custom for Ubuntu users). Double check it extracted correctly and contains all of the provided audio files in various formats
  3. Open the extensions.conf file
  4. Replace the <PUT_YOUR_AUTH_KEY_HERE!> item with your Auth Key, like so: tandmxkey=xFKeeYiizpYEcAQptn72BXQNf5B3TPRJF6qkaLQKd7B7eDYPSHKCdednm9ZFM9QS
  5. Replace the <PUT_YOUR_HOST_ID_HERE!> item with your Host ID, like so: tandmxhostid=42
  6. Save and close extensions.conf, then open the iax.conf file
  7. Replace the <PUT_YOUR_SECRET_HERE!> item with your Secret, like so: secret=zV4qI2o6alBC
  8. Save and close iax.conf, then open the pjsip_wizard.conf file
  9. Within this file, you will define the numbers and the passwords for you devices. A template and an example have been provided for you in the Devices section. You should edit the example to specify a number which is within the block you were allocated by the TandmX administrator, and set a safe password. Simply copy and paste the example or the template below the others (then uncomment if necessary) and modify as appropriate.
  10. Save and close pjsip_wizard.conf
  11. Restart Asterisk (service asterisk restart for Ubuntu users)

Port forward (5 min)

Access your router, and ensure the following ports are forwarded to your Asterisk server:

If you need to reduce the RTP port range, adjust the range on your router appropriately, update the range in the rtp.conf file and restart Asterisk. You must update the rtp.conf file otherwise you may end up with calls that have no audio.

Connect your device (~5 min)

You will now have a section in pjsip_wizard.conf which defines the number and password for your device, which looks like this:

[2311001](SipDevice)
inbound_auth/username = 2311001
inbound_auth/password = sxsphil123
endpoint/callerid = "Test" <2311001>

Connect your device using the number specified (2311001) as the Username and Auth, the password specified (sxsphil123) as the password, and the IP of your Asterisk server as the SIP server and proxy.

If you need further assistance, please contact us on Discord for one-to-one support.

Chapter 2 - NAT

If you want to allow SIP devices to connect to your server via the internet instead of on your local network, you'll probably need to adjust a few more settings to tell Asterisk how to appropriately structure call information for outside calls.

SIP was never designed with NAT in mind, and as a result contains information which can confuse devices and servers once it has passed through NAT. Luckily, Asterisk provides built in functionality to resolve these confusions, as long as you enable these functions and configure them correctly.

A template configuration has already been provided to you to assist with this setup.

Setup (2 min)

  1. Open the pjsip.conf file
  2. Uncomment the lines in the NAT section at the bottom
  3. Set your public and local IP addresses. Ask us for help if you do not know how to determine these
  4. Save and close pjsip.conf
  5. Restart Asterisk (service asterisk restart for Ubuntu users)

Port forward (3 min)

Access tour router, and ensure the following ports are forwarded to your Asterisk server:

Chapter 3 - Trunks

Trunks are useful if you have a PBX which you'd like to route multiple numbers to at the same time. This saves you from configuring a separate SIP connection from your PBX to the Asterisk server for each individual number you'd like it to have access to.

A template configuration has already been provided to you to assist with this setup.

Setup (5 min)

  1. Open the pjsip_wizard.conf file
  2. A template and an example have been provided for you in the Trunks section. You should uncomment and edit the example to specify a username for your trunk device, and set a safe password. Simply copy and paste the example or the template below the others (then uncomment if necessary) and modify as appropriate.
  3. Save and close the pjsip_wizard.conf file, then open the extensions.conf file
  4. Within this file, you will define the routing for your trunked devices. An example have been provided for you in the Trunks section. You should edit the example to specify a number (or wildcard, explained in Chapter 4) which is within the block you were allocated by the TandmX administrator. Simply copy and paste the example below the others (then uncomment if necessary) and modify as appropriate. You'll end up with something that looks a bit like the example below
  5. Save and close the extensions.conf file
  6. Restart Asterisk (service asterisk restart for Ubuntu users)

Here is an example for dialing 2311211 to access the trunk named MyPBXTrunk:

exten => _2311211,1,Dial(PJSIP/${EXTEN}@MyPBXTrunk)
  same => n(end),Hangup()

Connect your trunked device (~5 min)

You will now have a section in pjsip_wizard.conf which defines the username and password for your device, which looks like this:

[MyPBXTrunk](SipDevice)
inbound_auth/username = MyPBXTrunk
inbound_auth/password = sxsphil123

Connect your device using the username specified (MyPBXTrunk) as the Username and Auth, the password specified (sxsphil123) as the password, and the IP of your Asterisk server as the SIP server and proxy.

If you need further assistance, please contact us on Discord for one-to-one support.

Chapter 4 - Advanced Trunks

Trunks can be configured extensively using various functionality provided by Asterisk. In the following examples, we will show you how to route calls in more complex ways to your trunks.

It is important to note that you can copy and paste these examples many times and point them all to the same trunk at the same time if you wish to route multiple things in multiple different ways to the same trunk.

It is recommended you consult the Asterisk documentation for tailoring your setup to your liking, however some additional more advanced examples are provided below.

Wildcard

A wildcard is a slightly more advanced trunk route which allows multiple numbers within your TandmX number block(s) to be routed to a device at the same time with a single routing configuration.

In the example below, any numbers matching 231122X are routed to the trunk named MyPBXTrunk where X can be any number 0-9, so 2311220 through 2311229 are routed to the trunk:

exten => _231122X,1,Dial(PJSIP/${EXTEN}@MyPBXTrunk)
  same => n(end),Hangup()

In the next example, we specify a range of allowed numbers for a different digit. Any numbers matching 2311[1-3]2X are routed to the trunk named MyPBXTrunk where [1-3] can be 1, 2 or 3, so 2311120 through 2311329 are routed to the trunk:

exten => _2311[1-3]2X,1,Dial(PJSIP/${EXTEN}@MyPBXTrunk)
  same => n(end),Hangup()

Fallback

If your trunk is unavailable, you may want to route calls to another trunk, either a backup to the same PBX or to a completely different PBX. If you know what you're doing, you could even send the call to a specific device on your system.

In the example below, if a call to 231123X fails to be routed to MyPBXTrunk, it is instead routed to MyAlternativePBXTrunk:

exten => _231123X,1,Dial(PJSIP/${EXTEN}@MyPBXTrunk)
  same => n,GotoIf($["${DIALSTATUS}"="ANSWER"]?end:noanswer)
  same => n(noanswer),Dial(PJSIP/${EXTEN}@MyAlternativePBXTrunk)
  same => n(end),Hangup()

Final Thoughts

The information provided in this document barely scratches the surface of what you can do with Asterisk overall. It serves only to provide basic and slightly more advanced configurations to get you on the TandmX network and get your phones ringing sucessfully.

If you'd like to discuss something not covered in this document, or if you need assistance with any part of this document (no matter how small) feel free to join us on Discord where someone will be more than happy to help!