initial commit

1 files changed, 991 insertions, 0 deletions

diff --git a/src/blog/building-a-personal-voip-system/index.md b/src/blog/building-a-personal-voip-system/index.md
new file mode 100644
index 0000000..4d32748
--- /dev/null
+++ b/src/blog/building-a-personal-voip-system/index.md
@@ -0,0 +1,991 @@
+---
+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.<br>
+> I would like to place an audio call using the G.711 codec.<br>
+> Please send your audio frames to me at address 192.168.1.5, port 20000.
+
+> Hi there, 192.168.1.5!<br>
+> Sure, I support the G.711 codec.<br>
+> 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?<br>
+> I would like to place an audio call using the G.711 codec.<br>
+> 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!<br>
+> Sure, I support the G.711 codec.<br>
+> 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.
+  <br>
+  [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).