Introduction

Just like with self managed mail; this will be high maintenance, low reward, and is a very bad idea - like anything worth doing. This guide provides detailed instructions on setting up a FreePBX system with UniTel SIP Trunking.

Why Customize Your Phone System?

CallerID hacks to make calls go faster

One of the fun things you can do with this setup is integrate it with your customer relationship management software like I did with repairshopr. So, instead of the usual caller ID, you can have the status of a customer’s ticket show up. Back when I was the only one doing repairs at my store, this was a lifesaver. Most calls were simple status checks, and I could handle them while soldering, thanks to a Bluetooth headset.

Caller ID Customization: Instead of just a name, I saw ticket status in the caller ID too!
Efficiency: I could handle calls without stopping my work!
Customer Satisfaction: Instant info made customers feel like you know them better than they know themselves.

Automatically send mean customers to an extension where Allison Smith tells them to go fuck themselves :D

Rossmann Repair has never made use of this feature.

Make telemarketers miserable by installing a program that messes with them: Lenny

The customization possibilities are endless, and that’s what makes this so much fun. Now, let’s get into how to build your own system.

Step 1: Preparing a FreePBX installation

Step 1: Set up a FreePBX virtual machine

1.1 Download Debian 12 ISO

You used to download FreePBX as its own distro, which was based on CentOS. They switched to Debian after some recent CentOS/Red Hat controversy.

Open a terminal window or use a web browser within your happycloud server that is running Virtual Machine Manager to host all of your virtual machines. In our case, that’s 192.168.5.2.

Download and install Debian 12 on the machine designated for FreePBX.

wget https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/debian-12.0.0-amd64-netinst.iso -P ~/Downloads

Make sure the download completes successfully.

1.2 Move the Debian ISO to the Correct Directory

Move the downloaded ISO to /var/lib/libvirt/images:

sudo mv ~/Downloads/debian-12.0.0-amd64-netinst.iso /var/lib/libvirt/images/

Set the correct permissions and ownership for the ISO:

sudo chmod 644 /var/lib/libvirt/images/debian-12.0.0-amd64-netinst.iso
sudo chown libvirt-qemu:kvm /var/lib/libvirt/images/debian-12.0.0-amd64-netinst.iso

1.3: Launch Virtual Machine Manager

Open Virtual Machine Manager from the Openbox menu by right-clicking the desktop, going to system, and then running virtual machine manager. Or run:

virt-manager

1.4 Create a New Virtual Machine

Click Create a new virtual machine.
Select Local install media (ISO image or CDROM) and click Forward.
Click Browse… and navigate to /var/lib/libvirt/images/ to select debian-12.0.0-amd64-netinst.iso.
Choose Detect automatically for the OS type or manually set it as Debian 12.
Click Forward.

1.5: Configure VM Resources

Memory & CPU:
- Assign 4096 MB of RAM (or more, but the idea of giving more than 4 gigs to a phone system hurts me).
- Assign 2 CPUs (adjust based on available resources).
Storage:
- Select Create a disk image for the virtual machine.
Allocate at least 20 GB for storage. Choose more if you expect larger usage.
Click Forward.

1.6 Set Up Networking

Make sure the network selection is set to Bridge and matches your LAN network (e.g., br0). This will allow your VM to get a static IP from your existing network. Under Network settings, make sure it’s set to Bridge mode for proper network integration.

1.7 Set up FreePBX to start on boot

virsh autostart freepbx

Check that this is set up properly by typing virsh dominfo freepbx and seeing if the autostart line is set to enable.
If you don’t do this, you will realize once it is too late and you’ve left your house after you have rebooted your server (for whatever reason) that your phone system is dead. Don’t do that.

1.8 Debian 12 Installation Setup

Follow the Debian installer prompts:
- Language: Choose your preferred language.
- Location: Set your country.
- Keyboard: Select your preferred layout.
- Hostname: Set the hostname as freepbx.
Domain Name:
- You can leave this blank.
Set the Root Password:
- Choose a secure password and confirm it.
Create a New User:
- Add a user. I added a user named louis for myself.
Partitioning:
- Choose “Guided - use entire disk and set up LVM”.
- DO NOT USE ENCRYPTION - REMEMBER, THE HOST SYSTEM THIS IMAGE IS ON IS ALREADY AN ENCRYPTED DISK!!
- Select the disk and proceed.
- Confirm changes to write the partitions.
- The disk device will most likely be something like /dev/vda.

1.9 Post-Installation Configuration Test

After rebooting, log in as root or your user.

Make sure network connectivity works:

ping 8.8.8.8
hostnamectl

Step 2: Preparing Debian 12 for FreePBX Installation

This guide provides instructions on performing basic maintenance on a fresh Debian 12 installation and then downloading and running the FreePBX installation script. Follow the steps carefully to ensure a smooth setup.

2.1 Configure Network Settings

Log in with your username and password on the virt-manager screen on your host computer (the one hosting all the virtual machines).
Type ip addr show and find which interface shows your IP address.
- Remember its name for later.
- It should be something like enp1s0.
Become root:

su

Make a network configuration file like this:

Use the name of your network interface in place of enp1s0.

nano -w /etc/systemd/network/enp1s0.network

[Match]
Name=enp1s0 #put name of your network interface in place of enp1s0

[Network]
Address=192.168.5.6/24
Gateway=192.168.5.1
DNS=192.168.5.1

Hit ctrl-x, then y to save.

systemctl restart systemd-networkd

Make sure your IP address has changed to a static IP by typing ip addr show and checking.
- Static IP: Set the IP address to 192.168.5.6.
- Gateway: Use 192.168.5.1.
- DNS Server: Set to 192.168.5.1.

2.2 Do Basic Maintenance on Debian 12

Update Package Lists
- Refresh the package lists to make sure you get the latest versions
- Upgrade packages
- Remove junk, all with the following line:
```
sudo apt update ; sudo apt upgrade -y ; sudo apt autoremove -y
```

2.3 Download & run FreePBX install script

ssh to the Debian system as louis
Check FreePBX page for the latest script since the URL will change over time.

Download the file using wget:

su
wget https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh -O /tmp/sng_freepbx_debian_install.sh

Make the script executable

   su # become root user
   chmod +x /tmp/sng_freepbx_debian_install.sh

Run the FreePBX Installation Script
```
bash /tmp/sng_freepbx_debian_install.sh
```
- The script will handle the setup of Asterisk, Apache, MySQL, Postfix, etc., all necessary FreePBX modules.

Step 3: Visit FreePBX Web Interface

Open a Web Browser
- Use a browser on a device connected to the same network, or a device that is connected via OpenVPN. Remember, none of this is open to the public!
Navigate to the FreePBX IP
- Access FreePBX by entering the following URL: http://192.168.5.6/admin
- If you used a different IP configuration than I did, enter that IP.
Answer prompts for user/password
- Follow the setup wizard to configure your admin user, language settings, & other preferences. But don’t get started messing around with anything serious just yet.

Step 3: Configuring UniTel as Phone Service Provider

Now that we have a working FreePBX installation, we’re ready to set things up with an SIP trunk provider, aka “the phone company”. I use UniTel for this at the UniTel Customer Portal at unitelcustomer.com.

Setting up SIP trunking

A SIP trunk account is like your phone’s connection to the outside world. Think of it as paying for internet but for your phone calls. Without it, your PBX system is just an intercom for internal calls. You need a SIP trunk to make and receive calls from the outside world.

Choosing an SIP Trunk Provider

I recommend Unitel for SIP trunking. They’re solid, reliable, and unlike some other providers, they don’t just resell AWS in the cheapest way possible. I used to use VoicePulse, but they were terrible and went out of business a few years ago. They had no redundancy, so if some single AWS instance went down, you were out of luck.

John Grossbard: Studio Landlord & Seinfeld Character

There was an episode of Seinfeld where he said “I GOT GROSSBAR’D!” Supposedly this was a reference to a minor argument between him and Larry David.

John Grossbard was the owner of Planet to Planet Studios when I rented a space from him for my screen wholesaling company in the basement of 251 W. 30th St in NYC, back when this was called the “Music Building,” before it was remodeled to appeal to hipster-0%-interest-rate-funded-fad-yuppie-startups.

I was here because I had no credit and he didn’t ask for a security deposit. When a friend of mine brought up an issue of bedbugs, he looked at us and said “If I made this place any nicer, you couldn’t afford it.”

He wasn’t wrong. This stuck with me my entire adult life.

Unitel has two websites. One is their main website, and one is a website that looks like some 1997 Slashdot site. The website with the 1997 Slashdot look is what we want. It’s not too nice – that means we can “afford” it.

The Benefits of Your Own PBX; Revisited

In all seriousness, one of the benefits of hosting our own PBX is that we DON’T pay by the user. We DON’T pay by the feature. All we pay for is SIP trunking—any features & functionality are added by US, to OUR PBX, that we control.

We don’t need them to make it any nicer. If they did, you couldn’t afford it.

HINT: Avoid the fancy, infinite-scrolly websites like UnitelPhone.com. Instead, go for the classic UnitelCustomer.com. If it looks like it’s from 1997, you’re in the right place! It’s straightforward and gets the job done.

Having your own PBX means no more paying per user. You pay based on trunk usage, not the number of users. Some providers nickel and dime you on the number of extensions you have, visual voicemail, call recording, etc. With SIP trunking, they have no idea what is going on, so they can’t bill you by-the-extension or by-the-feature. It’s like a VPN for your calls—they don’t know how many extensions you have or if you’re recording calls. All they know is the call came in or went out. No extra charges for features like visual voicemail, lenny, call recording, or the voice of Allison Smith telling callers to go fuck themselves; which is the reason I set this up to begin with 14 years ago. :D

3.1 Register for a Unitel Account

Open a web browser and navigate to: https://signup.unitelgroup.com/sip-trunking-plans
Create an account with the nice SIP trunking people

3.2 Set Up an Endpoint (This is Where Inbound Calls Get Sent To)

Endpoints are where your call is sent when a call comes in on a number you have in Unitel. When you create a phone number in Unitel, it will ask where you want to send calls that come into that number. We’re going to set up the endpoint first so when we create a number, we’ll already have an endpoint to send it to.

Navigate to the “Endpoints” Section

From the main dashboard, go to “Settings”.
Click on “Endpoints”.
Create a New Endpoint
Click on “Add Endpoint”.
- Fill in the following details:
  - Endpoint Description: Enter a name that describes the endpoint (e.g., closet pbx).
  - Endpoint Destination: Insert the dynamic DNS entry (e.g.louishomeserver.chickenkiller.com) that you set up back in the FreeDNS Dynamic DNS section of this guide. This should resolve to your PBX’s external IP address. When a call comes in on a specific number, it is going to send the call to your PBX at this IP.
Click “Add Endpoint” to complete the setup.

3.3 Get & Configure Phone Numbers

Navigate to the “Numbers” Section
- From the main dashboard, after clicking on “Numbers”, click on “Add Number”.
- Buy a number.
Assign the Purchased Number to the Endpoint
- After purchasing, go to “Manage Numbers”.
- Find the purchased number and click the dropdown under “Actions” and click “Number Mode”.
- Select “Forward to Endpoint”: Select the endpoint you created earlier (e.g., closet pbx).
- Click Update.

3.4 Add a Trunk in Unitel

Purpose of an SIP trunk:

An SIP trunk is what attaches you to the world, similar to how your cable modem & spectrum or verizon connects you to the rest of the internet. A trunk is a connection between your phone system (PBX) and the external phone network. It allows your system to make and receive calls to/from the outside world. Setting up a trunk in Unitel is necessary.

The purpose of the trunk is to provide a pathway for your PBX to route calls to and from the public telephone network. Without a properly configured trunk, your system won’t be able to communicate with external phone numbers. Which is what I have been doing for three weeks while writing this guide.

Log in to the Unitel Admin Interface
- Open your web browser and go to the Unitel admin interface.
- Log in using your credentials.
Step 2: Add a New Trunk
- Navigate to Manage SIP Trunks.
- Click on Add Trunk.
Step 3: Configure Trunk Details
- Trunk Description: Enter a descriptive name for your trunk (e.g., Main Trunk).
- Trunk Type: Select General use/Conversational.
Click Add Trunk to save the new trunk.
Click Apply Config to activate the trunk.
NOTE YOUR CREDENTIALS!
- During the trunk setup, you will be provided with a username and password. Be sure to note your username & password in a password manager of some sort as it will be needed later when configuring the trunk in your PBX system.

Step 4: Setting up FreePBX with Unitel phone service

Now that your phone service provider is set up, we can configure freepbx to connect to it & receive & send phone calls. We’ll be using UniTel credentials to sign into our trunk.

Get into FreePBX interface:

Open a web browser and navigate to:

http://freepbx.home.arpa/ or http://192.168.5.5/
Log in

4.1 Add a New SIP Trunk

Navigate to the Trunk Configuration
Go to Connectivity > Trunks.
Click Add Trunk and choose Add SIP (chan_pjsip) Trunk.
Configure the General Settings
- Trunk Name: Enter a happy name, like UniTel_SIP.
- Hide CallerID: Set to No.
- Outbound CallerID: Enter your UniTel DID (your phone number) in e.164 format (e.g., 13475522258 for rossmann repair group).
- CID Options: Choose Allow Any CID.
- Dial Number Manipulation Rules
- Outbound Dial Prefix: Make sure all outgoing calls use the 11-digit e.164 format (e.g., 1NXXNXXXXXX).
- Add a rule if needed to prepend 1 for local or long-distance numbers:
  - Match Pattern: NXXNXXXXXX
  - Prepend: 1

4.2 PJSIP Settings Configuration in trunk configuration

Go to the “PJSIP Settings” Tab
- Username: Enter the SIP username provided by UniTel.
- Secret: Enter the SIP password from UniTel.
- SIP Server (SIP Host): Set to sip.unitelgroup.com, this may change over time. Make sure you check Unitel’s instructions that they offer on unitelcustomer.com after you log in. They’re nice people & provide all this for you in plain English.
- Authentication: Set to Outbound, should be checked by default.
- Registration: Choose Send, should be checked by default.
Advanced Options
- From Domain: Enter sip.unitelgroup.com.
- Context: Use from-pstn-toheader (This allows FreePBX to correctly handle incoming SIP headers from UniTel). This should be set by default.
Go to “Codecs” tab
- Check the codecs that Unitel allows.

- - G723
  - G729
  - G711
    - G711 is actually ulaw and alaw in the list.
- This may change over time, check Unitel’s page for details.
- Unitel are nice people & want you to be successful in setting up your PBX. They provide you with all of this information.
Submit and Apply
- Click Submit.
- Click Apply Config on the top-right to save changes and reload the configuration.

Step 5: Internal Call Handling and Call Routing Setup

Now we start the process of setting up internal call handling by creating extensions and ring groups, as well as defining call routing to manage inbound and outbound calls using the UniTel SIP trunk in FreePBX 17. Having a trunk is useless if we don’t have any phones set up.

5.1 Create an Extension

Extensions are individual phones. Alice has an extension for a phone on her desk, Mark has an extension for a phone on his desk, and so on and so forth. Each extension has a number for internal calls. Your desk phone could be 101 - this means people inside FreePBX connected directly to your PBX can call 101. This needs to be done first.

Log in to the FreePBX Admin Interface
Navigate to Extensions
- Go to Connectivity > Extensions.
- Click Add Extension.
- Choose Add SIP (chan_pjsip) Extension.
Configure the Extension
- User Extension: Enter a unique extension number (e.g., 101).
- Display Name: Enter the name for this extension (e.g., Office Phone).
- Secret: Enter a strong password for the extension or let FreePBX generate one automatically. It’s a good idea to add this to your password manager like Bitwarden so you have it later. Don’t put this on a post-it note.
Voicemail: Enable if you want voicemail for this extension.
- Set email address to the email you want voicemail sent to.
- Set Voicemail password to the password you want to have to dial to access voicemail (we will never use this archaic method, we will get voicemails emailed to us).
In Advanced you can set up call recording.
Submit and Apply Changes

5.2 Configure Ring Groups

When someone calls 3475522258 for my business, I don’t want one phone to ring. I want all of them to ring. This is what ring groups are for. We create one number that rings a bunch of different phones.

Go to Applications > Ring Groups.
Click “Add Ring Group”.
- Ring Group Number: Enter a unique number for the ring group (e.g., 600).
- Group Description: Enter a name for this ring group (e.g., Office Ring Group).
- Ring Strategy: Choose how calls should be distributed (e.g., Ringall to ring all devices simultaneously). Ringall is what you want 99% of the time. Use ringall if you are confused.
- Extension List: Add the extensions you want to include in this ring group (e.g., 101). Everyone here will have their phone ring when this ring group is called. In an office with one phone number, you would want to put every extension here of the people you want to pick up the phone when a customer calls.
Customize settings like Ring Time, Destination if No Answer, and Call Recording. I usually set this to the voicemail of a particular extension.
Click “Submit”.
Click “Apply Config” to activate the ring group.
REMEMBER, YOU NEED TO SET A DESTINATION IF NO ANSWER SO THAT PEOPLE CAN LEAVE VOICEMAILS.
- Mitt Romney famously said “ring groups are people, my friend.”
- They are not! People have voicemails – ring groups do not.

Step 6: Define Call Routing

Inbound routes define what we do when someone calls a particular phone number.

6.1 Set Up Call Flow Control

Call flow control allows you to change where calls go by dialing a number on your phone.

For instance, let’s say your business hours are 11 AM to 7 PM. You can set it up so that when you close, you dial *2886 on your phone to send the calls directly to voicemail. Then, when you open the next day, you dial *2886 again and your calls switch back to going to all of your business phones rather than go to voicemail.

I like this more than I like call scheduling because I set it manually. If I come to work early, I may want to answer the phone early. If I stay late, I may want to answer the phone late.

Rather than set up my phone number to go straight to my ring group, I set it up to go to call flow control. Then, I set up call flow control to go to my ring group, and my ring group to go to my extensions.

Navigate to Inbound Routes
Go to “Applications” > “Call Flow Control”.
Click “+ Add”.
Configure the Call Flow Control
- Call Flow Toggle Feature Code Index: This just means what number you enter into your phone to change it. Whatever you add here will be in front of a 28. So, if you enter 86, that means dialing *2886 on your phone will toggle where your calls go.
  - On older phones like the Cisco SPA525G, this doesn’t work since they seem to only support two digits in front of a * rather than four. :(
- Description: Describe what the point of this is so you know for later.
- Current Mode: This sets how calls are going when you initially finish setting this up.
- Normal Flow: This sets where calls go before you toggle call flow control. Put the default here. For me, that’s ringing all of my office phones at the Ring Group I set up earlier. Enter Ring Groups and then put the Ring Group you created here.
- Override Flow: This is where calls will go when you dial *2886 and toggle this feature on. Set this to Voicemail and then the voicemail of the extension we created.
- CallerID Number: Same as the DID number.
- Description: Provide a description for this route (e.g., Rossmann repair business number).
- Set Destination: Choose “Ring Groups” and select the ring group number you created earlier (e.g., 600 - Office Ring Group).
Submit and Apply Changes

6.2 Set Up an Inbound Route

Navigate to Inbound Routes
Go to “Connectivity” > “Inbound Routes”.
Click “+ Add Inbound Route”.
Configure the Inbound Route
- DID Number: Enter your UniTel DID in e.164 format (e.g., 13475522258). Put a 1 in front of your number in the US!
- CallerID Number: Same as the DID number.
- Description: Provide a description for this route (e.g., rossmann repair business number).
- Set Destination: Choose “Ring Groups” and select the ring group number you created earlier (e.g., 600 - Office Ring Group).
Submit and Apply Changes

6.3 Set Up CallerID

Navigate to CID Superfecta
- Go to “Admin” > “CID Superfecta”.
- Click Yes on the callerID sources you think would be useful.
Navigate to Inbound Routes
- Go to Connectivity > Inbound Routes.
- Go to the Other tab.
- Choose CID Lookup Source as CID Superfecta.
Submit and Apply Changes

6.4 Configure Outbound Route for Making Calls

Navigate to Outbound Routes
- Go to Connectivity > Outbound Routes.
- Click + Add Outbound Route.
Set Up the Outbound Route
- Route Name: Enter UniTel_Outbound.
- Route CID: Enter your UniTel DID (in e.164 format, e.g., 13475522258).
Assign Trunk to Route
- Trunk Sequence for Matched Routes: Select UniTel_SIP (the trunk created earlier). We don’t have multiple trunks.
Navigate to Dial Patterns
- Click Dial patterns wizards.
- Click the dial plans that make sense for your locale.
- This is a conversation for you to have with your SIP trunking provider based on your region. Open a ticket with them and make sure you choose the right options here!
Submit and Apply

Click Submit.
Click Apply Config to save and activate the outbound route.

Step 7: Configure IP subnets in FreePBX

FreePBX configures it to work automatically with the LAN subnet. For instance, if you chose 192.168.5.0/24 for your local network, it will configure FreePBX to work properly with your LAN subnet.

However, it doesn’t know you have a VPN. Remember that I suggest you not open ports. If you want this to work on your Android phone or iPhone when you connect to your home network, you have to add your VPN subnet manually. To do so, follow these instructions:

Add VPN subnet to local networks in FreePBX

Navigate to SIP Settings
Go to “Settings” > “Advanced SIP Settings”.
Make sure you are on the “General” tab.
Find the Local Networks section.
Log into the pfSense firewall in a new browser tab.
Go to “VPN” —> “OpenVPN” at the top menu.
Find the Tunnel Network for your VPN, which will be in the list of OpenVPN servers.
Return to the FreePBX browser tab and click Add Local Network Field.
Add the Tunnel Network of your VPN.
Submit and Apply Changes
- Click “Submit”.
- Click “Apply Config” to activate the outbound route.

Step 8: Setting up a softphone

A softphone is a software phone. I’ll show you how to use this; the instructions are about the same as configuring a hardware phone. It also allows me to create instructions that allow anyone watching this to confirm their system works without having to provide generalized instructions that aren’t precise to every single smartphone.

8.1 Download Zoiper

Go to Zoiper.
Download Zoiper here.
Install Zoiper.
Run Zoiper.

8.2 Get credentials for your extension.

Log in to the FreePBX Admin Interface
Navigate to Extensions
- Go to Connectivity > Extensions.
- Click your extension.
Get your extension number, which is your username, and your secret, which is your password.

8.3 Configure Zoiper

Open Zoiper and select Create New Account.
Enter the following details:
- Username: Your extension number (e.g., 401).
- Password: Your secret (password).
- Domain: Your server’s IP address or hostname (for us, 192.168.5.6:5060).
  - The format will be username@ip:port with the password in its own field.
  - In my setup with my example, it would be 401@192.168.5.6:5060 or 401@freepbx.home.arpa:5060.
- Skip Outbound Proxy.
- Select Transport Protocol SIP UDP.
- Choose SIP UDP as most setups use UDP by default.
Test Configuration:
- If you see a green checkmark, you did good.

8.4 Test Audio Settings

Go to options.
Select Input and Output Devices.
Set Input Device to your microphone.
Set Output Device to your speakers or headphones.
Test Audio: Speak into the microphone to check input levels. For output, press play to confirm audio works.

Step 9: Configuring Voicemail and Email Notifications in FreePBX 17

This guide provides step-by-step instructions to configure voicemail for an extension and ring group in FreePBX 17, making sure that voicemail messages are sent via email with audio file attachments. We will also set up your custom mail server for sending these email notification; we’re not calling into a voicemail system in 2024.

9.1 Enable Voicemail for the Extension

Log in to the FreePBX Admin Interface
- http://192.168.5.5/admin
- Log in with your admin credentials.
Navigate to Extensions
- Go to “Applications” > “Extensions”.
- Find and select the extension (e.g., 401) that you want to set up.
Enable Voicemail for the Extension
- Scroll down to the Voicemail section.
- Enable Voicemail: Set to Yes.
- Voicemail Password: Enter a numerical for accessing voicemail which we will never use.
- Email Address: Enter the email address where voicemail notifications should be sent (e.g., user@example.com).
- Attach Voicemail: Set to Yes (this will attach the audio file of the voicemail to the email notification).
- Delete Voicemail: Set to No (keeps a copy of the voicemail on the system even after sending the email). Until we know if our system works, keep this to no. Once it is emailing us our voicemails as a wav file, then we can change this to yes.
Submit and Apply Changes
- Click “Submit”.
- Click “Apply Config” to save the voicemail settings for the extension.

9.2 Configure Voicemail for the Ring Group

Navigate to Ring Groups
- Go to “Applications” > “Ring Groups”.
- Select the ring group you configured earlier (e.g., 600 - Office Ring Group).
Set Ring Group to Go to Voicemail
- Destination if No Answer: Choose “Voicemail”, and select the extension’s voicemail (e.g., 101).
Submit and Apply Changes
- Click “Submit”.

Step 9.3: Configure FreePBX to Send Email Notifications via Custom Mail Server

Navigate to System Admin Module
- Go to “Admin” > “System Admin”.
- Click on “Email Setup”…. GOTCHA!! This is GNU/Linux, nothing is easy. I had you for a moment there, didn’t I? :D
This is actually going to be a fun journey of configuring postfix manually. That is a long way away, at the end.

Step 10: Setting Up pfSense Firewall Rules for FreePBX with UniTel SIP Services

To make sure your FreePBX system (located at 192.168.5.6) is able to connect to UniTel’s SIP service and receive calls with two-way audio that actually work, we need to create NAT rules & corresponding firewall rules that only allow traffic from UniTel’s approved IPs. Next we’ll walk you through setting up aliases for UniTel’s IPs, creating NAT rules, & making sure SIP and RTP traffic flows correctly.

Create aliases for UniTel’s IPs

Step 10.1: Log in to Your pfSense Web Interface

Open a web browser and navigate to: https://pfsense.home.arpa or https://192.168.5.1
Enter your pfSense admin credentials.

Step 10.2: Add an Alias for UniTel’s SIP Signaling IPs

Go to Firewall > Aliases.
Click Add (+) to create a new alias.
Configure the alias as follows:
- Name: Unitel_SIP_IPs
- Description: SIP Signaling IPs from UniTel
- Type: Host(s)
- IP Addresses:

Add each of the following SIP IP addresses: THIS MAY CHANGE, CHECK UNITEL GETTING STARTED PAGE TO MAKE SURE THESE ARE THE RIGHT ONES!

- - 199.180.220.89
  - 199.180.220.91
  - 208.89.104.3
Click Save, then Apply Changes.

Step 10.3: Add an Alias for UniTel’s Media IPs

In the Aliases section, click Add again to create another alias.
Configure the alias as follows:
Name: Unitel_Media_IPs
Description: Media IPs for UniTel SIP Services
Type: Host(s)
IP Addresses: Add each of the following media IP addresses: THIS MAY CHANGE, CHECK UNITEL GETTING STARTED PAGE TO MAKE SURE THESE ARE THE RIGHT ONES!
- 199.180.223.109
- 45.55.33.77
- 157.230.238.197
- 45.33.70.196
- 45.33.71.83
- 159.65.107.252
- 45.33.14.21
- 159.89.122.218
- 167.71.237.189
- 172.104.226.108
- 139.162.250.71
Click Save, then Apply Changes.

Setting up NAT port forward & firewall rules

10.4 Configure NAT port forwards for FreePBX signalling

Navigate to Firewall > NAT.
Under the Port Forward tab, click Add to create a new NAT rule.
Configure the rule as follows:
- Interface: WAN
- Protocol: UDP
- Destination: WAN address
- Destination Port Range:
  - From: 5060
  - To: 5065 (for SIP signaling)
- Redirect Target IP: Enter your PBX IP: 192.168.5.6
- Redirect Target Port:
  - From: 5060
  - To: 5065
- Source: Select Single host or alias and choose Unitel_SIP_IPs.
- Description: Forward SIP Traffic from UniTel to FreePBX
Click Save, then Apply Changes.

10.5 Set Up NAT port forwards for RTP (Media) Traffic

In the Port Forward tab, click Add to create another NAT rule.
Configure the rule as follows:
- Interface: WAN
- Protocol: UDP
- Destination: WAN address
- Destination Port Range:
  - From: 10000
  - To: 20000 (for RTP media traffic)
Redirect Target IP: Enter your PBX IP: 192.168.5.6
Redirect Target Port:
- From: 10000
- To: 20000
Source: Select Single host or alias and choose Unitel_Media_IPs.
Description: Forward RTP Traffic from UniTel to FreePBX
- Click Save, then Apply Changes.

10.6 Verify Automatic Firewall Rules

After creating the NAT rules, go to Firewall > Rules.
In the WAN tab, confirm that the firewall rules were automatically created for:
1. SIP Traffic (ports 5060-5065) pointing to 192.168.5.6 and restricted to Unitel_SIP_IPs.
2. RTP Traffic (ports 10000-20000) pointing to 192.168.5.6 and restricted to Unitel_Media_IPs.

10.7 Test the Configuration

Make sure that your FreePBX system can register with UniTel’s SIP servers.
Make a test call to make sure both SIP signaling and media (audio) traffic are functioning correctly.
Make sure that when you end a phone call, both the caller & recipient notice that it has ended immediately.
Make sure you have two-way audio.
Leave a call on for fifteen minutes and make sure it doesn’t hang up by itself.

Step 11: Troubleshooting when it doesn’t work. It’s open source, so….

Introduction to Network Rules

We set up two sets of rules:

SIP Trunk rules (Ports 5060-5065)
- Allows Unitel to talk to our PBX
- Deals with signaling & connection management
Media Proxy Rules (Ports 10000-20000)
- Manages the actual audio transmission
- Handles voice data going back and forth

What are NAT port forwards vs Firewall Rules?

Network Address Translation (NAT) Port Forwards

NAT is like the restaurant host who brings guests to specific tables. It allows specific machines behind your network to get traffic depending on the port that the traffic was trying to access when the traffic got to your cable modem & firewall.

Firewall Rules

The firewall acts as a bouncer. Even when NAT directs traffic to the right computer, the firewall can still block problematic connections.

Order:

pfSense will add a firewall rule AUTOMATICALLY each time you create a NAT port forward, as long as you do not change that option at the end of the NAT port forward rule creation page. I circled this to make sure you would get it right.

Set up NAT rules first
Configure firewall rules second

Our Setup

FreePBX box IP address: 192.168.5.6

Internet Traffic → NAT (Traffic Direction) → Firewall (Security Check) → FreePBX virtual machine

When Things Don’t Work (Common Scenario)

This is an open source firewall combined with self-managed SIP trunking. If something works on the first go, you should be very concerned – this likely means you are in a coma & dreaming. Try to wake up. If you can’t, something is wrong.

IMPORTANT: Follow along in the video as this is best explained there as I go. This is one of the few sections where I believe the video is a must-have to understand how troubleshooting an issue here would work in real time.

When initial setup doesn’t work, follow this troubleshooting sequence:

Clear ARP Tables
- Navigate to Diagnostics → ARP Table → Clear
Reset States
- Navigate to Diagnostics → States → Reset States
- States are current connections
- Must be reset on both routers
- Wait 90 seconds after reset (best practice)
Reload Filter Rules
- Navigate to Status → Filter → then click ** Reload**

Using Packet Capture for Diagnostics

Go to: Diagnostics → Packet Capture
Configure capture:
- Interface: WAN or LAN depending on test
- Port: 5060, 5061, 5062, 5063, 5064, 5065 for SIP traffic

Reading Packet Capture Results

Example of captured traffic: 199.18.220.89 (Unitel’s IP in my case)
You’re looking to see if the port 5060 traffic is actually being directed to your PBX. You’re also looking to see if it is even coming in at all.

Stuff we use to troubleshoot:

When dealing with miserable issues:

Check Logs

Status → System Logs → Firewall → Normal View
- Sort by newest first
- Enable logging for allowed and blocked traffic
Use diagnosing tools
- Packet capture shows where things are going
- Firewall logs show what’s being blocked/allowed
- Side-by-side comparison of rules vs. actual traffic
Reset Everything
- Clear ARP tables
- Reset state tables
- Reload filter rules
- None of this will work because it’s open source, SO:
- Reboot the router
- Look for hints & clues.

Important takeaway from this

In the video, I did all of the above. The router magically started passing traffic after a reboot.
Even when everything is configured correctly, it may not work correctly – it’s open source.
Consumer routers vs Enterprise/Open Source firewalls:
- $20 consumer router: “It just works”
- Enterprise-grade open source firewall: Requires patience and systematic troubleshooting
It’s still better to use this than a traditional router so you don’t get hacked & owned via lack of updates.

Step 12: Install Lenny on FreePBX 17

12.1 Prepare to Access Your FreePBX System

You need to SSH into the FreePBX VM to install Lenny. Open a terminal on your local machine and connect via SSH:

ssh louis@192.168.5.6
su

12.2 Add Lenny’s Custom Context in Asterisk

Open the extensions_custom.conf file for editing:
```
nano /etc/asterisk/extensions_custom.conf
```
Add the following lines to define the Lenny context:

[Lenny]
exten => talk,1,Set(i=${IF($["0${i}"="016"]?7:$[0${i}+1])})
same => n,ExecIf($[${i}=1]?MixMonitor(${UNIQUEID}.wav))
same => n,Playback(Lenny/Lenny${i})
same => n,BackgroundDetect(Lenny/backgroundnoise,1500)

Save and exit the editor by pressing Ctrl + X, then Y, and Enter.

12.3 Download Lenny’s Sound Files

Continue with the necessary steps to download and configure Lenny’s sound files as required.

Lenny works by playing recorded audio. You’ll need to download these audio files to the correct directory on your FreePBX system.

Download Lenny’s sound files from this link. Crosstalk solutions is a hero for continuing to host this. Tell him thank you.

cd /var/lib/asterisk/sounds/
wget https://www.crosstalksolutions.com/pub/Lenny.zip
unzip Lenny.zip
chown asterisk:asterisk /var/lib/asterisk/sounds/Lenny/* -R
chmod -R 755 /var/lib/asterisk/sounds/Lenny/* -R

12.4 Create a Custom Destination in FreePBX

Log in to the FreePBX web interface.
Navigate to Admin > Custom Destinations.
Add a new custom destination with the following details:
- Custom Destination: Lenny,talk,1
This may be called TARGET instead of CUSTOM DESTINATION IN NEW VERSIONS
- Description: Lenny
Click Submit and then Apply Config to save the changes.

12.5 Set Lenny as a Destination

You now have multiple options for how to use Lenny.

Manual Transfers to Lenny:
- Navigate to Connectivity —> Extensions
- Create a new Virtual Extension
- Set the extension to whatever you want it to be; this is the number you dial to get Lenny & the number you transfer people to for Lenny
- Click on the Advanced tab
- Scroll to the bottom for destinations when nobody answers.
- Set each of the three to Custom Destinations —> Lenny
- Enjoy transferring telemarketers to Lenny at his extension. :)

12.6 Reload things in the terminal.

In your SSH terminal, type the following:

fwconsole reload

IMPORTANT: Hitting the red “Apply Config” button in the upper right corner of the FreePBX webpage is not enough here. For this to work, you must run fwconsole reload in the terminal.

12.7 Sending blocked numbers to Lenny

After hanging up on someone you hate, hit *32 quickly which will block their number.
Navigate to Admin —> Blacklist.
Click onto Settings.
Set the Destination for BlackListed Calls to Custom Destination —> Lenny.

Now every time you get a call from someone you hate, you can dial *32 & they will be routed to Lenny as soon as they call back. But remember, in the words of one of my first recording studio job bosses in 2007 - “Louis, you hate nothing; you intensely dislike it!”

Step 12: Hiring a virtual receptionist who tells annoying people to “get the fuck outta here!”

This is the primary reason to have a self managed PBX.

12.1 Download the Sound Files

First, SSH into your FreePBX machine:

ssh louis@freepbx.home.arpa

Download the sound files from the given URL using wget:

wget http://downloads.asterisk.org/pub/telephony/sounds/asterisk-extra-sounds-en-g722-current.tar.gz

12.2 Place the Files in the Proper Directory

After downloading the archive, extract it and move the files to the appropriate directory in FreePBX. Asterisk sound files typically reside in /var/lib/asterisk/sounds.

Extract the tarball:

tar -xvzf asterisk-extra-sounds-en-g722-current.tar.gz

Move the extracted files into the custom sound directory for FreePBX:

mv asterisk-extra-sounds-en-g722 /var/lib/asterisk/sounds/custom

If the custom directory doesn’t exist, you can create it:

mkdir /var/lib/asterisk/sounds/custom

12.3 Set Correct Permissions

Make sure that FreePBX and Asterisk can access the sound files by setting the correct ownership and permissions. FreePBX generally runs under the asterisk user:

chown -R asterisk:asterisk /var/lib/asterisk/sounds/custom/* -R
chmod -R 755 /var/lib/asterisk/sounds/custom/* -R

12.4 Find the Sound Files in the FreePBX GUI

Log in to the FreePBX Admin Interface.
Navigate to Admin > System Recordings.
Under Add Recording, you should now be able to see & use the uploaded sound files from the /var/lib/asterisk/sounds/custom directory.

12.5 Combine Sound Prompts into a Sequence

To combine multiple sound files into a single prompt sequence, use the System Recordings feature in FreePBX:

Go to Admin > System Recordings and create a new recording.
- Select the option to Add Sound Recording by combining the existing files.
- Add the sound files in the order you want them to play.
Choose the following codecs:
- alaw
- g722
- gsm
- ulaw
- wav
EXCLUDE the following codecs:
- g729
- sln
- sln16
- sln48
Save the combined sound as a new recording.

12.6 Create an Extension That Plays the Sound Prompts

To forward someone to an extension that plays back the sound prompts:

Log in to the FreePBX Admin Interface.
Navigate to Applications > Extensions.
Click Add Extension and select Custom Extension.
Set destination of unanswered to play your recording.
Save, Submit and Apply Config.

Now, you can transfer calls to this extension, and the selected sound prompts will be played back. Allison Smith will tell.

Step 13: Get emails with voicemails using Postfix with Postmark SMTP Relay

We are not doing the 1990s calling into voicemail system nonsense. That is miserable.

13.1 Configure the FROM Address in FreePBX

Log into your FreePBX web interface.
Navigate to Settings → Voicemail Admin.
Click the Settings tab.
Click on the Email Config tab.
Set the Server Email to an email address of your choice.
- I suggest this address be within the domain of the email you set up in mailcow.
- For instance, if you set up an email for yourself called steve@stevesavers.com in mailcow, make this voicemails@stevesavers.com.
Click Submit, then Apply Config (red button in the upper right corner).

13.2 Configure user access to voicemail

Navigate to Admin —> User Management.
Click Edit next to the user.
- Click the User Details tab at the top.
  - Check that the email address is correct.
- Click the UCP tab at the top.
  - Click the Call History sub-tab.
    - In CDR Access, add the extensions for which you want to allow this user to listen to call recordings. So if your extension is 401, then 401 should be in this list.
    - Set Allow CDR to Yes.
    - Set Allow CDR Downloads to Yes.
    - Set Allow CDR Playback to Yes.
  - Click the Voicemail sub-tab.
    - Make sure every option here is set to Yes.
    - In Allowed Voicemail, make sure that your extension is in the list. So if your extension is 401, then 401 should be in this list.
- Click Submit, then Apply Config (red button in the upper right corner).

13.3 Configure extension for voicemail

Navigate to Connectivity —> Extensions
- Choose your extension
Go to Voicemail
- Set your Voicemail password
- Set the Email Address to the email address you want it to email.
- Click Submit, then Apply Config red button in the upper right corner
Click UCP on the top menu to enter the User Control Panel
- Click the plus sign in the upper left to add a panel.
- Choose Voicemail.
- Choose your extension, in this case, 401
- Go to the little gear on the upper right corner of the panel you just added to open the settings menu
- Make sure Email Attachment is On
- Email Address should be the address that you want voicemails to go to.

13.4 Get Postmark Credentials for SMTP relay

We are using Postmark for SMTP relay so our emails are not immediately rejected by most providers.

Go to postmarkapp.com
Log in and click Servers
Click onto the server you made earlier.
Click Default Transactional Stream
Navigate to the Setup Instructions page after clicking onto your message stream.
- Under “Pick the library or integration” – pick “SMTP”.
- This is the same thing we did when we set up mailcow with Postmark for SMTP relay in the mailcow section!
- Take note of these, as we will be using them with FreePBX

13.5 Modify Postfix Configuration

Edit the main configuration file:
```
sudo nano /etc/postfix/main.cf
```
Find and modify/add these lines. Keep everything elsein the main.cf file unchanged. Adjust the sender_canonical_maps = static:voicemailalert@stevesavers.com to the email address you wish to use.

relayhost = [smtp.postmarkapp.com]:587
smtp_use_tls = yes
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
smtp_sasl_security_options = noanonymous
smtp_sasl_mechanism_filter = plain
sender_canonical_maps = static:voicemailalert@stevesavers.com

Make sure that you change

myhostname = {whateverishere}

so the {whateverishere} section is the domain name of your email. For example, if I am having the server use

voicemailalert@stevesavers.com

as the from email, then

myhostname = stevesavers.com

is how that option should be set.

13.6 Set Up Authentication

Ssh into the FreePBX virtual machine:
```
ssh louis@192.168.5.6
```
Create/edit the SASL password file:
```
sudo nano /etc/postfix/sasl_passwd
```
Add this line (replace USERNAME:PASSWORD with your Postmark credentials):
```
[smtp.postmarkapp.com]:587 USERNAME:PASSWORD
```

Create the hash database and set permissions:

sudo postmap /etc/postfix/sasl_passwd
sudo chmod 600 /etc/postfix/sasl_passwd*

13.7 Restart Postfix

sudo systemctl restart postfix

13.8 Test Configuration

Send a test email:

cat << EOF | sendmail l.a.rossmann@gmail.com
From: voicemailalert@stevesavers.com
To: l.a.rossmann@gmail.com
Subject: Test Email
Content-Type: text/plain
X-PM-Message-Stream: outbound

This is a test email body.
EOF

Check mail logs for errors:

sudo tail -f /var/log/mail.log

Troubleshooting

If emails aren’t sending:

Check /var/log/mail.log for errors
Check that Postmark credentials are correct (if you typed postmark.com instead of postmarkapp.com for server, etc)
Verify sender domain (stevesavers.com) is properly configured in Postmark
Check the activity tab on the transactional stream in Postmark
Mail log will tell you what you fkd up 99% of time.

Postmark Activity Monitor:

If you want more troubleshooting information, check Postmark.

Log into Postmark.
Click Servers
Click onto the server you made.
Click onto your Default Transactional Stream
Click Activity
Poke around.

Default /etc/postfix/main.cf config file

Just in case you mess something up, here’s the default one, because the ones in /usr/share/postfix require configuration from scratch. What they mean when they say “more complete” version is “we don’t offer a copy anywhere of the just working version”, because it’s… GNU/Linux.

# See /usr/share/postfix/main.cf.dist for a commented, more complete version


# Debian specific:  Specifying a file name will cause the first
# line of that file to be used as the name.  The Debian default
# is /etc/mailname.
#myorigin = /etc/mailname

smtpd_banner = $myhostname ESMTP $mail_name (Debian/GNU)
biff = no

# appending .domain is the MUA's job.
append_dot_mydomain = no

# Uncomment the next line to generate "delayed mail" warnings
#delay_warning_time = 4h

readme_directory = no

# See http://www.postfix.org/COMPATIBILITY_README.html -- default to 3.6 on
# fresh installs.
compatibility_level = 3.6



# TLS parameters
smtpd_tls_cert_file=/etc/ssl/certs/ssl-cert-snakeoil.pem
smtpd_tls_key_file=/etc/ssl/private/ssl-cert-snakeoil.key
smtpd_tls_security_level=may

smtp_tls_CApath=/etc/ssl/certs
smtp_tls_security_level=may
smtp_tls_session_cache_database = btree:${data_directory}/smtp_scache


smtpd_relay_restrictions = permit_mynetworks permit_sasl_authenticated defer_unauth_destination
myhostname = debian.home.arpa
alias_maps = hash:/etc/aliases
alias_database = hash:/etc/aliases
mydestination = $myhostname, debian, localhost.localdomain, localhost
relayhost = 
mynetworks = 127.0.0.0/8 [::ffff:127.0.0.0]/104 [::1]/128
mailbox_size_limit = 0
recipient_delimiter = +
# WARNING: Changing the inet_interfaces to an IP other than 127.0.0.1 may expose Postfix to external network connections.
# Only modify this setting if you understand the implications and have specific network requirements.
inet_interfaces = 127.0.0.1
inet_protocols = all
message_size_limit = 102400000