--- title: Building a Personal VoIP System date: May 25, 2023 description: Take control of your telephony with Asterisk! --- I've always been a big [self-hoster](https://github.com/sacredheartsc/selfhosted), but had never attempted anything related to VoIP. I recently purchased some IP phones and set up a personal home phone network using [Asterisk](https://www.asterisk.org/). This guide will help you set up your own digital telephone system using open-source tools. This guide is written for those who are experienced with self-hosting, but are totally unfamiliar with VoIP. Therefore, I'm going to gloss over certain uninteresting technicalities for the sake of brevity. ## SIP: A Brief Introduction Before getting your hands dirty with phone configuration and Asterisk dialplans, it's worth taking some time to understand the underlying network protocols involved. This will pay dividends later on when you're debugging the inevitable connectivity issues with your voice calls (trust me). The [Session Initialization Protocol](https://www.ietf.org/rfc/rfc3261.txt), or SIP, is a signaling protocol used by basically every digital telephony device produced in the last two decades. VoIP phones, softphones, office conferencing devices...they all use SIP. SIP can use either TCP or UDP, and usually listens on port 5060. There are two really important things you need to know about about SIP. 1. SIP does **not** carry the voice data. It's just a signaling protocol, and it's only used to negotiate which IP address, port, and audio format should be used to carry the audio stream. 2. SIP was initially released in 1999, and was designed with the assumption that each device has its own globally routable public IP address. After all, the IPv6 standard was released back in 1995, and NAT would soon be a thing of the past...right? Unforunately, this did not end up being the case. For example, let's say we have a standard home network with two VoIP phones in the local 192.168.1.0/24 subnet. Consider what happens when these two phones want to call each other. In plain English, the SIP handshake will go something like this: > Hello 192.168.1.6.
> I would like to place an audio call using the G.711 codec.
> Please send your audio frames to me at address 192.168.1.5, port 20000. > Hi there, 192.168.1.5!
> Sure, I support the G.711 codec.
> Please send your audio frames to me at address 192.168.1.6, port 30000. Each phone randomly chooses an unused UDP port on which to receive the other party's audio stream. After the SIP negotiation, they will both send voice data to each other using the [Real-Time Transport Protocol](https://www.rfc-editor.org/rfc/rfc3550), or RTP. Since they are both on the same local network, this works fine. ### NAT Problems Now consider what happens when we call someone _outside_ of our local network. Let's say our router has a public IP of 203.0.113.8, and our friend Alice has address 198.51.100.7. > Hello 198.51.100.7. Is Alice there?
> I would like to place an audio call using the G.711 codec.
> Please send your audio frames to me at address 192.168.1.5, port 20000. > Hi there, "192.168.1.5". I see you have source IP 203.0.113.8...strange!
> Sure, I support the G.711 codec.
> Please send your audio frames to me at address 198.51.100.7, port 30000. Thanks to [network address translation](https://en.wikipedia.org/wiki/Network_address_translation), or NAT, we are able to make the SIP connection to Alice. Unfortunately, you will probably find that audio only works in one direction! We've got two problems. First, we've asked Alice to send her audio to our _local_ IP address, which won't route over the Internet. Luckily, most devices are smart enough to use the source address of the incoming packet when these don't match up. So Alice's audio stream will probably end up at our router. But second, our router will still block all of her audio traffic! When it receives a UDP packet from Alice's audio stream, there's no stateful NAT connection to match it back to an internal client, so it's silently dropped. Sad! ### NAT Solutions There are three ways to solve this problem. 1. Give each of your SIP devices its own public IP (probably not feasible). 2. Use a SIP [Application Layer Gateway](https://www.voip-info.org/routers-sip-alg/). This is a horrible feature offered by some routers. Basically, it deep-packet-inspects your SIP traffic, rewrites the headers, and creates port forwards on-the-fly to make sure the inbound audio stream makes its way to your device. SIP ALGs are a total hack and notoriously buggy. In addition, when you decide to encrypt your SIP traffic using TLS, they quit working altogether. 3. Configure a fixed RTP port range on each of your SIP devices, then create static port forwarding rules on your router for each device. This is really the only decent option. Note that since we'll be using Asterisk, you also have the option of "proxying" all your audio streams through the Asterisk box--then you only have one port forward to set up (we'll get to that later). ## Asterisk: What _is_ it? [Asterisk](https://www.asterisk.org/) is an open-source implementation of a [private branch exchange](https://en.wikipedia.org/wiki/Business_telephone_system#Private_branch_exchange), or PBX. If you're a VoIP novice like I was, this is probably meaningless to you. A PBX is the central brain of any private telephone network. The general idea is this: You plug a bunch of dumb telephones into one side of the PBX, and you plug one or more uplinks to the [PSTN](https://en.wikipedia.org/wiki/Public_switched_telephone_network "Public Switched Telephone Network") into the other side. The PBX lets the internal phones dial each other using private internal extensions, while multiplexing calls to and from the PSTN. It also handles advanced features like voicemail, call queues, hunt groups, and interactive menus for callers. In the old days, the PBX would be a huge box down in the server room with a rat's nest of of RJ-11 telephone cables sprawling out, connecting it to every single phone in the office. These monstrosities have since been replaced with software-based PBXes that talk SIP over standard Ethernet networks. Asterisk is the de-facto open source PBX. ## Jargon Glossary Before we get started, you need to know some lingo. Asterisk is an _old_ project, with an unintuitive configuration. Hopefully this section will help you decipher some of the documentation and setup guides you find out there. Extensions : Technically, in Asterisk parlance, any dialed number is an extension. In practice though, an _extension_ typically refers to a _local_ phone number (like 6001) with an associated SIP account. While extensions can be alphanumeric, virtually no one does this--most people use 3- or 4-digit numbers. Queues : Asterisk [queues](https://www.voip-info.org/asterisk-call-queues/) are a mechanism for managing incoming callers. You can configure which local extensions should ring for each queue, and even play custom music while callers are waiting. SIP Trunk : A "SIP Trunk" is just a fancy term for your upstream telephone provider. For example, if you subscribe to a provider like [VOIP.ms](https://voip.ms/en/invite/MzU5Nzc4), they'll give you a public phone number and a SIP server to connect to, along with a username and password. This is your "SIP Trunk." DID : A DID, or "Direct Inward Dial," is the technical term for a public phone number. Contexts : In Asterisk, every call is assigned a _context_. The context is simply a name of your choosing, and you specify it when you configure each extension or SIP trunk. For example, I give all my internal phones a context called `from-home`, and I give my SIP trunk a context called `from-pstn`. Dialplan : The Asterisk [dialplan](https://wiki.asterisk.org/wiki/display/AST/Dialplan) is an arcane scripting language where you define what happens when you dial a number or an incoming call is received. The dialplan is the glue between the _extensions_ and _contexts_ described above. The syntax is fairly unintuitive, but don't worry! We'll walk through it in a later section. Codecs : A codec is a type of digital encoding used for the audio stream over the wire. Every VoIP device supports one or more codecs, and you need at least one common codec with the other party to make calls. When no shared codecs are supported, Asterisk has the ability to do man-in-the-middle transcoding.
[G.711](https://en.wikipedia.org/wiki/G.711) is basically the only codec with universal support. It has two versions: `ulaw` (North America/Japan) and `alaw` (everywhere else). I use a higher quality codec ([G.722](https://en.wikipedia.org/wiki/G.722)) for internal calls, and let Asterisk transcode down to G.711 when I call out to the PSTN. BLF / Presence : The BLF, or busy lamp field, is a little LED on your VoIP phone that lights up when one of your contacts is using their line. In Asterisk, this functionality is enabled by something called a [presence subscription](https://wiki.asterisk.org/wiki/display/AST/Configuring+res_pjsip+for+Presence+Subscriptions). SIP / PJSIP : On some guides online, you will see references to the `chan_sip` and `chan_pjsip` modules. `chan_sip` is the legacy Asterisk SIP implementation. You should be using PJSIP for everything these days. ## Step 1: Acquire an IP Phone First, you will need one or more VoIP phones. Any device that supports SIP calling should work fine with Asterisk, so this mostly comes down to personal preference. As a beginner, you'll probably want to select for ease of configuration. Most modern VoIP phones expose a friendly web GUI where you configure all your SIP accounts, ring settings, etc. I'd also recommend avoiding any devices that rely on proprietary setup tools. Personally, I've had zero problems with Yealink devices. I recommend the [T54W](https://www.yealink.com/en/product-detail/ip-phone-t54w) model for a desk phone, or the [W73P](https://www.yealink.com/en/product-detail/dect-phone-w73p) if you prefer a cordless model. You can buy these new at the usual online retailers, but eBay often has used models for sale if you want to save some money. If you don't want to buy a physical device, you can also use a softphone app like [Linphone](https://f-droid.org/en/packages/org.linphone/). I use it on my Android phone running [GrapheneOS](https://grapheneos.org/), and it works well with the right settings. I'll cover Linphone in a later section. ## Step 2: Subscribe to a VoIP Provider Next, you need to subscribe to a VoIP service so you can make and receive calls over the PSTN. You'll often see people call this a "SIP Trunk." Basically, you pay a VoIP company a small monthly fee, usually $3-$5 per month for a single DID. In exchange, they give you a public telephone number, along with credentials for their SIP server. After configuring Asterisk to connect to that SIP server, you can make and receive calls via the PSTN with that number. I can personally recommend two providers. 1. [VOIP.ms](https://voip.ms/en/invite/MzU5Nzc4) is an inexpensive provider with servers in the USA, Canada, and western Europe. You can get "unlimited" inbound calls with a single DID for about $5 a month, or less if you pay by the minute. VOIP.ms also supports call encryption via TLS/SRTP, which is nice. 2. [JMP.chat](https://jmp.chat/) (USA/Canada only) is an XMPP-based service that lets you make and receive voice calls and SMS/MMS messages using your existing XMPP account. I especially like JMP because there's already tons of high-quality native XMPP apps for both desktop and mobile devices. In addition, their entire stack is open source. While JMP is primarily focused on XMPP calling, they also provide you with a SIP account that you can use with Asterisk. There are _tons_ of other VoIP providers out there, so shop around. ## Step 3: Configure Asterisk Now you're ready to set up Asterisk. These instructions are written for RHEL-based distributions, but should be applicable to other Unixen. ### Installation First, install Asterisk: ```bash dnf install asterisk asterisk-pjsip asterisk-voicemail-plain ``` You'll also need the sound files. Some distributions include these with their Asterisk package (EPEL does not). ```bash for codec in g722 g729 gsm sln16 ulaw wav; do curl -sL "https://downloads.asterisk.org/pub/telephony/sounds/asterisk-core-sounds-en-${codec}-current.tar.gz" \ | tar xvz -C /usr/share/asterisk/sounds done ``` ### Network Configuration Now we're ready to edit some config files. If you're behind a NAT (likely), you'll need to start by telling Asterisk about your local network. Edit `/etc/asterisk/pjsip.conf` and add some transport templates. ```lisp ; /etc/asterisk/pjsip.conf ; This template contains default settings for all transports. [transport-defaults](!) type = transport bind = 0.0.0.0 ; For communication to any addresses within local_nets, Asterisk will not apply ; NAT-related workarounds. local_net = 127.0.0.0/8 local_net = 10.0.0.0/8 local_net = 172.16.0.0/12 local_net = 192.168.0.0/16 ; If you have a public static IP for your Asterisk server, set it here. external_media_address = 203.0.113.8 external_signaling_address = 203.0.113.8 ; The following UDP and TCP transports will inherit from the defaults. [transport-udp](transport-defaults) protocol = udp [transport-tcp](transport-defaults) protocol = tcp ``` Remember our discussion about NAT and RTP audio streams above? We also need to set up a static port range for incoming UDP audio traffic. Choose a suitable range for your Asterisk server in `rtp.conf`. Then, set up port forwarding on your router/firewall to forward all incoming UDP traffic within that range to the internal IP of your Asterisk server. **If your Asterisk server is behind NAT and you forget to do this, you'll experience one-way audio in your phone calls.** ```lisp ; /etc/asterisk/rtp.conf [general] rtpstart=20000 rtpend=20999 ``` ### SIP Trunks Next, we'll configure our SIP trunk(s). I'll be using `pjsip_wizard.conf`, since the PJSIP Wizard configuration style eliminates a ton of boilerplate. For this step, you'll need a server hostname and port, along with the username and password provided by your upstream SIP provider. ```lisp ; /etc/asterisk/pjsip_wizard.conf ; This template contains default settings for all SIP trunks. [trunk-defaults](!) type = wizard ; Require SIP authentication. sends_auth = yes ; Require SIP registration. sends_registrations = yes ; Send media to the address and port on the incoming packet, regardless of what ; the SIP headers say (NAT workaround). endpoint/rtp_symmetric = yes ; Rewrite the SIP contact to the address and port of the request (NAT workaround). endpoint/rewrite_contact = yes ; Send the Remote-Party-ID SIP header. Some providers need this. endpoint/send_rpid = yes ; Force the ulaw codec, which should work for everything in North America. endpoint/allow = !all,ulaw ; Call encryption is out of scope for this guide. endpoint/media_encryption = no ; If registration fails, keep trying ~forever. registration/max_retries = 4294967295 ; Don't assume an authentication failure is permanent. registration/auth_rejection_permanent = no ; Perform a connectivity check every 30 seconds. aor/qualify_frequency = 30 ; Your SIP trunks go here. For this example, we'll assume you're using VOIP.ms. ; You can pick whatever section name you like, as long as its unique. [voipms](trunk-defaults) ; You almost certainly want to use TCP. transport = transport-tcp ; Hostname and port for your SIP provider. remote_hosts = atlanta2.voip.ms:5060 ; Choose a context name for incoming calls from this account. You'll use this ; name in your dialplan. endpoint/context = from-pstn ; Your SIP provider will give you these credentials. outbound_auth/username = 555555 outbound_auth/password = s3cret ``` ### Local SIP Extensions In the same file, we'll also configure our local extensions. You'll need an extension for each VoIP handset or softphone within your network. I'll be using a prefix of `6XXX` for local extensions, but feel free to use whatever convention you prefer. The following example has three extensions: two dedicated VoIP handsets, and one Android softphone. Note that if you want to use a softphone outside of your local network, you'll need to either open your Asterisk instance to the world (not recommended, unless you know what you're doing) or set up some kind of VPN. ```lisp ; /etc/asterisk/pjsip_wizard.conf ; This template contains default settings for all local extensions. [extension-defaults](!) type = wizard ; Require clients to register. accepts_registrations = yes ; Require clients to authenticate. accepts_auth = yes ; When simultaneous logins from the same account exceed max_contacts, disconnect ; the oldest session. aor/remove_existing = yes ; For internal phones, allow the higher quality g722 codec in addition to ulaw. endpoint/allow = !all,g722,ulaw ; Context name for BLF/presence subscriptions. This can be any string of your ; choosing, but I'm using "subscribe". We'll use this in the dialplan later. endpoint/subscribe_context = subscribe ;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; Extension 6001 - VoIP phone ;;;;;;;;;;;;;;;;;;;;;;;;;;;;; [6001](extension-defaults) ; Dialplan context name for calls originating from this account. endpoint/context = from-home ; Voicemail address (note: I'm using the same voicemail address for all extensions) endpoint/mailboxes = 6000@default ; Internal Caller ID string for this device. endpoint/callerid = Living Room <6001> ; Username for SIP account. By convention, this should be the extension number. inbound_auth/username = 6001 ; Password for SIP account (you can choose whatever password you like). inbound_auth/password = s3cret ; Maximum number of simultaneous logins for this account. aor/max_contacts = 1 ; Check connectivity every 30 seconds. aor/qualify_frequency = 30 ; Set connectivity check timeout to 3 seconds. aor/qualify_timeout = 3.0 ; IMPORTANT! This setting determines whether the audio stream will be proxied ; through the Asterisk server. ; ; If this device is directly reachable by the internet (either by a publicly ; routable IP, or static port mappings on your router), choose YES. ; ; Otherwise, if this device is hidden behind NAT, choose NO. endpoint/direct_media = yes ;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; Extension 6002 - VoIP phone ;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; (Same settings as above, except for the extension number and password.) [6002](extension-defaults) endpoint/context = from-home endpoint/mailboxes = 6000@default endpoint/callerid = Kitchen <6002> inbound_auth/username = 6002 inbound_auth/password = s3cret2 aor/max_contacts = 1 aor/qualify_frequency = 30 aor/qualify_timeout = 3.0 endpoint/direct_media = yes ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ; Extension 6003 - Linphone app on Android device ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; [6003](extension-defaults) endpoint/context = from-home endpoint/mailboxes = 6000@default endpoint/callerid = Smartphone <6003> inbound_auth/username = 6003 inbound_auth/password = s3cret3 aor/max_contacts = 1 endpoint/direct_media = no ; For mobile devices, connectivity checks should be disabled. ; Two reasons for this: ; 1. Poor cellular signal often causes the connectivity check to time out, ; even when nothing is actually wrong. ; 2. Frequent traffic on the TCP session causes constant wakeups and kills ; battery life. aor/qualify_frequency = 0 ``` ### Voicemail Voicemail recordings are stored on the local filesystem of the Asterisk server. You can access them by dialing a special voicemail extension from a local phone (configured in your dialplan). In addition, if you have a local [MTA](https://en.wikipedia.org/wiki/Message_transfer_agent "Mail Transfer Agent") running, Asterisk can dispatch an email to an address of your choice whenever new voicemails arrive. In the previous section, we referenced a voicemail address called `6000@default` for our internal extensions. We'll create the actual voicemail box in `voicemail.conf`. ```lisp ; /etc/asterisk/voicemail.conf ; This section contains global voicemail options. [general] ; Audio formats to store voicemail files. format=wav49|gsm|wav ; "From:" address used for sending voicemail emails. serveremail=asterisk-noreply@example.com ; Whether to attach the voicemail audio file to notification emails. attach=yes ; Maximum number of messages per mailbox. maxmsg=100 ; Maximum length of a voicemail message in seconds. maxsecs=300 ; Maximum length of a voicemail greeting in seconds. maxgreet=60 ; How many milliseconds to skip forward/back when rew/ff in message playback. skipms=3000 ; How many seconds of silence before we end the recording. maxsilence=10 ; Silence threshold (what we consider silence: the lower, the more sensitive). silencethreshold=128 ; Maximum number of failed login attempts. maxlogins=3 ; Email template for voicemail notifications. emailsubject=New voicemail ${VM_MSGNUM} in mailbox ${VM_MAILBOX} emailbody=Hi ${VM_NAME},\n\nYou have a new voicemail in mailbox ${VM_MAILBOX}.\n\nFrom: ${VM_CALLERID}\nDate: ${VM_DATE}\nDuration: ${VM_DUR}\nMessage Number: ${VM_MSGNUM} emaildateformat=%A, %B %d, %Y at %r ; Default timezone for mailboxes (defined in zonemessages section below). tz=myzone ; Locale for generating date/time strings. locale=en_US.UTF-8 ; Minimum voicemail password length. minpassword=4 ; Custom timezone definitions go in this section. [zonemessages] myzone=America/New_York|'vm-received' Q 'digits/at' IMp ;;;;;;;;;;;;;;;;; ; Voicemail Boxes ;;;;;;;;;;;;;;;;; ; Each of the following sections describe a voicemail "context," which is a ; a collection of voicemail boxes. If you don't need multiple contexts, you ; can specify "default". ; ; The format is as follows: ; VOICEMAIL_NUMBER => INITIAL_PASSWORD,REAL_NAME,EMAIL_ADDRESS,,, ; ; The last three fields aren't relevant for simple configurations. [default] 6000 => 1234,John Doe,johndoe@example.com,,, ``` ### Queues When someone calls our phone number, we'd like all our phones to ring simultaneously (similar to a traditional landline phone). We can emulate this behavior in Asterisk using a `ringall` queue. Queues are configured in `queues.conf`. ```lisp ; /etc/asterisk/queues.conf ; Global queue settings go in this section. [general] ; Persist dynamic member lists in the astdb. persistentmembers = yes ; Some options for more intuitive queue behavior. autofill = yes monitor-type = MixMonitor shared_lastcall = yes log_membername_as_agent = yes ;;;;;;;;;;;;;;;;;;; ; Queue Definitions ;;;;;;;;;;;;;;;;;;; ; The "home-phones" queue is for incoming calls to our home phone line. [home-phones] ; For each incoming call, ring all members of the queue. strategy = ringall ; Max number of seconds a caller waits in the queue. timeout = 30 ; Don't announce estimated hold time, etc. announce-frequency = 0 announce-holdtime = no announce-position = no periodic-announce-frequency = 0 ; Allow ringing even when no queue members are present. joinempty = yes leavewhenempty = no ; Ring member phones even when they are on another call. ringinuse = yes ; Queue Members ; ; Each member is specified with the following format: ; member => INTERFACE,PENALTY,FRIENDLY_NAME,PRESENCE_INTERFACE ; ; The "penalty" value is not interesting for our use case. ; With PJSIP, the BLF/Presence interface is identical to the standard interface name. member => PJSIP/6001,0,Living Room,PJSIP/6001 member => PJSIP/6002,0,Kitchen,PJSIP/6002 member => PJSIP/6003,0,Smartphone,PJSIP/6003 ``` ### The Dialplan At this point, we've configured our upstream SIP trunks, created SIP accounts for some local phone extensions, and even defined a queue for incoming calls. All that's left is to glue all this together in a [dialplan](https://wiki.asterisk.org/wiki/display/AST/Dialplan)! The dialplan is configured in `extensions.conf`, and it's definitely the least intuitive aspect of Asterisk. You'll most likely find its syntax to be confusing at first glance. The thing to remember is that in the dialplan, everything is an _application_. Hanging up is performed by the `Hangup()` application, and voicemail prompts are handled by the `Voicemail()` application. Dialing a phone number is handled by (you guessed it) the `Dial()` application. Each application can take one or more comma-separated arguments. Now, for the syntax. Each dialplan context is marked by square brackets. Each line within the context is (confusingly) called an _extension_, and has the following format: ```lisp [context-name] exten => NAME,PRIORITY,APPLICATION() exten => NAME,PRIORITY,APPLICATION() ; etc... ``` The _name_ is the number (or pattern) of the extension. The _priority_ defines the order in which the step should be executed. Finally, the _application_ performs some action on the call. A simple context definition might look something like this: ```lisp [from-home] ; ${EXTEN} is a macro which expands to the currently dialed number. exten => _6XXX,1,Dial(PJSIP/${EXTEN}) exten => _6XXX,2,Hangup() ``` This dialplan section allows internal phones to call each other. The `_6XXX` is an extension pattern. When a device in the `from-home` context dials a 4-digit extension beginning with `6`, Asterisk will ring the corresponding PJSIP account. Because it gets tedious repeating the same extension name over and over, Asterisk provides some syntactic sugar. The exact same dialplan could also be written as the following: ```lisp [from-home] exten => _6XXX,1,Dial(PJSIP/${EXTEN}) same => n,Hangup() ``` Below, I've provided a complete Asterisk dialplan for our example VoIP network. It supports the following features: 1. Internal phones can dial each other via their 4-digit extension. 2. Internal phones can dial out to the PSTN via standard 10-digit numbers. 3. Internal phones can access the voicemail menu by dialing `*99`. 4. Internal phones can show BLF/line status for all other phones. 5. Incoming calls from the PSTN will ring all internal phones simultaneously. Callers will be sent to voicemail if no one answers within 25 seconds. 6. If your phones support the "auto answer" header, you can initiate a whole-house intercom by dialing `6000`. I'll provide plenty of comments to help you understand the arcane syntax. Hopefully it will be enough to bootstrap your own dialplan! ```lisp ; /etc/asterisk/extensions.conf ; Remember, context names for each SIP account are specified in pjsip_wizard.conf. ; First, some safeguards against abuse of the built-in contexts. [public] exten => _X.,1,Hangup(3) [default] exten => _X.,1,Hangup(3) ; Next, some global variables. You'll need to change some of these. [globals] ; Your local area code. MY_AREA_CODE = 555 ; Your real name and public phone number. This will be used for outgoing calls ; to the PSTN. MY_CALLER_ID = John Doe <+5555555555> ; Dial this number from a local phone to access the voicemail menu. VOICEMAIL_NUMBER = *99 ; Voicemail address (configured in voicemail.conf) VOICEMAIL_BOX = 6000@default ; Ring for this many seconds before forwarding the caller to voicemail. VOICEMAIL_RING_TIMEOUT = 25 ; Name of the 'ringall' queue for local phones. HOME_QUEUE = home-phones ; Number to dial for local intercom. INTERCOM = 6000 ; Dial pattern for local extensions. LOCAL_EXTS = _6XXX ; Boilerplate to enable BLF/presence subscriptions. Note that the context name ; corresponds to the "endpoint/subscribe_context" value in pjsip_wizard.conf. [subscribe] exten => _XXXX,hint,PJSIP/${EXTEN} ; This context handles incoming calls from our SIP trunk provider. Each call is ; is placed into a ringall queue. If there is no answer, the caller is forwarded ; to voicemail. [from-pstn] exten => _X.,1,Queue(${HOME_QUEUE},nr,,,${VOICEMAIL_RING_TIMEOUT}) same => n,Answer(500) same => n,Voicemail(${VOICEMAIL_BOX},su) same => n,Hangup() ; This is a function (or "gosub" in Asterisk lingo) that sets the "auto answer" ; SIP header on an outgoing call. [gosub-intercom] exten => s,1,Set(PJSIP_HEADER(add,Alert-Info)=auto answer) same => n,Return() ; This context handles incoming calls from local phones. [from-home] ; When the INTERCOM number is dialed, page all members of the "home-phones" queue ; into a conference call. exten => ${INTERCOM},1,Set(CALLERID(all)=Intercom <${EXTEN}> same => n,Page(${STRREPLACE(QUEUE_MEMBER_LIST(${HOME_QUEUE}),",","&")},db(gosub-intercom^s^1),10) same => n,Hangup() ; For local-to-local calls, ring indefinitely. exten => ${LOCAL_EXTS},1,Dial(PJSIP/${EXTEN}) same => n,Hangup() ; When the voicemail number is dialed, dump the caller into the voicemail menu. exten => ${VOICEMAIL_NUMBER},1,Answer(500) same => n,VoiceMailMain(${VOICEMAIL_BOX},s) same => n,Hangup() ; The following extensions are used to dial out to the PSTN via our SIP trunk, ; using a personalized caller ID string. ; ; Recall that we named our SIP trunk "voipms" in pjsip_wizard.conf. ; ; N matches any digit 2-9 ; X matches any digit 1-9 ; For numbers formatted as +1xxxxxxxxxx, dial as-is. exten => _+1NXXNXXXXXX,1,Set(CALLERID(all)=${MY_CALLER_ID}) same => n,Dial(PJSIP/${EXTEN}@voipms) same => n,Hangup() ; For numbers like 1xxxxxxxxxx, add a leading "+". exten => _1NXXNXXXXXX,1,Set(CALLERID(all)=${MY_CALLER_ID}) same => n,Dial(PJSIP/+${EXTEN}@voipms) same => n,Hangup() ; For numbers without a country code, add a "+1". exten => _NXXNXXXXXX,1,Set(CALLERID(all)=${MY_CALLER_ID}) same => n,Dial(PJSIP/+1${EXTEN}@voipms) same => n,Hangup() ; For 7-digit numbers, add the local area code. exten => _NXXXXXX,1,Set(CALLERID(all)=${MY_CALLER_ID}) same => n,Dial(PJSIP/+1${MY_AREA_CODE}${EXTEN}@voipms) same => n,Hangup() ; For 3-digit numbers, like 311, 411, 911 (UNTESTED!!!), dial as-is. exten => _N11,1,Set(CALLERID(all)=${MY_CALLER_ID}) same => n,Dial(PJSIP/${EXTEN}@voipms) same => n,Hangup() ``` ### Troubleshooting Once you've got all your configs in place, give Asterisk a kick: ```bash systemctl restart asterisk ``` On RedHat-based distributions, you can check `/var/log/asterisk/messages` for errors. You can also check the systemd journal: ```bash journalctl -u asterisk ``` You can also get lots of real-time information from the Asterisk console. To try it out, run the following command as root: ```bash asterisk -rvvvvv ``` If you're experiencing connectivity issues with your voice calls, you can enable SIP debugging in the console using the following command: ```default pjsip set logger on ``` ## Step 4: Configure your IP Phones The final step is to configure your VoIP phones to connect to your Asterisk server, and make a few test calls! The instructions here are for Yealink phones, but they should easily translate to other manufacturers. ### SIP Account Navigate to the IP address of the VoIP phone in your web browser, and log in with the default username and password (usually `admin/admin`). From here, you should be able to add a SIP account. In the Yealink interface, this is found under _Account→Register_. For the "Living Room" extension we created above, you would set the following: - **Register Name:** 6001 - **Username:** 6001 - **Password**: s3cret - **Server Host:** _IP/hostname of your Asterisk server_ - **Server Port:** 5060 - **Transport:** UDP ### Codecs You should also make sure the appropriate codecs are enabled on the device. In the Yealink web interface, you'll find them under _Account→Codec_. I recommend enabling these codecs in the following priority: 1. **G722**, for high-quality local calls 2. **PCMU** (_ulaw_), for dialing out to the PSTN Asterisk will automatically transcode G722 down to _ulaw_ if the other side doesn't support it. You can mess around with even higher quality codecs like Opus, but in my experience they are not well supported nor easy to transcode. ### RTP Port Range To reduce load on the Asterisk server, you may want your VoIP phone to send and receive audio streams directly to and from the other party. To do this, you'll need to configure your router/firewall to forward all incoming RTP traffic for the device. First, give the device a static IP on your local network. Then, configure your router to port-forward all UDP traffic on your chosen RTP port range to that IP. In the Yealink web interface, you can configure a static RTP port range under _Network→Advanced→Local RTP Port_. If you _don't_ do all this, then make sure `endpoint/direct_media` is set to `no` for the SIP account in `pjsip_wizard.conf`! ### Voicemail Number You'll also want to configure which number the phone should dial when you press the voicemail button. In the Yealink web interface, set _Account→Advanced→Voice Mail_ to `*99` (or whatever you number you chose for `VOICEMAIL_NUMBER` above). ### Busy Lamp Field (BLF) You may want to have your phone's LED light up when a given line is on a call. In the Yealink web interface, you can configure this under _Dsskey→Line Key_. For each line you're interested in, set **Type** to _BLF_ and **Value** to the other party's extension number. ### Intercom For the intercom functionality described in the dialplan above, make sure the phone is configured to allow auto-answer. In the Yealink web interface, you can configure this by setting _Features→Intercom→Intercom Allow_ to _on_. ## VoIP on Android: Linphone In the past, Android provided a built-in SIP client. Sadly, [as of Android 12](https://www.xda-developers.com/android-12-killing-native-sip-calling/), this has been removed. After trying all of the SIP apps available in F-Droid, I'm only able to recommend [Linphone](https://f-droid.org/en/packages/org.linphone/). It works with bluetooth devices, has an intuitive interface, and reliably delivers calls. To keep Android from killing the app, you'll need to make sure battery optimizations are disabled. Go to _Settings→Apps→See All Apps→Linphone→App Battery Usage_ and select _Unrestricted_. When configuring the SIP account in Linphone, use the following settings: - **Username:** 6003 _(or your chosen mobile extension)_ - **Password:** _your chosen SIP account password_ - **Domain:** _IP/hostname of your Asterisk server_ - **Transport:** TCP - **Expire:** 3600 - **Apply prefix for outgoing calls:** _enabled_ You'll definitely want to use the TCP transport for a mobile device. Smartphone radios are exceedingly efficient at keeping a long-running TCP connection open, and TCP will reliably deliver your SIP packets even with a poor cellular signal. With _Expire_ set to 3600, your phone will wake up every hour to re-establish the SIP connection. I've never had any connectivity issues with the TCP transport, but if you're paranoid, you might want to set this to a lower value. I've also found the following Linphone settings useful: - **Settings→Audio→Echo cancellation:** _disabled_ (most phones have hardware-level echo cancellation) - **Settings→Audio→Adaptive rate control:** _enabled_ - **Settings→Audio→Codec bitrate limit:** 128 kbits/s - **Settings→Audio→Codecs:** _enable PCMU and G722_ - **Settings→Call→Improve interactions with bluetooth devices:** _enabled_ - **Settings→Call→Voice mail URI:** \*99 - **Settings→Advanced→Start at boot time:** _enabled_ You may be tempted to hide the persistent notification icon while Linphone is running. Don't do it! Whenever I've tried to hide this icon, I get tons of missed calls, and Asterisk reports the device as offline for minutes at a time. As long I keep the icon visible in the notification area, I don't have any issues. ## Closing Thoughts For the past few months, I've used this exact setup for my primary phone number, and I've been pleased with the results. If you decide to self-host your own VoIP infrastructure, you'll definitely want to configure some type of QoS on your router or firewall to prioritize voice traffic. Otherwise, you'll experience lags and poor audio quality whenever your network is congested. In addition, you may want to investigate encrypting your calls via STRP and SIP TLS. I don't personally do this, because voice calls are totally in the clear as soon as you connect to the PSTN anyway. If you'd like to check out the configs required for encrypting your calls, or if you just want to get some ideas for automating your Asterisk configuration, check out my Ansible role on [GitHub](https://github.com/sacredheartsc/selfhosted/tree/master/roles/asterisk).