Introduction
We wanted to build a phone system in our homelabs. Each of us set up a FreePBX server, purchased a VoIP phone, and configured trunks between our servers to make it work. This setup simulates internal phone calling, with plans to add external calling in the future.
FreePBX Installation
There are two ways you can install FreePBX. One with using their ISO file found here: https://www.freepbx.org/downloads/
The other way is to install it on top of Debian 12. We will go over how to do it both ways.
ISO Install
The easiest and most “plug-and-play” way to get FreePBX running is by using the official FreePBX ISO. This method installs a minimal, hardened Linux OS with Asterisk and FreePBX preconfigured, making it ideal for dedicated hardware or a VM.
Start by downloading the latest FreePBX ISO from the official site and attach it to your physical server or virtual machine. Boot from the ISO and follow the on-screen installer. Most environments can safely use the default options.
During installation, you’ll be prompted to:
- Select your time zone
- Configure basic network settings (DHCP or static IP)
- Set the root password (Do this before clicking next or you could be locked out of your PBX cmd shell)
Once the installer finishes, remove the ISO and reboot the system. After boot, FreePBX will display the management IP address on the console.
From another machine on the network, open a browser and navigate to:
http://<FreePBX-IP-address>
You’ll then be guided through the initial web-based setup, including:
- Creating the FreePBX admin account
- Setting system credentials
- Applying initial module updates
This method is best suited for production or lab environments where FreePBX will be the primary role of the system, as it provides a clean, purpose-built PBX with minimal setup effort.
Debian Install
Important: At the time of writing, the official install script does not support newer Debian versions.
Step 1 — Install Debian
Install Debian 12 (Bookworm) with a minimal install.
You can do this on:
- Proxmox VM
- Other hypervisor
- Physical hardware
Step 2 — Switch to Root
The installer must be run as the root user:
sudo su
Step 3 — Download and Run the FreePBX Installer
FreePBX provides an automated install script.
Run the following commands:
cd /tmp
wget https://github.com/FreePBX/sng_freepbx_debian_install/raw/master/sng_freepbx_debian_install.sh -O sng_freepbx_debian_install.sh
bash sng_freepbx_debian_install.sh
Tip: This process can take quite a while depending on your system resources.
Step 4 — Complete Initial Setup
Once the script finishes, open your browser and navigate to:
http://<FreePBX-IP-address>
Follow the on-screen prompts to complete the initial configuration.
At this point, your FreePBX instance should be fully installed and ready for configuration.
Creating an Extension
Extensions are what allow phones, softphones, or SIP devices to register to FreePBX and make or receive calls. Each user or device typically gets its own extension.
To create an extension, log into the FreePBX web interface and navigate to:
Connectivity → Extensions
Click Add Extension and select Add New SIP [chan_pjsip] Extension (recommended for most setups).
At a minimum, you’ll need to configure the following:
- User Extension – The extension number (e.g.,
1001)
- Display Name – A friendly name for the user or device
- Secret – The SIP password used by the phone or softphone
Scroll down and review the remaining options. In most cases, the defaults are fine for a basic setup.
Once finished, click Submit, then Apply Config at the top of the page.
After the extension is created, use the extension number, SIP server IP, and secret to register a physical phone or softphone (such as Zoiper, Linphone, or a desk phone). If registration is successful, the extension should show as Available in the FreePBX dashboard.
This process can be repeated for each user or device that needs access to the PBX.
Voicemail Setup
Voicemail allows users to receive messages when they are unavailable. Setting it up in FreePBX is straightforward, but it’s important to make sure the PIN matches between the extension and the phone if you plan to access voicemail directly from the handset.
Enabling Voicemail for an Extension (Optional)
Log into the FreePBX web interface.
Navigate to: Connectivity → Extensions
Select the extension you want to enable voicemail for.
Scroll down to the Voicemail section.
Check Enable Voicemail.
Set a Voicemail Password / PIN (4–10 digits). This is what users will enter when checking messages from their phone.
Optionally, configure Email Notification:
- Enter the user’s email to receive voicemail notifications.
- Choose whether to attach the message as a
.wav file.
Click Submit and then Apply Config at the top.
Accessing Voicemail from the Phone
- Dial the voicemail access code (usually
*97 by default).
- Enter the voicemail PIN.
- Follow the prompts to listen to, save, or delete messages.
Tips:
- Make sure the voicemail PIN on the phone matches the PIN set in FreePBX; otherwise, access will fail.
- You can change the voicemail greeting from the phone or the FreePBX web interface.
- If using email notifications, confirm your FreePBX server can send emails (SMTP configured correctly).
Voicemail adds a simple but powerful layer of functionality, ensuring that no call goes unanswered even when extensions are unavailable.
Mapping Extension to Sangoma S505
After creating the extension in FreePBX, you need to configure the Sangoma S505 so it can register with the PBX and make/receive calls.
Manual Configuration
- Find the phone’s IP address on your network (check the screen or use your router’s DHCP table).
- Open a web browser and navigate to the phone’s IP address.
- Log in as the administrator.
- Enter the SIP account details from the extension you created:
- Username / Extension – Your extension number (e.g.,
1001)
- Authentication ID – Your extension number
- Password / Secret – The extension secret
- SIP Server / Proxy – The FreePBX server IP address
- Save the configuration and reboot the phone.
Once the phone restarts, it should register to FreePBX and appear as Available in the dashboard. The extension is now ready to make and receive calls.
Tips:
- Ensure the phone and FreePBX are on the same LAN, or configure proper NAT/firewall rules if remote.
- Double-check the extension secret if registration fails.
- If enabling voicemail, make sure the PIN on the phone matches the PIN configured for the extension in FreePBX.
- Verify the SIP port (usually
5060) is not blocked by the network.
Creating Trunk Connections Between PBX Servers
This assumes:
- Both FreePBX servers are already installed and reachable over the network (VPN, site-to-site tunnel, or public IP).
- You know the IP address of the remote PBX.
Step 1 — Create the Trunk on PBX #1
- Log into the FreePBX Web UI.
- Navigate to:
Connectivity → Trunks
- Click Add Trunk → Add SIP (chan_pjsip) Trunk
Step 2 — Configure the General Settings
Give the trunk a recognizable name:
Trunk Name: PBX2
Step 3 — Configure the PJSIP Settings
Under the pjsip Settings tab:
General
Authentication: None (or Outbound if using credentials)
Registration: None
SIP Server: <PBX2-IP-Address>
SIP Server Port: 5060
Advanced
Match (Permit): <PBX2-IP-Address>
This allows calls from the remote PBX.
Step 4 — Repeat on PBX #2
Repeat the same process on the second FreePBX server:
Connectivity → Trunks → Add SIP (chan_pjsip)
Set:
Trunk Name: PBX1
SIP Server: <PBX1-IP-Address>
Match (Permit): <PBX1-IP-Address>
Authentication: None
Registration: None
Apply Config after saving.
Step 5 — Create Outbound Routes
To allow extensions to dial the other PBX:
- Navigate to:
Connectivity → Outbound Routes
- Create a new route.
Example:
Route Name: To-PBX2
Dial Patterns: 3XXX
Trunk Sequence: PBX2
This means any extension dialing 3XXX will route across the trunk.
Repeat on PBX #2 if needed.
Step 6 — Test the Connection
From an extension on PBX #1:
- Dial an extension on PBX #2 that matches the route pattern.
If configured correctly:
- The call should complete immediately.
- Audio should flow both directions.
Debugging SIP Trunks
Once your SIP trunks are set up between multiple FreePBX servers, it’s common to run into issues like calls not connecting, audio problems, or registration failures. FreePBX and Asterisk provide several commands and logs that make troubleshooting much easier.
Useful Commands
tcpdump -i eth0 -n -s 0 -w sip-trunk.pcap port 5060 or portrange 10000-20000
pjsip show registrations
pjsip show endpoints
core show channels
Fixing 30-Second Timeout Issue
A common issue with SIP phones like the Sangoma S505 is calls dropping or failing after about 30 seconds. This usually happens when NAT settings or SIP session timers are misconfigured.
Steps to fix:
Check NAT Settings in FreePBX
- Navigate to Settings → Asterisk SIP Settings.
- Under the General SIP Settings, make sure:
- External Address is set to your public IP (if behind NAT).
- Local Networks includes your LAN subnet (e.g.,
192.168.1.0/24).
Adjust SIP Timers
- In Asterisk SIP Settings, look for SIP Timers / Session Timers:
- Enable Session Timers.
- Set the session expiration to around
180 seconds (default is usually fine, but sometimes devices need longer).
Configure Phone Keep-Alives
- On the Sangoma S505, enable SIP OPTIONS Ping or Keep Alive.
- This ensures the phone sends regular signals to FreePBX to keep the session active.
Firewall / NAT Considerations
- Make sure UDP port
5060 (or the port you use for SIP) is open and forwarded correctly if remote.
- Avoid double NAT if possible, as it can interfere with SIP signaling.
After making these changes, reboot the phone and test a call. Calls should no longer drop at the 30-second mark.
Tip: This issue almost always comes down to the phone not maintaining a proper NAT mapping with the PBX, so SIP keep-alives and proper external/local network configuration are key.
Conclusion
By setting up multiple FreePBX servers, configuring extensions, mapping phones like the Sangoma S505, and linking trunks between sites, you can create a fully functional multi-site phone system in your homelab. This setup allows internal calling across different locations and prepares your environment for future expansion to external calling. Proper NAT, SIP timers, and trunk configurations are crucial to maintaining reliable connections and avoiding common issues like dropped calls.
With these foundations in place, you can explore additional features such as voicemail notifications, custom dial plans, call queues, and integration with other communication tools. This hands-on approach not only builds a practical homelab but also provides valuable experience in managing real-world VoIP systems.