How to Configure SIPdia with Asterisk (PJSIP)

SIPdia connects to a plain Asterisk server as a PJSIP endpoint. You need three sections in pjsip.conf for the extension (an endpoint, an auth and an AOR), at least one transport, and an RTP port range in rtp.conf. After pjsip reload, enter the server address, transport, extension number and password on SIPdia's Account page. The Asterisk configuration below is general guidance based on the official documentation; the SIPdia fields are verified against the app.

What you need before you start

• Root or sudo access to the Asterisk server, and the path to its configuration files (usually /etc/asterisk/).
• Asterisk 18 or 20 with res_pjsip loaded. Run asterisk -rx "module show like pjsip" to check.
• A dialplan context for internal calls. The example uses from-internal.
• For TLS: a certificate for the server's hostname, signed by a public certificate authority, plus its private key.

Configure the transport in pjsip.conf

A transport tells Asterisk which address, port and protocol to listen on. Add a UDP transport, and a TLS transport if you want encrypted signalling:

[transport-udp]
type=transport
protocol=udp
bind=0.0.0.0:5060

[transport-tls]
type=transport
protocol=tls
bind=0.0.0.0:5061
cert_file=/etc/asterisk/keys/pbx.example.com.crt
priv_key_file=/etc/asterisk/keys/pbx.example.com.key
method=tlsv1_2

Replace the certificate paths with yours. The certificate must match the hostname you will type into SIPdia's Server field, and it must chain to a public CA. SIPdia rejects self-signed certificates on macOS and iOS. If the server sits behind NAT, add external_media_address and external_signaling_address with the public IP, and local_net with the LAN range, as described in the Asterisk NAT documentation.

Transports are read when the module loads. After adding or changing one, do a full core restart rather than a reload.

Define the extension in pjsip.conf

Each extension needs an endpoint (how calls are handled), an auth (the credentials) and an AOR (where the device registered from). A minimal, working example for extension 1001:

[1001]
type=endpoint
context=from-internal
disallow=all
allow=ulaw
allow=alaw
allow=opus
auth=1001
aors=1001
dtmf_mode=rfc4733
direct_media=no
rtp_symmetric=yes
force_rport=yes
rewrite_contact=yes

[1001]
type=auth
auth_type=userpass
username=1001
password=change-this-to-a-long-random-secret

[1001]
type=aor
max_contacts=1
remove_existing=yes
qualify_frequency=60

What each option does:

1. disallow=all followed by allow= lines sets the codecs Asterisk will offer. SIPdia supports Opus, G.711 ulaw and G.711 alaw, so these three are the only ones worth listing. Drop opus if codec_opus is not installed.
2. dtmf_mode=rfc4733 matches how SIPdia sends keypad tones (RTP events). Older documentation calls this rfc2833; both names mean the same mechanism.
3. direct_media=no keeps audio flowing through Asterisk, which avoids problems when the two parties are on different networks.
4. rtp_symmetric=yes, force_rport=yes and rewrite_contact=yes make Asterisk send signalling and audio back to the address the packets actually came from. These three are what makes a softphone behind a home router work.
5. max_contacts=1 allows one registered device. Raise it if the same extension should ring on a Mac and an iPhone at the same time.
6. qualify_frequency=60 sends an OPTIONS ping every 60 seconds so pjsip show contacts shows whether the device is reachable.

To use TLS for this endpoint only, add transport=transport-tls to the endpoint section. Without it, Asterisk picks a transport based on the request.

Add SRTP

To encrypt the audio, add one line to the endpoint:

media_encryption=sdes

SDES exchanges the SRTP keys in the SDP body of the SIP messages, so it only makes sense together with TLS signalling. In SIPdia, set Transport to TLS and Encrypt audio to Required for that account. With media_encryption=sdes, Asterisk requires SRTP for the endpoint, so a SIPdia account with Encrypt audio set to Off would fail to get audio. Read TLS and SRTP for how the two protocols fit together.

Set the RTP port range in rtp.conf

Audio travels over RTP on UDP ports chosen from a range. Set it explicitly so you know what to open on the firewall:

[general]
rtpstart=10000
rtpend=20000

Open UDP 10000 to 20000 and the SIP port (UDP 5060, or TCP 5061 for TLS) between the devices and the server.

Reload and check the configuration

asterisk -rx "pjsip reload"
asterisk -rx "pjsip show endpoints"
asterisk -rx "pjsip show endpoint 1001"

pjsip show endpoints lists every endpoint with its state. Before the device registers it shows Unavailable. pjsip show endpoint 1001 prints the merged settings, which is the quickest way to spot a typo.

Enter the account in SIPdia

1. Open SIPdia, sign in, and go to Account.
2. Fill in the fields:
   • Server: the Asterisk hostname or IP address. Add :port if you bound the transport to a port other than 5060 (UDP or TCP) or 5061 (TLS).
   • Transport: UDP, TCP or TLS to match the transport you configured.
   • Username: 1001 (the endpoint and auth username).
   • Password: the value of password= in the auth section.
   • Display name: the name shown to other extensions.
3. Leave Domain, Outbound proxy and Auth username empty. SIPdia uses the Server value as the SIP domain and the Username as the auth username when these are blank. Fill in Auth username only if the auth section's username= differs from the endpoint name.
4. For TLS, set Encrypt audio to Required when the endpoint has media_encryption=sdes, otherwise leave it Off.
5. Click Save and Register (Mac) or Add and Register (iPhone).

Verify registration

In SIPdia the dot next to the account turns green when Asterisk answers 200 OK to the REGISTER request. On the server, confirm it with:

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

The contact should list the device's IP address and port, with a status of Avail once the first qualify has succeeded. If you see nothing, watch the SIP messages while SIPdia retries:

asterisk -rvvv
pjsip set logger on

A 401 Unauthorized followed by a second REGISTER and a 200 OK is normal: the first request has no credentials, the second one does. A 401 with no 200 OK means the password does not match; see SIP 401 Unauthorized. No request at all means the packets are not reaching Asterisk: check the port, the transport and the firewall. Turn the logger off with pjsip set logger off when you are done.

Place a test call

1. Make sure the from-internal context can reach something. A minimal extensions.conf test:

   [from-internal]
   exten => 600,1,Answer()
    same => n,Echo()
    same => n,Hangup()
   

   Run asterisk -rx "dialplan reload" after saving.

2. In SIPdia, open the Phone page and dial 600. You should hear your own voice echoed back. This proves two-way audio and the codec negotiation.

3. Create a second endpoint (for example 1002) and dial it from 1001. Add exten => _1XXX,1,Dial(PJSIP/${EXTEN},20) to the context so extensions can call each other.

4. During the call, press keypad digits. In the Asterisk console you should see DTMF events if dtmf_mode=rfc4733 is correct.

Troubleshooting

• Registration times out. Confirm the transport is bound (pjsip show transports) and that the firewall allows the port. On the Mac, allow SIPdia under System Settings > Privacy & Security > Local Network for a server on the LAN.
• One-way or no audio. Check rtp_symmetric, force_rport and rewrite_contact, open UDP 10000 to 20000, and set a STUN server and ICE in SIPdia when the device is outside a VPN. The one-way audio article walks through each cause.
• No matching codec. Asterisk logs No joint capabilities. Add allow=ulaw or allow=alaw to the endpoint; SIPdia does not support G.722 or G.729.
• TLS handshake fails. The certificate must be valid for the hostname in Server, not expired, and issued by a public CA. Check with openssl s_client -connect pbx.example.com:5061.

Security notes

Never leave UDP 5060 open to the whole internet without protection. Use long random passwords in every auth section, restrict the SIP port to known networks or a VPN, and run fail2ban against the Asterisk security log. Leave identify_by at its default (username,ip) unless you understand how a change affects which requests match the endpoint.

Next steps

• How SIP extensions work in Asterisk explains endpoints, auths and AORs in more depth.
• How to connect a softphone to an Asterisk PBX covers the client side for any softphone.
• Using a web panel instead of raw files? See the FreePBX and Issabel guides.