How to Configure a SIP Extension in FreePBX

To add a SIP extension in FreePBX, go to Applications > Extensions, click Add Extension, choose Add New SIP [chan_pjsip] Extension, fill in the User Extension, Display Name and Secret, review the Advanced tab, click Submit and then Apply Config. Before handing the details to a user, confirm the PJSIP port and codecs under Settings > Asterisk SIP Settings and open the firewall for SIP and RTP. This tutorial covers the administrator's side. For entering the extension in SIPdia, see How to configure SIPdia with FreePBX.

FreePBX is an open source web interface for Asterisk maintained by Sangoma. Most fields on the extension page map to an option in Asterisk's PJSIP configuration, so if you know the Asterisk option names you will recognise them here. Menu names can vary a little between FreePBX 15, 16 and 17; the FreePBX documentation describes each release.

Before you start

• Administrator access to the FreePBX web interface.
• A numbering plan for extensions that avoids feature codes and outside numbers.
• Knowledge of where the phones will connect from: the office LAN, a VPN, or the internet.

Step 1: Check the PJSIP transport and port

1. Go to Settings > Asterisk SIP Settings.
2. Open the SIP Settings [chan_pjsip] tab.
3. In the Transports section, make sure the UDP transport is enabled on 0.0.0.0 port 5060 (or whatever your site uses). Enable TCP or TLS only if you need them. TLS requires a certificate from Admin > Certificate Management; phones such as SIPdia accept it only when it comes from a public certificate authority.
4. Note the ports. If chan_sip is still enabled on this system, it uses 5160 by default, which is a frequent source of confusion.

The SIP port reference lists the standard values.

Step 2: Set global codecs and NAT

Still under Settings > Asterisk SIP Settings, open the General SIP Settings tab:

1. Audio Codecs: enable ulaw and alaw. Enable opus if the codec module is installed and your phones support it. Disable codecs none of your devices use; fewer codecs mean faster negotiation.
2. NAT Settings: set External Address to the public IP or hostname of the server, and add every internal subnet under Local Networks. Click Detect Network Settings to fill them in automatically, then check the result.
3. RTP Port Ranges: the default is 10000 to 20000. Note it for the firewall.

Click Submit, then Apply Config.

Step 3: Add the extension

1. Go to Applications > Extensions.
2. Click Add Extension and choose Add New SIP [chan_pjsip] Extension.
3. On the General tab:
   • User Extension: for example 1001.
   • Display Name: the user's name.
   • Outbound CID: optional caller ID for external calls.
   • Secret: FreePBX generates a long random secret. Keep it. Short secrets get brute-forced.
4. On the Voicemail tab, enable voicemail and set a PIN if the user needs a mailbox.
5. On the Advanced tab, check these options:
   • Max Contacts: 1 for one device, more if the user registers several phones on the same number.
   • Remove Existing: Yes, so a re-registering phone replaces its old contact instead of being refused when the limit is reached.
   • DTMF Signaling: RFC 4733 (shown as RFC 2833 in older versions).
   • Direct Media: No, so audio always passes through Asterisk.
   • Rewrite Contact, Force rport, RTP Symmetric: Yes. These three let phones behind NAT work; the Asterisk NAT documentation explains each one.
   • Transport: Auto, or the specific transport for this phone.
   • Media Encryption: None, or SRTP via in-SDP when the phone uses TLS and you want encrypted audio.
   • Qualify Frequency: 60 seconds, so FreePBX can show whether the phone is reachable.
6. Click Submit.
7. Click the red Apply Config button. FreePBX writes pjsip.endpoint.conf, pjsip.auth.conf and pjsip.aor.conf and reloads Asterisk.

Step 4: Open the firewall

FreePBX includes a firewall module under Connectivity > Firewall:

1. Add the networks your phones use to the Trusted or Local zone.
2. Turn on Responsive Firewall if remote phones connect from changing addresses. Unknown addresses may try to register a few times before being blocked.
3. Keep intrusion detection (fail2ban) enabled. Depending on the version it lives under Admin > System Admin > Intrusion Detection or in a tab of the Firewall module.

On any router or cloud firewall in front of the server, allow the SIP port (UDP 5060 or your TLS port) and UDP 10000 to 20000 for RTP from the phone networks only.

Step 5: Review feature codes

Open Admin > Feature Codes. Defaults include *72/*73 (Call Forward All), *90/*91 (Call Forward Busy), *52/*53 (Call Forward No Answer), *78/*79 (DND) and *97 (My Voicemail). Phones with forwarding or DND buttons dial these, so if you change them, update the phones too.

Step 6: Register a phone and verify

1. Give the user the server address, port, transport, extension number and secret. For SIPdia, point them to How to configure SIPdia with FreePBX.
2. Check the registration in Reports > Asterisk Info, or on the console:

asterisk -rx "pjsip show contacts"
asterisk -rx "pjsip show endpoint 1001"

The contact should show the phone's IP address and Avail. 3. If it does not appear, watch the SIP exchange:

asterisk -rvvv
pjsip set logger on

401 then 200 OK is success. 401 only means a wrong secret. No request at all means the phone's packets never arrived: wrong port, wrong transport or firewall. The registration troubleshooting article lists the checks in order.

Step 7: Make a test call

1. From the phone, dial *97 and enter the PIN. If the prompt reacts to digits, DTMF works.
2. Call another extension and confirm audio in both directions.
3. Call the new extension from another phone and confirm it rings with the right Display Name.

Common mistakes

• Applying was skipped. The extension exists in the database only.
• Wrong port. The phone uses 5060 but the site moved PJSIP, or the phone is pointed at the chan_sip port 5160.
• No Local Networks. Remote phones register but have one-way audio.
• Codec mismatch. The phone supports only G.711 or Opus while the site allows only G.722 or G.729.
• Responsive Firewall block. After several failed attempts with a wrong secret, the phone's address is blocked for a while. Fix the secret, then clear the block.

Next steps

• Register SIPdia on the extension: How to configure SIPdia with FreePBX.
• Learn what FreePBX wrote behind the scenes: How SIP extensions work in Asterisk.