VMware ESXi and vSphere Cluster Management

Configuring SIP Peers with Asterisk sip.conf

Learn to configure legacy Asterisk chan_sip with sip.conf, define SIP peers, manage authentication and codecs, reload settings, and verify registration.

sip.conf configures Asterisk's legacy chan_sip channel driver. It controls SIP signaling behavior, global defaults, and configured SIP peers such as hardware phones and softphones.

Asterisk is an open-source PBX that routes calls and provides telephony features. SIP, or Session Initiation Protocol, is the signaling protocol used to establish, manage, and end voice or video sessions.

Prerequisites and configuration-file location

You should be familiar with basic Linux file editing, service privileges, IP networking, Asterisk dialplans and contexts, and the general idea of SIP registration.

The conventional location for the file is:

/etc/asterisk/sip.conf

If the file does not exist, create it with appropriate privileges:

sudo touch /etc/asterisk/sip.conf

Edit it with a privileged editor, for example by using sudoedit or an editor launched with suitable authorization. Keep ownership and permissions appropriate for the Asterisk service. Do not make the file broadly writable merely to avoid a permissions problem; configuration files can contain SIP credentials.

sip.conf syntax

The file is organized into sections. A section header is a name enclosed in square brackets, such as [general] or [bob].

  • Section names are case-sensitive.
  • Use names without spaces. Names such as [AlicePhone] and [alicephone] are different.
  • Settings use the form option=value.
  • An option applies to the section in which it appears until another section begins.
  • A semicolon starts a comment. Comments document intent and are ignored by the configuration parser.
; This comment explains the purpose of the section
[general]
context=public
allowguest=no

The [general] section

[general] is the top-level area for chan_sip settings and default endpoint behavior. A value in this section can be inherited by peers that do not define their own value.

Minimal global example

[general]
; Default dialplan destination for unauthenticated traffic
context=public

; Reject SIP requests that do not match an authenticated peer
allowguest=no

; Listen for SIP UDP traffic on every local IPv4 interface
udpbindaddr=0.0.0.0

; Do not enable SIP over TCP in this basic lab
tcpenable=no

The context value identifies the dialplan namespace used for unauthenticated traffic. A dialplan context is a namespace containing extensions and call-routing rules. With allowguest=no, Asterisk rejects guest calls rather than accepting unauthenticated SIP traffic.

udpbindaddr=0.0.0.0 tells chan_sip to listen on all local IPv4 interfaces. This can be convenient on a lab server with one trusted network interface, but it also exposes the SIP listener on every eligible interface. A more restrictive example binds to one address:

udpbindaddr=192.0.2.10

Use a specific interface when the PBX has multiple networks and SIP should be reachable only on one of them. Regardless of the binding choice, use firewall rules and network controls to limit untrusted access.

tcpenable=yes enables SIP signaling over TCP in chan_sip; tcpenable=no disables it. Enabling TCP does not automatically make every device use TCP. The phone, firewall, and Asterisk configuration must all support the chosen transport. Enable only transports required by the lab or deployment.

Core settings reference

Setting | Section | Purpose | Example value | Security or operational note

[general] | File section | Holds global chan_sip settings and defaults | [general] | Global changes can affect many peers.

context | [general] or peer | Selects the dialplan context for incoming traffic | public or local | Keep untrusted traffic in a restricted context.

allowguest | [general] | Controls unauthenticated guest calls | no | Disabling guest access is an important baseline.

udpbindaddr | [general] | Selects the local UDP listening address | 0.0.0.0 | All-interface binding increases exposure.

tcpenable | [general] | Enables or disables SIP over TCP | no | Enable only when required and permitted by network policy.

type | Peer section | Defines the legacy peer behavior | friend | Understand identification behavior before using it in production.

allow | Peer section or inherited setting | Lists codecs Asterisk may negotiate | ulaw,alaw | Codec choices affect bandwidth and transcoding.

secret | Peer section | Sets the shared SIP authentication credential | unique-secret | Use a strong, different secret for every endpoint.

host | Peer section | Defines how the endpoint address is handled | dynamic | Dynamic peers must register; fixed peers use a known address.

Defining SIP peers

A peer is a configured SIP device or remote SIP entity known to Asterisk. An endpoint is a SIP-capable phone, softphone, adapter, or other device that connects to the PBX.

Create a separate named section for each phone. This example defines two dynamically registering lab phones:

[bob]
type=friend
context=local
allow=ulaw,alaw
secret=replace-with-a-unique-strong-password
host=dynamic

[alice]
type=friend
context=local
allow=ulaw,alaw
secret=replace-with-a-different-unique-strong-password
host=dynamic

Each device uses its section name as its SIP identity, so the phone configured as bob must use the corresponding username and secret. The two secrets must be different. The example placeholders are not suitable production passwords.

Peer options

  • type=friend is a historical chan_sip peer type commonly used for phones that both place and receive calls. Asterisk may associate an inbound request with the peer using SIP identity information and/or network source details.
  • context=local places calls received from the identified peer into the local dialplan context. The context must exist in the dialplan and contain the required extensions.
  • secret is a shared authentication credential. Configure the same secret on the phone and in Asterisk, but use a strong, unique value for each endpoint.
  • host=dynamic is for devices that register and may receive different network addresses. Asterisk learns the current address from registration.
  • A fixed endpoint can instead use a known address, such as host=192.0.2.25. This is appropriate only when the endpoint has a stable, trusted address.

Codec allow lists

The allow option lists audio codecs that Asterisk may negotiate with a peer. In the example, ulaw is G.711 mu-law and alaw is G.711 A-law. Both are common PCM voice codecs.

Codec availability must align among the phone, the Asterisk build and loaded modules, and the other call leg such as another phone or a provider. If no common codec exists, the call may fail. Codec selection also affects bandwidth, interoperability, and whether Asterisk must transcode audio between different formats.

Inheritance and precedence

A peer can inherit a setting when it does not define that setting itself. A peer-specific value overrides an inherited value. The precedence sequence is:

Priority | Source of setting | Effect

1: individual peer section | A value written directly in [bob] or another peer section | Highest priority; it replaces inherited values.

2: peer section template | A value inherited from a reusable template | Supplies shared peer settings when the peer has no override.

3: [general] section | A global default | Applies when neither the peer nor its template specifies the option.

4: built-in chan_sip default | The driver's internal fallback | Used only when no configuration value is available.

Templates are reusable configuration sections for shared peer settings. They are useful when many phones need the same codecs, transport, or other defaults. A peer-specific option still takes precedence over a template.

Peer override example

[general]
context=public

[bob]
type=friend
context=local
host=dynamic

The global context is public, but calls associated with bob enter local because the peer section overrides the global value. The same rule applies to codec settings: an allow value inside a peer section replaces an inherited codec list for that peer.

Apply changes through the Asterisk CLI

Saving sip.conf does not necessarily make its settings active. Attach to an already running Asterisk process and reload chan_sip:

asterisk -rvvv
sip reload

The -r option attaches to the active Asterisk instance. The additional v flags increase console verbosity. The sip reload command reloads the chan_sip configuration after the file has been saved.

Attaching with asterisk -rvvv is different from starting Asterisk. It connects to an existing process through the Asterisk control interface; it does not launch a second PBX process. Review parsing messages and investigate any errors before testing phones.

Verify peers and registration

From the Asterisk CLI, list the configured peers:

sip show peers

The output should include bob and alice. A peer can be configured correctly yet remain offline, unavailable, or unregistered until a phone has been configured and successfully registered.

Observed state | Likely interpretation | First checks

Online or reachable | Asterisk knows the peer's current address and can reach it | Confirm the phone remains registered and check network stability.

Offline or unavailable | The peer is loaded, but its device is not currently reachable or registered | Check the phone, registrar address, SIP port, firewall, NAT, and transport.

Unregistered | A dynamic peer has no current registration | Verify the endpoint username, secret, server address, and registration setting.

Authentication failure | The device attempted registration or a call but credentials did not match | Compare the peer name and secret on both sides; use a unique strong secret.

The next lab step is to configure two SIP clients using the identities bob and alice, register them to the PBX, and run sip show peers again.

Troubleshooting

CLI cannot connect to Asterisk

A message about being unable to connect to the remote Asterisk instance or control socket commonly means that Asterisk is stopped, the socket path differs from the expected path, the invoking user lacks permission, or SELinux is blocking access.

  1. Check whether the service is running:
systemctl status asterisk
  1. Confirm that the expected control socket exists, then inspect its ownership and permissions.
  2. Attach as an appropriately authorized user or correct the service's socket configuration and permissions using least privilege.
  3. On an SELinux-enabled system, inspect the enforcement mode:
getenforce

SELinux is a mandatory access control system. It can deny access to service files or sockets even when traditional Unix ownership and mode bits appear correct. Review recent audit denials:

sudo ausearch -m AVC -ts recent

Use the audit details to apply a targeted policy correction or correct file labeling. Do not permanently disable SELinux as the normal solution. Temporarily switching to permissive mode can help isolate whether SELinux is involved during controlled diagnosis, but it is not a production fix and should be restored immediately after testing.

Peer remains offline or unavailable

  • Verify that the phone or softphone is configured to register.
  • Check the PBX address, SIP username, password, and selected transport.
  • Confirm network reachability and firewall rules for the SIP listener.
  • Consider NAT issues when the client and PBX are on different networks.
  • Review Asterisk logs and verbose CLI output for registration attempts.

Correct the endpoint and network settings, then register the device again. Reload sip.conf only when the server-side configuration changed.

Calls enter the wrong dialplan context

If a phone registers but calls do not reach the expected extensions, inspect the peer's context. A missing peer-specific value can cause the peer to inherit the global context. Also verify that the referenced context exists and contains the requested extension. Verbose CLI output can show where the incoming channel enters the dialplan.

No compatible audio codec

Compare the phone's codec settings with the peer's allow list, the capabilities of the other call leg, and the codecs available in the Asterisk installation. Align the lists or enable a supported codec while considering bandwidth and transcoding requirements.

Security and operational checklist

  • Use allowguest=no unless unauthenticated traffic is explicitly required and isolated.
  • Use a restricted dialplan context for untrusted or externally reachable traffic.
  • Give every peer a different, strong secret.
  • Bind UDP to a specific interface when listening on all interfaces is unnecessary.
  • Enable TCP only when the devices and network require it.
  • Use firewall rules to limit SIP access to known networks where practical.
  • Keep ownership and permissions on /etc/asterisk/sip.conf suitable for the Asterisk service.
  • Remember that chan_sip configuration is legacy; evaluate PJSIP for new deployments and migration work.

Summary

sip.conf is the legacy configuration file for chan_sip. The [general] section supplies global behavior such as the default context, guest-call policy, UDP binding, and TCP transport. Named peer sections define phones, their authentication credentials, address behavior, codecs, and dialplan contexts.

After editing the file, attach to the running Asterisk CLI, run sip reload, and inspect sip show peers. A loaded peer is not necessarily registered. If the CLI cannot attach, check the service, control socket, permissions, and SELinux audit records before changing security controls.

Related lesson: Configuring SIP peers with sip.conf.