Edge server

The Kamailio edge box is the only part of own-pbx that faces the internet. This page is its detailed reference — the step-by-step install lives on Installation.

#How it works

Remote phone --TLS 5061--> Kamailio --UDP 5060--> Asterisk (192.168.1.10, private)
RTP: phone <-SRTP, UDP 20000-20099-> rtpengine (same box) <-plain RTP, LAN-> Asterisk

• Kamailio terminates TLS, proxies SIP to Asterisk, and pins a Path header on REGISTER so inbound calls can find the phone again.
• Asterisk stays the registrar and the authenticator. Extensions are still managed entirely by the panel and API — no credential sync, no second user database on the edge.
• rtpengine relays the audio so NAT "just works", and terminates SRTP (SDES) on the internet leg. The LAN leg to Asterisk stays plain RTP — a trusted network, and zero Asterisk changes for encryption.
• The public surface is one TLS port. SIP scanners are UDP-based, so TLS-only kills ~99% of drive-by scanning before fail2ban even gets involved.

#What the installer sets up

The edge install on Installation takes about 10–15 minutes (rtpengine builds from source) and leaves you with:

• Kamailio — TLS-only on port 5061, with a flood limit.
• rtpengine — the audio relay that does the SRTP encryption, UDP 20000–20099.
• fail2ban — bans scanners and password guessers. Your own LAN is never banned.
• A firewall — nftables, default deny.
• An IP-follow timer — re-advertises your public IP every minute if it changes (see below).

#One more step, on the PBX

The edge needs support_path=yes on the phone AORs (that's what makes the Path header work). It's in the PBX's config template, so after installing the edge, re-deploy the PBX once:

cd /root/own-pbx && ./scripts/deploy.sh

This re-renders pjsip.conf and reloads. Phones re-register on their own; LAN phones keep working exactly as before.

#Certificates

#Real certificate via Cloudflare (recommended)

cd /root/kamailio
CF_Token=<Cloudflare API token with Zone → DNS → Edit> \
  ./get-cert-cloudflare.sh sip.example.com you@example.com

Uses Let's Encrypt with the Cloudflare DNS challenge (no port 80 needed), installs the certificate to /etc/kamailio/tls/, adds the domain as a Kamailio alias, and renews automatically.

#Replacing the certificate by hand

Already have a certificate pair (from any CA or tool)? Drop it in and restart:

cp fullchain.pem /etc/kamailio/tls/cert.pem
cp privkey.pem   /etc/kamailio/tls/key.pem
chmod 600 /etc/kamailio/tls/key.pem
systemctl restart kamailio

#If your public IP changes

Two things follow the IP automatically:

• DNS — on the PBX, Admin → Network: SIP domain plus a Cloudflare API token (Zone → DNS → Edit). The PBX checks every 1–15 minutes and updates the A record — always DNS only, TTL 60 s, because Cloudflare's proxy can't carry SIP/RTP.
• The edge itself — pbx-edge-ip.timer (installed by install.sh, or add it with ./update-public-ip.sh --install-timer) checks every minute and updates Kamailio's advertised address and rtpengine's SDP address, then restarts both. Without it, calls still connect after an IP change but have no audio.

Run it by hand any time with /root/kamailio/update-public-ip.sh (or pass the new IP). Logs: journalctl -u pbx-edge-ip. Expected downtime after a change: up to ~1 minute (detection) + the DNS TTL (60 s) + the phone's re-register interval — which is why phones away from home should re-register every 60–120 seconds.

#Updating the edge

Copy the new kamailio/ folder over /root/kamailio and run:

cd /root/kamailio && ./update-edge.sh

It re-renders kamailio.cfg from the new template (keeping your IPs and aliases), installs the fail2ban files and the alert hook — and rolls back by itself if the new config won't start. Usually you won't even do this by hand: pbx-update on the PBX updates the edge for you whenever the edge files changed (see Updating & maintenance).

#Verifying the edge

One command on the edge covers it:

cd /root/kamailio && PUBLIC_HOST=sip.example.com ./verify-edge.sh

It checks the services, the kamailio.cfg syntax, the TLS listener and handshake on 5061, the certificate's hostname and expiry, rtpengine's media ports, the nftables rules, the fail2ban jail, the UDP path to Asterisk, and whether your public IP still matches the advertised one. Green means go. Manual checks work too:

# on the edge
systemctl is-active kamailio rtpengine fail2ban
kamailio -c -f /etc/kamailio/kamailio.cfg   # config ok
tail -f /var/log/syslog | grep kamailio     # watch registrations

# on the PBX
asterisk -rx "pjsip show contacts"          # phone contact, with Path

Then register a phone remotely, call an extension both ways, and confirm two-way audio.

#Flood limit, fail2ban and alerts

• Flood limit: more than ~30 requests in 2 seconds from one IP is dropped and logged once as edge: flood from <ip>.
• Failed sign-ins: the edge logs edge: auth failed only when a phone actually sent a password and was refused — the normal first 401 challenge doesn't count, and stale nonces are ignored, so real users don't trip it by accident.
• Two fail2ban jails: kamailio-edge (scanners, failed sign-ins, junk: 8 in 10 minutes → 1-hour ban) and kamailio-edge-flood (one flood → 24-hour ban). List bans with fail2ban-client status kamailio-edge; lift one with fail2ban-client unban <ip>.
• Alerts: every ban and unban is sent to the PBX, which shows it in the dashboard Activity feed and emails the address under Email → Security alerts. One-time setup with an admin API key from the panel's API Keys page: pbx-edge-notify --setup http://<PBX-IP>:8001 <API key>.

More on the whole security model: Security.

#Files on the edge

Installed configuration lives in /etc/kamailio, /etc/rtpengine, /etc/fail2ban/jail.d and /etc/pbx-edge/notify.env.

#Edge troubleshooting

More problems and fixes: Troubleshooting.