FreePBX Setup & Troubleshooting Guide

Condensed reference covering trunk setup (IAX2), extensions, ring groups, call recording, music on hold, and common troubleshooting scenarios. All secrets, phone numbers, and IPs below are placeholders — replace before use.

1. Install¶

FreePBX 13 on CentOS 7 — see official install docs: https://wiki.freepbx.org (search "Installing FreePBX on CentOS 7" for current version).

2. IAX2 Trunk Setup (Generic VoIP Provider Pattern)¶

This pattern applies to any IAX2 provider (e.g. voip.ms) — adjust host/credentials per provider.

Connectivity → Trunks → Add Trunk → Add IAX2 Trunk
- Trunk Name: <provider>-out
- CallerID: <Your Name>

Outgoing settings (Peer Details)¶

username=<username>
type=peer
secret=<secret>
nat=yes
qualify=yes
insecure=very
host=<provider_host>
dtmfmode=rfc2833
disallow=all
allow=gsm&alaw&ulaw

Incoming settings (User Details)¶

USER Context: <provider>-in

username=<username>
type=friend
secret=<secret>
qualify=yes
requirecalltoken=no
insecure=port,invite
host=<provider_host>
disallow=all
allow=ulaw
context=from-trunk

Registration string¶

<username>:<secret>@<provider_registrar_host>

Submit → Apply Config.

Outbound route¶

Connectivity → Outbound Routes → Add Route
Route Name: <provider>-out
Trunk Sequence: the trunk created above
Dial Patterns: Dialplan Wizard → select all standard dial plans → Generate Routes

Inbound route¶

Connectivity → Inbound Routes → Add Incoming Route
Description: <provider>-in
Set Destination: target extension or ring group (see below)

Verify trunk status¶

asterisk -rvvvvvvvvvvvvvvvvvv
*CLI> iax2 show peers

Expect OK (n ms) for each configured peer; UNREACHABLE indicates a dead/misconfigured trunk.

3. FreePhoneLine-Style SIP/Peer Trunk (Alternate Provider Pattern)¶

Some residential VoIP providers (e.g. FreePhoneLine) use a peer-type trunk rather than IAX2 friend/peer split. General shape:

Outgoing settings

username=<your_did_number>
type=peer
secret=<secret>
nat=yes
insecure=very
host=<provider_host>
disallow=all
allow=gsm&alaw&ulaw
dtmfmode=rfc2833

Incoming settings

USER Context: <provider>-in
username=<your_did_number>
type=peer
secret=<secret>
nat=yes
insecure=very
host=<provider_host>
disallow=all

Registration string

<did_number>:<secret>@<provider_host>/<did_number>

Outbound route dial patterns — add via Dialplan Wizard:
- Local 7/10 digit
- Toll free
- Long distance
- International
- Emergency

Inbound route — set Description and DID Number, point Destination at an extension or ring group.

4. Create an Extension¶

Applications → Extensions → Add Extension → Generic SIP Device

User extension: <ext_number>
Display name: <Name>

Device options
- Secret: <generate a strong secret>
- NAT: yes

Recording options
- On Demand Recording: enabled

Voicemail
- Status: enabled
- Voicemail password: <4-digit PIN>
- Email address: <destination_email>
- Email attachment: yes
- Play CID / Play Envelope: yes

Submit → Apply Config.

5. Ring Groups¶

Applications → Ring Groups → Add Ring Group
- Ring strategy: ringall (or preferred strategy)
- Extension list: one extension per line — external numbers can also be added (format: <number>#)
- Destination if no answer: typically voicemail on a primary extension
- Record calls: On Demand

If an inbound route currently points at a single extension, redirect its Destination to the ring group instead once created.

6. Admin Password Reset (CLI)¶

Useful if locked out of the web admin.

echo -n '<new_password>' | sha1sum

mysql asterisk
update ampusers set password_sha1 = '<sha1_hash>' where username = '<admin_username>' limit 1;
select username from ampusers;   -- to list existing admin users

After logging back in, reset the AMP (Asterisk Manager Password) from the GUI as well to fully restore consistency.

7. Call Recording¶

Enable feature code
- Admin → Feature Codes → "In-Call Asterisk Toggle Call Recording" (*1) → Enabled

Dial options
- Settings → Advanced Settings
- Asterisk Dial Options: TtrwW
- Asterisk Outbound Trunk Dial Options: TtwW

Per-extension
- Applications → Extensions → select extension → On Demand Recording: Enable

Trigger a recording: press *1 during a call.

Retrieve recordings:

/var/spool/asterisk/monitor/YYYY/MM/DD/*.wav

Known issue: if MixMonitor logs a "No such format" error with garbled characters instead of a proper extension, this is a longstanding Asterisk ticket (search "app_mixmonitor no such format" on the FreePBX/Asterisk trackers) rather than a local misconfiguration.

8. Custom Music on Hold¶

cd /var/lib/asterisk/moh
mkdir archive
mv * archive

Then upload the custom file via the FreePBX GUI. Note: there's no built-in "priority" mechanism to prefer a custom file over defaults — moving defaults aside is the practical workaround. Also confirm PHP upload limits are large enough:

; /etc/php.ini or /etc/php5/apache2/php.ini
upload_max_filesize = 20M
post_max_size = 50M

Restart the web server / reboot after changing.

9. Troubleshooting Log¶

"No compatible codecs, not accepting this offer!"¶

Add explicit codec allowances to the trunk's Peer Details:

allow=gsm&alaw&ulaw
dtmfmode=rfc2833

Inbound caller doesn't hear ringback¶

Usually a music-on-hold class issue tied to the ring group method (RingGroupMethod=ringallv2). Check for a deleted default system sound for incoming ringback and confirm it was properly restored — a partial restore is a common cause even after files are put back.

No incoming calls (unknown peer rejection)¶

Log shows the call landing in from-sip-external and getting rejected with "no service" / congestion tones for an unrecognized peer. Indicates the inbound trunk's host/context isn't matching — verify the trunk's incoming context and host match what the provider is actually sending from.

No audio on inbound or outbound calls¶

Retransmission timeout reached ... no reply to our critical packet

Classic SIP retransmission/NAT traversal symptom — check firewall/NAT rules for the RTP port range and SIP signaling ports, and confirm nat=yes is set where appropriate.

Registration times out repeatedly¶

Registration for '<number>@<provider>' timed out, trying again

Checklist:
1. Confirm outbound connectivity to the provider isn't blocked by an upstream firewall or ISP (test with sipsak -v -v -s sip:<provider_host> — a valid 200 OK response confirms reachability).
2. Add qualify=yes to the trunk even if it wasn't previously required — providers can start enforcing keepalive checks.

"All circuits are busy now"¶

Often resolved by setting NAT = No on the affected extension(s) rather than Yes, counter to the usual default.

File upload fails for music on hold¶

PHP Warning: POST Content-Length of <n> bytes exceeds the limit of <n> bytes

Increase post_max_size in php.ini (see MOH section above) and restart the web service.

10. ATA / Device Notes¶

Linksys PAP2T¶

Factory reset:
1. Plug in power, connect a phone to Phone 1 port
2. Dial **** → "Configuration Option Menu"
3. Dial 73738# (spells "RESET#")
4. Press 1 to confirm

Reset to defaults (alternate): **** then 110#

Remote syslog (for debugging):
- Admin login → System tab → Advanced View → set Syslog Server / Debug Server to your logging host, Debug Level 3
- Line 1 / Line 2 tabs → Advanced View → SIP Debug Option: full

Aastra 6731i¶

No specific config notes captured yet — placeholder for future documentation.

11. Outstanding / Not Yet Documented¶

Aastra 6731i device configuration
NCID (Network Caller ID) integration — noted as worth evaluating, not yet implemented