Reverse Proxy & Network Ports

Reverse Proxy Configuration

Reverse Proxy and Network Setup Guide

Configure AiPBX to safely run behind existing HTTP/HTTPS reverse proxies (such as Nginx, Caddy, Traefik, HAProxy, or Apache). Manage trusted proxy IPs to safely forward real client IP addresses, generate sample configurations, and inspect required network ports and firewall scripts.

Limits to know

HTTPS between the proxy and AiPBX only works with HAProxy. Port 443 tells HTTPS from TURNS by ALPN, and Nginx, Apache, Caddy and Traefik do not send it on the connections softphones need. With those, end TLS at the proxy and use a private network to reach AiPBX.

VoIP & Media Boundary Notice (SIP / RTP)

Standard HTTP/HTTPS reverse proxies can terminate web management traffic and proxy WebRTC WebSocket signaling (/ws). However, SIP signaling (ports 5060/5061 UDP/TCP) and audio/video RTP media streams (ports 10000-20000 UDP) CANNOT be routed through an HTTP reverse proxy. They must reach the AiPBX host directly via port forwarding, direct 1:1 NAT, or Layer 4 routing.

Real-Time Request Diagnostics

Immediate Remote IP (REMOTE_ADDR):
10.218.49.1 Direct / Untrusted

Forwarded IP (X-Forwarded-For):
—

Protocol (X-Forwarded-Proto):
—

Resolved Client IP (Effective):
10.218.49.1

Enable Reverse Proxy Mode

When enabled, AiPBX inspects X-Forwarded-For and X-Forwarded-Proto headers coming strictly from trusted proxies.

External FQDN / Domain

Public hostname clients use to access this PBX (e.g., pbx.example.com).

External HTTPS Port

Public port on the reverse proxy (default 443).

TLS Termination Mode

Choose how SSL/TLS encryption is handled between the proxy and AiPBX.

Preferred Reverse Proxy

Trusted Reverse Proxy IPs / CIDRs

Comma-separated list of proxy IPs or CIDR networks (e.g., 127.0.0.1, ::1, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16). Headers from unlisted IPs will be ignored.

Live Configuration Generator

Pre-configured, production-ready configuration snippets including WebRTC WebSocket (/ws) upgrade handling and client IP headers.

Sample Configuration for Nginx

# ==============================================================================
# /etc/nginx/sites-available/aipbx.conf
# AiPBX Reverse Proxy Configuration (Nginx)
# External FQDN: demo.aipbx.local
# Backend Target: http://10.218.49.190:80
#
# IMPORTANT: VoIP protocols (SIP 5060/5061 and RTP 10000-20000 UDP) MUST bypass
# this HTTP proxy and connect directly to the server host.
# ==============================================================================

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

upstream aipbx_web_backend {
    server 10.218.49.190:80;
    keepalive 32;
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name demo.aipbx.local;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

# Main HTTPS Server
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name demo.aipbx.local;

    # TLS Certificates (manage via certbot or centralized PKI)
    ssl_certificate /etc/letsencrypt/live/demo.aipbx.local/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/demo.aipbx.local/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;

    client_max_body_size 64M;

    # 1. WebRTC WebSocket Signaling (Softphones)
    location /ws {
        proxy_pass http://aipbx_web_backend/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Keep alive for long WebRTC sessions
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }

    # 2. Main Portal, Chat WebSocket & Desk Phone Provisioning
    location / {
        proxy_pass http://aipbx_web_backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        proxy_connect_timeout 60s;
        proxy_send_timeout 3600s;
        proxy_read_timeout 3600s;
        proxy_buffering off;
    }
}

Sample Configuration for Caddy

# ==============================================================================
# /etc/caddy/Caddyfile
# AiPBX Reverse Proxy Configuration (Caddy)
# External FQDN: demo.aipbx.local
#
# IMPORTANT: SIP (5060/5061) and RTP (10000-20000 UDP) MUST route directly.
# ==============================================================================

demo.aipbx.local {
    encode zstd gzip

    # Web Portal, Phone Provisioning and the WebSockets (/ws, /demo/en/chat/ws)
    reverse_proxy http://10.218.49.190:80 {
        header_up Host {host}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        header_up X-Forwarded-Host {host}
    }
}

Sample Configuration for Traefik

# ==============================================================================
# traefik-dynamic.yaml
# AiPBX Reverse Proxy Configuration (Traefik Dynamic File Provider)
# External FQDN: demo.aipbx.local
#
# IMPORTANT: SIP (5060/5061) and RTP (10000-20000 UDP) MUST route directly.
# ==============================================================================

http:
  routers:
    aipbx-web-http:
      rule: "Host(`demo.aipbx.local`)"
      entryPoints: ["web"]
      middlewares: ["redirect-to-https"]
      service: "noop@internal"

    aipbx-web:
      rule: "Host(`demo.aipbx.local`)"
      entryPoints: ["websecure"]
      service: "aipbx-web-svc"
      middlewares: ["forwarded-https"]
      tls:
        certResolver: "letsencrypt"

  middlewares:
    redirect-to-https:
      redirectScheme:
        scheme: "https"
        permanent: true
    # Traefik says "wss" for a WebSocket, and the portal redirects anything but "https".
    forwarded-https:
      headers:
        customRequestHeaders:
          X-Forwarded-Proto: "https"

  services:
    aipbx-web-svc:
      loadBalancer:
        passHostHeader: true
        servers:
          - url: "http://10.218.49.190:80"

Sample Configuration for HAProxy

# ==============================================================================
# /etc/haproxy/haproxy.cfg (Snippet for AiPBX)
# External FQDN: demo.aipbx.local
#
# IMPORTANT: SIP (5060/5061) and RTP (10000-20000 UDP) MUST route directly.
# ==============================================================================

frontend http_in
    bind *:80
    bind *:443 ssl crt /etc/ssl/certs/demo.aipbx.local.pem alpn h2,http/1.1
    redirect scheme https code 301 if !{ ssl_fc }

    acl is_aipbx hdr(host) -i demo.aipbx.local
    acl is_websocket hdr(Upgrade) -i WebSocket
    acl is_ws_path path_beg /ws

    use_backend aipbx_ws_backend if is_aipbx is_websocket or is_aipbx is_ws_path
    use_backend aipbx_web_backend if is_aipbx

backend aipbx_web_backend
    mode http
    option forwardfor
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    http-request set-header X-Forwarded-Host %[req.hdr(host)]
    server aipbx1 10.218.49.190:80 check

backend aipbx_ws_backend
    mode http
    option forwardfor
    timeout tunnel 3600s
    http-request set-header X-Forwarded-Proto https if { ssl_fc }
    server aipbx_ws1 10.218.49.190:80 check

Sample Configuration for Apache

# ==============================================================================
# /etc/apache2/sites-available/aipbx-reverse-proxy.conf
# AiPBX Reverse Proxy Configuration (Apache 2.4)
# External FQDN: demo.aipbx.local
#
# Required modules: a2enmod proxy proxy_http proxy_wstunnel ssl rewrite headers
# IMPORTANT: SIP (5060/5061) and RTP (10000-20000 UDP) MUST route directly.
# ==============================================================================

<VirtualHost *:80>
    ServerName demo.aipbx.local
    RewriteEngine On
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

<VirtualHost *:443>
    ServerName demo.aipbx.local

    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/demo.aipbx.local/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/demo.aipbx.local/privkey.pem

    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"
    RequestHeader set X-Forwarded-Port "443"

    # WebRTC WebSocket Signaling
    ProxyPass /ws ws://10.218.49.190:80/ws
    ProxyPassReverse /ws ws://10.218.49.190:80/ws
    ProxyPass /chat/ws ws://10.218.49.190:80/chat/ws
    ProxyPassReverse /chat/ws ws://10.218.49.190:80/chat/ws

    # Main Web Portal
    ProxyPass / http://10.218.49.190:80/
    ProxyPassReverse / http://10.218.49.190:80/
</VirtualHost>

Network Ports & Firewall Matrix

Comprehensive matrix of all network ports used by AiPBX, showing protocols, required exposure, and reverse proxy bypass status.

Port Range	Protocol	Service / Purpose	Access Scope	Proxy Bypass	Description & Notes
5060	UDP / TCP	SIP Signaling	Public / LAN	Direct (Bypass)	Standard SIP phone signaling, PBX trunks, and softphone registrations.
5061	TCP	SIP-TLS Signaling	Public / LAN	Direct (Bypass)	Secure encrypted SIP signaling via TLS.
10000-20000	UDP	RTP / SRTP Media	Public / LAN	Direct (Bypass)	Real-time Transport Protocol streams for two-way audio and video calls.
80	TCP	HTTP Web Portal / ACME	Public / LAN	Proxied (HTTP/WS)	Web administration portal, phone auto-provisioning, and Let's Encrypt HTTP-01 challenge.
443	TCP	HTTPS Web Portal	Public / LAN	Proxied (HTTP/WS)	Encrypted Web portal, REST API endpoints, and WebSocket proxying.
8089	TCP	Asterisk WSS (WebRTC)	Localhost (127.0.0.1)	Proxied (HTTP/WS)	Not used by clients and never opened: browsers and the mobile apps reach WebRTC signaling over 443 at /ws.
8088	TCP	Asterisk HTTP / WS	Localhost (127.0.0.1)	Proxied (HTTP/WS)	Behind /ws of the portal. A reverse proxy connects to the portal, not to this port.
3478 / 5349	UDP / TCP	STUN / TURNS (coturn)	Public	Direct (Bypass)	NAT traversal relay for WebRTC media behind symmetric NAT or corporate firewalls.
69	UDP	TFTP Provisioning	LAN only	Direct (Bypass)	Legacy desk phone configuration and firmware downloads.
9061	UDP	HEP / Homer SIP Capture	Internal / Monitoring	Direct (Bypass)	Encapsulated SIP packet capture streaming for Homer VoIP monitoring.
5038	TCP	AMI (Asterisk Manager)	Localhost only (127.0.0.1)	Direct (Bypass)	Internal Asterisk management interface. NEVER expose to the internet.
3306	TCP	MariaDB Database	Localhost only (127.0.0.1)	Direct (Bypass)	Core PBX database. Bound to 127.0.0.1 only.

Ready-to-Use Firewall Rules

Firewall Script for UFW

#!/usr/bin/env bash
# AiPBX UFW Firewall Rules Setup
# Run with root privileges

set -euo pipefail

# 1. Reset or set baseline defaults
ufw default deny incoming
ufw default allow outgoing

# 2. Management & Web
ufw allow 22/tcp comment 'SSH Access'
ufw allow 80/tcp comment 'AiPBX Web Portal / HTTP-01'
ufw allow 443/tcp comment 'AiPBX Web Portal / HTTPS'

# 3. VoIP Signaling (MUST route directly to server)
ufw allow 5060/udp comment 'SIP Signaling UDP'
ufw allow 5060/tcp comment 'SIP Signaling TCP'
ufw allow 5061/tcp comment 'SIP-TLS Signaling TCP'

# 4. RTP Audio / Video Media Range (Direct UDP)
ufw allow 10000:20000/udp comment 'AiPBX RTP Media Streams'

# 5. WebRTC STUN / TURNS Relay
ufw allow 3478/udp comment 'STUN / TURN UDP'
ufw allow 3478/tcp comment 'STUN / TURN TCP'
ufw allow 5349/tcp comment 'TURNS TLS'

# 6. Internal Desk Phone Provisioning (Restrict to local subnet if desired)
# ufw allow from 192.168.1.0/24 to any port 69 proto udp comment 'TFTP Phone Provisioning'

# Enable firewall
ufw --force enable
ufw status verbose

Firewall Script for firewalld

#!/usr/bin/env bash
# AiPBX firewalld Rules Setup (RHEL, Rocky, AlmaLinux, Fedora)
# Run with root privileges

set -euo pipefail

# Standard Web & Management
firewall-cmd --permanent --add-service=ssh
firewall-cmd --permanent --add-service=http
firewall-cmd --permanent --add-service=https

# VoIP Signaling & Media (MUST bypass reverse proxy)
firewall-cmd --permanent --add-port=5060/udp
firewall-cmd --permanent --add-port=5060/tcp
firewall-cmd --permanent --add-port=5061/tcp
firewall-cmd --permanent --add-port=10000-20000/udp

# WebRTC STUN / TURN
firewall-cmd --permanent --add-port=3478/udp
firewall-cmd --permanent --add-port=3478/tcp
firewall-cmd --permanent --add-port=5349/tcp

# Reload rules
firewall-cmd --reload
firewall-cmd --list-all

Firewall Script for iptables

#!/usr/bin/env bash
# AiPBX iptables Stateful Firewall Rules
# Run with root privileges

set -euo pipefail

# Flush existing rules
iptables -F
iptables -X
iptables -t nat -F
iptables -t nat -X

# Default policies
iptables -P INPUT DROP
iptables -P FORWARD DROP
iptables -P OUTPUT ACCEPT

# Allow loopback
iptables -A INPUT -i lo -j ACCEPT

# Allow established and related connections
iptables -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

# SSH, HTTP, HTTPS
iptables -A INPUT -p tcp --dport 22 -j ACCEPT
iptables -A INPUT -p tcp --dport 80 -j ACCEPT
iptables -A INPUT -p tcp --dport 443 -j ACCEPT

# SIP Signaling (Direct)
iptables -A INPUT -p udp --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp --dport 5060 -j ACCEPT
iptables -A INPUT -p tcp --dport 5061 -j ACCEPT

# RTP Media Streams (Direct UDP)
iptables -A INPUT -p udp --dport 10000:20000 -j ACCEPT

# WebRTC STUN/TURN & WSS
iptables -A INPUT -p udp --dport 3478 -j ACCEPT
iptables -A INPUT -p tcp --dport 3478 -j ACCEPT
iptables -A INPUT -p tcp --dport 5349 -j ACCEPT

# ICMP ping
iptables -A INPUT -p icmp --icmp-type echo-request -j ACCEPT

Phone Settings

Reverse Proxy and Network Setup Guide

Open Source License & Telecom Disclaimer