How to install Asterisk + FreePBX 17 on Debian 12

This guide installs FreePBX 17 with Asterisk on Debian 12 (Bookworm) using the official FreePBX installation script.

Use Debian 12, not Debian 13. FreePBX's current official installer is specifically designed for Debian 12 / Bookworm, and the installer itself contains logic to prevent an unsupported upgrade to Debian 13 / Trixie. (Sangoma KB)

FreePBX 17 officially moved to Debian as its supported base operating system, with Debian 12 being the supported platform for the current installer. (FreePBX - Let Freedom Ring)

System Requirements

Recommended for a small production PBX:

OS:        Debian 12 Bookworm
CPU:       2+ vCPU
RAM:       4 GB+
Disk:      40 GB+ SSD
Network:   Static IP strongly recommended

For heavier environments:

CPU:       4-8+ cores
RAM:       8 GB+
Disk:      SSD/NVMe
Network:   Stable low-latency connection

Sizing depends mainly on:

Concurrent calls
Call recording
Voicemail
Transcoding
Conference bridges
SIP trunks
Number of extensions
WebRTC usage

Network Ports

Typical FreePBX/Asterisk ports include:

Port	Protocol	Purpose
`80`	TCP	HTTP
`443`	TCP	HTTPS
`5060`	UDP/TCP	SIP
`5061`	TCP	SIP TLS
`5160`	UDP	Legacy SIP, if configured
`10000-20000`	UDP	RTP media
`8088`	TCP	Asterisk HTTP/WebSocket
`8089`	TCP	Asterisk HTTPS/WebSocket

The exact SIP and RTP ports should be verified against your FreePBX configuration before firewalling.

Recommended Architecture

                     Internet
                        │
                        ▼
                SIP Trunk Provider
                        │
                        │ SIP
                        ▼
                 ┌─────────────┐
                 │ Firewall /  │
                 │ Router      │
                 └──────┬──────┘
                        │
                        ▼
                 ┌─────────────┐
                 │ FreePBX 17  │
                 │ Asterisk    │
                 │ Debian 12   │
                 └──────┬──────┘
                        │
          ┌─────────────┼─────────────┐
          │             │             │
          ▼             ▼             ▼
      SIP Phone      WebRTC        Softphone

1. Install Debian 12

Start with a fresh Debian 12 Bookworm server or VM.

FreePBX's official instructions explicitly say to begin with a Debian 12 host or virtual machine. (Sangoma KB)

Recommended installation options:

Debian 12
SSH Server
Standard system utilities

A desktop environment is not required.

2. Verify Debian Version

Before continuing:

cat /etc/os-release

You should see:

VERSION_ID="12"
VERSION_CODENAME=bookworm

Also:

lsb_release -a

if lsb-release is installed.

Do not proceed if the machine is Debian 13.

3. Configure Static IP

A PBX should normally use a stable IP address.

Check:

ip addr

Example:

10.10.10.20

Also verify hostname:

hostnamectl

Example:

freepbx01.example.local

Set if needed:

sudo hostnamectl set-hostname freepbx01

4. Update Debian

sudo apt update
sudo apt upgrade -y

Reboot if required:

sudo reboot

After reboot:

cat /etc/os-release

Verify that the system is still:

Debian 12 / Bookworm

The current FreePBX installer contains explicit safeguards around Debian 13 because FreePBX currently supports Debian 12/Bookworm. (GitHub)

5. Install Basic Requirements

sudo apt install -y \
    wget \
    curl \
    ca-certificates

6. Download the Official FreePBX Installer

Create a working directory:

mkdir -p ~/freepbx-install
cd ~/freepbx-install

Download the current official installation script from the FreePBX GitHub repository:

wget \
  https://raw.githubusercontent.com/FreePBX/sng_freepbx_debian_install/master/sng_freepbx_debian_install.sh

The official FreePBX repository describes this as the FreePBX 17 installation script for vanilla Debian 12.x. (GitHub)

Set executable permission:

chmod +x sng_freepbx_debian_install.sh

7. Run the Installer

Run as root:

sudo ./sng_freepbx_debian_install.sh

This is the supported FreePBX 17 installation approach documented by Sangoma: start from Debian 12 and execute their GitHub-hosted installation script. (Sangoma KB)

The script installs and configures the FreePBX software stack automatically.

Important: Do Not Manually Install Asterisk First

When using the official FreePBX installation script, do not separately install:

Asterisk
Apache
MariaDB
PHP
Node.js
FreePBX

before running it unless you specifically intend to perform an expert/manual installation.

The official installer handles the required stack.

Sangoma separately documents a manual installation path, but explicitly labels it as an experts-only method because some modules/features may not behave as expected. (Sangoma KB)

8. Check Installation Logs

If installation fails, inspect the generated installer log.

List:

ls -lah /var/log/

Also search:

sudo find /var/log -iname '*freepbx*' -o -iname '*asterisk*'

Depending on the installer version, an installation log with a FreePBX-specific filename will be generated.

9. Verify Services

Check Asterisk:

sudo systemctl status asterisk

Check Apache:

sudo systemctl status apache2

Check MariaDB:

sudo systemctl status mariadb

FreePBX:

sudo fwconsole status

Restart FreePBX-managed services:

sudo fwconsole restart

10. Open FreePBX

From another machine on the network:

http://SERVER_IP

Example:

http://10.10.10.20

The official getting-started instructions say that once installation completes, browse to the new PBX IP and complete the initial administrator setup. (FreePBX - Let Freedom Ring)

11. Initial Administrator Setup

The first browser visit will prompt you to create the FreePBX administrator.

Configure:

Admin Username
Admin Password
Email

Use a strong administrator password.

Then log into:

FreePBX Administration

12. Verify Asterisk

Open the Asterisk CLI:

sudo asterisk -rvvv

You should enter a prompt similar to:

freepbx01*CLI>

Useful commands:

core show version

core show uptime

pjsip show endpoints

pjsip show registrations

Exit:

exit

13. Verify FreePBX CLI

sudo fwconsole --version

Check:

sudo fwconsole status

Reload configuration:

sudo fwconsole reload

Restart services:

sudo fwconsole restart

14. Update FreePBX Modules

From CLI:

sudo fwconsole ma upgradeall

Then:

sudo fwconsole reload

Or use:

Admin
    → Module Admin

in the FreePBX web interface.

15. Configure Firewall

FreePBX includes its own firewall module.

Use:

Connectivity
    → Firewall

rather than blindly opening all PBX ports publicly.

Define trusted networks such as:

10.10.10.0/24

for administration and internal SIP devices.

External Firewall / Router

Typical inbound ports may include:

5060 UDP/TCP
5061 TCP
10000-20000 UDP

However, only forward the ports actually required by your SIP provider and deployment.

Do not expose the FreePBX administrative web interface unnecessarily.

SIP NAT Configuration

If FreePBX is behind NAT:

Internet
    │
    ▼
Public IP
    │
    ▼
Router / NAT
    │
    ▼
10.10.10.20
FreePBX

Configure:

Settings
    → Asterisk SIP Settings

Set:

External Address
Local Networks

Example:

External Address:
163.53.181.162

Local Network:
10.10.10.0/24

Incorrect NAT configuration commonly produces:

One-way audio
No audio
Calls connect but media fails
Registration problems

RTP Port Range

Check:

Settings
    → Asterisk SIP Settings
    → RTP Settings

A common range is:

10000-20000 UDP

Your firewall/NAT must forward the same range if external media flows directly to the PBX.

SIP Trunk

Navigate:

Connectivity
    → Trunks
    → Add Trunk

For modern FreePBX installations, prefer:

PJSIP

unless your provider explicitly requires otherwise.

Typical information:

SIP Server
Username
Password
Authentication
Registration
From Domain
Codecs

Extensions

Navigate:

Applications
    → Extensions

Create:

PJSIP Extension

Example:

Extension:
1001

Display Name:
Reception

Use a strong SIP secret.

SIP Phone Configuration

Typical SIP client:

Server:
10.10.10.20

Port:
5060

Username:
1001

Password:
<extension secret>

PJSIP Diagnostics

Open:

sudo asterisk -rvvv

Show endpoints:

pjsip show endpoints

Show contacts:

pjsip show contacts

Show registrations:

pjsip show registrations

Show endpoint:

pjsip show endpoint 1001

SIP Packet Debugging

Install:

sudo apt install -y sngrep

Run:

sudo sngrep

This is particularly useful for diagnosing:

REGISTER
INVITE
180 Ringing
200 OK
ACK
BYE
401/407 authentication
403 errors

Asterisk Logs

Main logs are typically under:

/var/log/asterisk/

Watch:

sudo tail -f /var/log/asterisk/full

FreePBX logs:

sudo fwconsole log

System journal:

sudo journalctl -u asterisk -f

Call Recording

FreePBX can record:

Inbound calls
Outbound calls
Internal calls
Conferences

Recordings are generally stored under Asterisk's spool/monitor area, commonly:

/var/spool/asterisk/monitor/

Check:

sudo du -sh /var/spool/asterisk/monitor

Call recording can consume a significant amount of storage, so monitor disk utilization.

Voicemail Storage

Voicemail is generally stored beneath:

/var/spool/asterisk/voicemail/

Check:

sudo du -sh /var/spool/asterisk/voicemail

Storage Recommendation

For a dedicated PBX:

SSD

is preferable for the OS/database.

If call recording is enabled heavily, consider a larger dedicated volume.

Example:

/
├── OS
├── FreePBX
└── MariaDB

/data/
└── call-recordings/

Timezone

Set server timezone:

sudo timedatectl set-timezone Asia/Dhaka

Check:

timedatectl

Accurate timezone/time synchronization matters for:

CDRs
Call recordings
Voicemail
Schedules
Time conditions
Logs

NTP / Time Sync

Check:

timedatectl status

Make sure:

System clock synchronized: yes

is reported.

Fail2Ban

The official FreePBX installation stack includes security-related components and FreePBX provides integrated firewall/security controls.

Check:

sudo systemctl status fail2ban

If present:

sudo fail2ban-client status

Secure the Web Interface

Prefer:

https://pbx.example.com

over plaintext HTTP when remote administration is required.

Configure TLS from the FreePBX certificate management interface.

Also restrict administration to:

VPN
Trusted LAN
Management network

where possible.

Do Not Publicly Expose Admin UI

Avoid:

Internet
    │
    ▼
FreePBX Admin UI

Prefer:

Administrator
     │
     ▼
WireGuard / Tailscale / VPN
     │
     ▼
FreePBX Admin UI

FreePBX Backup

Navigate:

Admin
    → Backup & Restore

Create backups containing the required:

FreePBX configuration
Asterisk configuration
CDR data
Voicemail
Certificates
Recordings where required

Store backups outside the PBX server.

Recommended Backup Architecture

FreePBX
   │
   │ Scheduled backup
   ▼
Remote storage
   │
   ├── NAS
   ├── S3-compatible storage
   └── Backup server

A local backup stored on the same disk is not sufficient protection against disk failure.

Restore

For migration or disaster recovery:

Fresh Debian 12
      │
      ▼
Install FreePBX 17
      │
      ▼
Restore FreePBX backup

Ensure the source and target FreePBX versions are compatible with the chosen restore procedure.

Important: Do Not Upgrade Debian 12 to Debian 13

For this deployment, do not perform:

sudo sed -i 's/bookworm/trixie/g' /etc/apt/sources.list

or any equivalent Debian major-version upgrade.

Do not change repositories from:

bookworm

to:

trixie

FreePBX's current installer explicitly states that it supports only Debian 12/Bookworm and contains code to block Debian 13/Trixie updates. (GitHub)

Upgrade FreePBX/Asterisk through the supported FreePBX upgrade path rather than upgrading the underlying distribution independently.

Debian Security Updates

You can still apply normal Debian 12 updates:

sudo apt update
sudo apt upgrade

But verify that APT remains pointed to:

bookworm

Check:

grep -R "trixie\|bookworm" \
    /etc/apt/sources.list \
    /etc/apt/sources.list.d/ \
    2>/dev/null

You should not accidentally have Debian 13/Trixie sources active.

Check OS Before Updating

A useful safety check:

cat /etc/debian_version

and:

cat /etc/os-release

Expected:

Debian GNU/Linux 12
bookworm

Recommended VM Configuration

For Proxmox/VMware/Hyper-V:

CPU:        4 vCPU
RAM:        4-8 GB
Disk:       50-100 GB SSD
NIC:        VirtIO / VMXNET3
IP:         Static
Snapshots:  Before major FreePBX upgrades

If heavy recording is enabled:

Separate recording disk / volume

is recommended.

Proxmox Example

Proxmox
   │
   ▼
Debian 12 VM
   │
   ├── FreePBX 17
   ├── Asterisk
   ├── MariaDB
   └── Apache

Use a VM rather than an LXC container for the most predictable PBX environment, especially if you expect:

DAHDI hardware
USB telephony devices
Kernel-dependent telephony features
Complex networking

High Availability Note

FreePBX itself is not normally deployed as an active-active application cluster.

For PBX resilience, common approaches include:

Primary FreePBX
      │
      ▼
Backup FreePBX / standby

plus:

SIP trunk failover
DNS/SRV
Provider failover
Backup/restore
Hypervisor HA
VM replication

Do not assume that simply running two FreePBX servers creates one shared Asterisk cluster.

Useful Commands

FreePBX

sudo fwconsole status

sudo fwconsole reload

sudo fwconsole restart

sudo fwconsole ma list

sudo fwconsole ma upgradeall

Asterisk

sudo asterisk -rvvv

core show version

core show channels

pjsip show endpoints

pjsip show contacts

pjsip show registrations

Services

sudo systemctl status asterisk

sudo systemctl status apache2

sudo systemctl status mariadb

Ports

sudo ss -lntup

Filter SIP:

sudo ss -lunp | grep 5060

Management:

sudo ss -lntp | grep -E ':80|:443'

Troubleshooting

FreePBX Web UI Not Available

Check:

sudo systemctl status apache2

Then:

sudo fwconsole status

Logs:

sudo journalctl -u apache2 -n 100

Asterisk Not Running

sudo systemctl status asterisk

Logs:

sudo journalctl -u asterisk -n 200

Asterisk log:

sudo tail -n 200 \
    /var/log/asterisk/full

Extension Will Not Register

Check:

sudo asterisk -rvvv

Then:

pjsip show endpoints

pjsip show contacts

Use:

sudo sngrep

and verify:

IP
Port
Username
Secret
Transport
Firewall
NAT

One-Way Audio

Usually investigate:

RTP port forwarding
External address
Local network configuration
SIP ALG
NAT
Firewall

Verify:

Settings
    → Asterisk SIP Settings

particularly:

External Address
Local Networks
RTP Port Range

Disable SIP ALG

On the edge router/firewall, SIP ALG often causes unpredictable SIP rewriting.

If your router provides a setting named:

SIP ALG
SIP Helper
SIP Inspection

it is commonly preferable to disable it for properly configured Asterisk deployments and handle NAT explicitly.

Quick Installation

Start with a fresh:

Debian 12 Bookworm

Verify:

cat /etc/os-release

Update:

sudo apt update
sudo apt upgrade -y

Install downloader:

sudo apt install -y wget

Download installer:

wget \
  https://raw.githubusercontent.com/FreePBX/sng_freepbx_debian_install/master/sng_freepbx_debian_install.sh

Make executable:

chmod +x sng_freepbx_debian_install.sh

Run:

sudo ./sng_freepbx_debian_install.sh

When complete, open:

http://SERVER_IP

Create the FreePBX administrator and continue configuration.

This is the official FreePBX 17 workflow for Debian 12. (Sangoma KB)

Recommended Production Checklist

[ ] Use Debian 12 Bookworm, not Debian 13.
[ ] Start from a clean Debian 12 host or VM.
[ ] Use the official FreePBX installation script.
[ ] Do not manually pre-install Asterisk when using the installer.
[ ] Configure a static IP.
[ ] Configure correct hostname/DNS.
[ ] Keep accurate NTP/timezone settings.
[ ] Configure Asterisk External Address and Local Networks.
[ ] Forward only required SIP/RTP ports.
[ ] Do not expose the FreePBX Admin UI publicly.
[ ] Use VPN for administration where practical.
[ ] Use strong extension secrets.
[ ] Use PJSIP for new deployments unless there is a compatibility reason otherwise.
[ ] Disable SIP ALG if it interferes with SIP traffic.
[ ] Configure FreePBX Firewall.
[ ] Enable TLS where appropriate.
[ ] Configure automated off-server backups.
[ ] Monitor recording/voicemail disk usage.
[ ] Snapshot the VM before major FreePBX upgrades.
[ ] Keep Debian repositories on Bookworm.
[ ] Do not perform an in-place Debian 12 → 13 upgrade until FreePBX officially supports it.

Why Debian 12?

FreePBX 17's official installation documentation tells users to start from a Debian 12 host or VM and run the GNU GPL install script. (Sangoma KB)

The FreePBX project's installation repository describes the script specifically as an installer for vanilla Debian 12.x. (GitHub)

Most importantly, the current official installation script explicitly contains logic to block Debian 13/Trixie updates because FreePBX currently supports only Debian 12/Bookworm. (GitHub)

Therefore this server should remain on:

Debian 12 Bookworm

until FreePBX/Sangoma publishes an officially supported Debian 13 installation or migration procedure.

References

The official Sangoma FreePBX 17 installation documentation instructs administrators to use a Debian 12 machine or VM and execute the official GitHub-hosted installation script. (Sangoma KB)

The official FreePBX 17 installer repository states that the script installs FreePBX 17 on top of vanilla Debian 12.x. (GitHub)

FreePBX's current installer explicitly says that FreePBX supports only Debian 12/Bookworm and includes logic to prevent upgrades to Debian 13/Trixie. (GitHub)

FreePBX 17 officially moved the supported FreePBX platform to Debian, with Debian 12 used as the supported base OS for the installation script. (FreePBX - Let Freedom Ring)

Gallery

Contacts

System Requirements

Network Ports

Recommended Architecture

1. Install Debian 12

2. Verify Debian Version

3. Configure Static IP

4. Update Debian

5. Install Basic Requirements

6. Download the Official FreePBX Installer

7. Run the Installer

Important: Do Not Manually Install Asterisk First

8. Check Installation Logs

9. Verify Services

10. Open FreePBX

11. Initial Administrator Setup

12. Verify Asterisk

13. Verify FreePBX CLI

14. Update FreePBX Modules

15. Configure Firewall

External Firewall / Router

SIP NAT Configuration

RTP Port Range

SIP Trunk

Extensions

SIP Phone Configuration

PJSIP Diagnostics

SIP Packet Debugging

Asterisk Logs

Call Recording

Voicemail Storage

Storage Recommendation

Timezone

NTP / Time Sync

Fail2Ban

Secure the Web Interface

Do Not Publicly Expose Admin UI

FreePBX Backup

Recommended Backup Architecture

Restore

Important: Do Not Upgrade Debian 12 to Debian 13

Debian Security Updates

Check OS Before Updating

Recommended VM Configuration

Proxmox Example

High Availability Note

Useful Commands

FreePBX

Asterisk

Services

Ports

Troubleshooting

FreePBX Web UI Not Available

Asterisk Not Running

Extension Will Not Register

One-Way Audio

Disable SIP ALG

Quick Installation

Recommended Production Checklist

Why Debian 12?

References

How to install RabbitMQ on Debian 13 with Cluster Support

How to install Kubernetes K3s on Debian 13

Leave a comment Cancel reply

Company

Solutions

Contact Info