---
name: fusionpbx
description: FusionPBX recipe for open-forge. Full-featured multi-tenant PBX web interface for FreeSWITCH. Manages extensions, IVR menus, call routing, voicemail, conference rooms, call queues, and fax. Debian/Ubuntu install via script. Source: https://github.com/fusionpbx/fusionpbx
---

# FusionPBX

Full-featured, multi-tenant PBX web administration interface for FreeSWITCH. Manages extensions, IVR menus, call routing, ring groups, voicemail, conference rooms, call queues, fax, call recording, and more. Supports multiple tenants (domains) on a single installation. Written in PHP with a PostgreSQL backend. FreeSWITCH provides the actual SIP/voice processing; FusionPBX provides the web UI to configure and manage it. Upstream: https://github.com/fusionpbx/fusionpbx. Docs: https://docs.fusionpbx.com/.

## Compatible install methods

| Method | Platform | Notes |
|---|---|---|
| Install script | Debian 12 / Ubuntu 22.04+ | Recommended. Installs FreeSWITCH + FusionPBX + PostgreSQL + nginx. |
| Manual install | Debian / Ubuntu | For custom setups; follow docs carefully. |

## Inputs to collect

| Phase | Prompt | Notes |
|---|---|---|
| install | "Target OS?" | Debian 12 (Bookworm) or Ubuntu 22.04+ LTS recommended |
| install | "Server hostname / domain?" | Used for SIP domain(s) and web UI certificate |
| install | "Domain name(s) for PBX?" | One per tenant; can add more later in Admin UI |
| install | "Admin username + password?" | Created during install script |
| sip | "SIP trunk provider credentials?" | Added after install in Admin UI |
| tls | "TLS certificate?" | Let's Encrypt or self-signed for SIP TLS/SRTP |

## Software-layer concerns

### Install via script (Debian/Ubuntu)

  # Prerequisites: fresh Debian 12 or Ubuntu 22.04 server (dedicated/VM recommended)
  # Run as root:

  # Debian:
  wget https://raw.githubusercontent.com/fusionpbx/fusionpbx-install.sh/master/debian/install.sh
  chmod +x install.sh
  ./install.sh

  # Ubuntu:
  wget https://raw.githubusercontent.com/fusionpbx/fusionpbx-install.sh/master/ubuntu/install.sh
  chmod +x install.sh
  ./install.sh

  # The script installs:
  # - FreeSWITCH (voice switch)
  # - FusionPBX (web UI via PHP-FPM + nginx)
  # - PostgreSQL (database)
  # - Fail2ban (security)
  # - Let's Encrypt TLS (optional, prompted during install)

### After install — web UI access

  https://<server-ip-or-domain>/   # FusionPBX admin panel
  # Default credentials created during install script.

### Key services

  freeswitch         # FreeSWITCH SIP server (systemd service)
  nginx              # Web server for FusionPBX UI
  php8.x-fpm         # PHP processor
  postgresql         # Database

  systemctl status freeswitch
  systemctl status nginx
  systemctl status postgresql

### Key directories

  /var/www/fusionpbx/          # FusionPBX PHP application
  /etc/freeswitch/             # FreeSWITCH configuration (XML, generated by FusionPBX)
  /var/lib/freeswitch/         # FreeSWITCH data (recordings, voicemail, etc.)
  /usr/share/freeswitch/       # FreeSWITCH sounds, music-on-hold

### SIP ports

  5060/udp+tcp   # SIP plaintext
  5061/tcp       # SIP TLS (SIPS)
  16384-32768/udp  # RTP media (configurable range)

### Database

  # PostgreSQL database: fusionpbx
  # Connection string in: /etc/fusionpbx/config.php
  sudo -u postgres psql fusionpbx

### Backup

  # Back up both database and recording files:
  pg_dump fusionpbx > fusionpbx_$(date +%Y%m%d).sql
  tar -czf fusionpbx_recordings_$(date +%Y%m%d).tar.gz /var/lib/freeswitch/recordings/

### Multi-tenant setup

  # Admin → Domains → Add Domain
  # Each domain acts as a separate PBX tenant with its own extensions and routing.
  # SIP clients register with: username@domain or just username (depends on config).

## Upgrade procedure

  # FusionPBX (web app only):
  cd /var/www/fusionpbx
  git pull origin master
  # Then log in to Admin UI → Advanced → Upgrade → run upgrade steps

  # Full system upgrade: follow https://docs.fusionpbx.com/en/latest/getting_started/upgrade.html

## Gotchas

- **Dedicated server recommended**: FusionPBX + FreeSWITCH work best on a dedicated VM or physical server. Running alongside other services on the same box can cause port conflicts (SIP ports, RTP range).
- **Firewall critical**: open SIP (5060/udp+tcp, 5061/tcp) and the RTP range (16384-32768/udp) on your firewall. Also open 80/443 for the web UI.
- **Fail2ban included**: the install script configures Fail2ban to block SIP scanners. Check `/var/log/fail2ban.log` if legitimate devices are blocked.
- **FreeSWITCH config is generated**: FusionPBX manages `/etc/freeswitch/` via its database. Do not edit XML files directly — use the FusionPBX Admin UI, then Advanced → Reload or Advanced → FreeSWITCH to apply changes.
- **TLS/SRTP for security**: plaintext SIP is vulnerable to eavesdropping. Enable SIP TLS (port 5061) and SRTP for production deployments, especially over the internet.
- **PostgreSQL not MySQL**: FusionPBX uses PostgreSQL. The install script handles this, but manual installs must ensure pg_hba.conf allows the FusionPBX user to connect.
- **Signaling vs media NAT**: for servers behind NAT, configure `external_rtp_ip` and `external_sip_ip` in FreeSWITCH (via FusionPBX → Advanced → Variables) to the public IP. Without this, remote phones cannot receive audio.

## References

- Upstream GitHub: https://github.com/fusionpbx/fusionpbx
- Install script: https://github.com/fusionpbx/fusionpbx-install.sh
- Documentation: https://docs.fusionpbx.com/
- Community forum: https://community.fusionpbx.com/
- FreeSWITCH docs: https://developer.signalwire.com/freeswitch/
