Asterisk

Builds and installs Asterisk (open-source PBX/telephony engine) from source, and configures PJSIP endpoints, outbound trunks, and a basic dialplan.

Requirements

• Debian/Ubuntu host (builds Asterisk from source; installs build prerequisites via contrib/scripts/install_prereq)

Variables

Variable	Default	Description
asterisk_version	23.4.1	Version of the Asterisk source tarball to download and build.
asterisk_data_dir	/var/lib/asterisk	Directory where Asterisk stores its data (sounds, agi-bin, keys, AstDB).
asterisk_menuselect_enable	[]	Menuselect options to force-enable before compiling.
asterisk_menuselect_disable	[]	Menuselect options to force-disable before compiling.
asterisk_endpoints	[]	SIP endpoints (e.g. desk phones) that register in. See Endpoints below.
asterisk_trunks	[]	Outbound SIP trunks this instance registers to. See Trunks below.
asterisk_outbound_trunk	""	Trunk used for outbound (endpoint-originated) calls when more than one is defined. Default: first entry in asterisk_trunks.
asterisk_codecs	[ulaw, alaw, g722]	Codecs offered/accepted, in priority order.
asterisk_local_nets	RFC1918 ranges	CIDR ranges PJSIP treats as not behind NAT for address rewriting purposes.
asterisk_external_address	""	Public IP/hostname advertised in SIP/SDP. Required whenever an endpoint or trunk crosses a NAT boundary.
asterisk_udp_bind	0.0.0.0:5060	Bind address:port for the UDP PJSIP transport.
asterisk_tls_enabled	false	Enables the TLS PJSIP transport, needed for phones registering over an untrusted network.
asterisk_tls_bind	0.0.0.0:5061	Bind address:port for the TLS PJSIP transport.
asterisk_tls_cert_file	""	Cert file path for the TLS transport. Required if asterisk_tls_enabled: true.
asterisk_tls_priv_key_file	""	Private key path for the TLS transport. Required if asterisk_tls_enabled: true.
asterisk_rtp_start	10000	Start of the RTP port range. Forward this range through any firewall/NAT for media to traverse it.
asterisk_rtp_end	20000	End of the RTP port range.
asterisk_user_agent	""	Overrides the SIP User-Agent header PJSIP sends. Empty means don't override.
asterisk_logrotate_keep	14	Number of rotated logs to keep for /var/log/asterisk/full and queue_log.
asterisk_uninstall	false	Uninstalls Asterisk instead of setting it up.
asterisk_prune	false	Also removes /etc/asterisk, logs, spool, cache, and asterisk_data_dir on uninstall. Requires asterisk_uninstall: true. Irreversible.

Usage

Minimal setup - one desk phone, one outbound/inbound trunk:

asterisk_endpoints:
  - id: "100"
    password: "{{ vault_deskphone_password }}"
    callerid: "Front Desk <100>"

asterisk_trunks:
  - name: my-provider
    host: sip.provider.example
    username: "1000"
    password: "{{ vault_trunk_password }}"
    caller_id: "+15551234567"
    dids:
      - number: "+15551234567"
        destination: "100"

asterisk_external_address: 203.0.113.10

Endpoints

asterisk_endpoints is a list of SIP endpoints (e.g. desk phones) that register directly to this Asterisk instance.

Field	Description
id	Extension/endpoint id, used as the SIP username. Required.
password	Registration password. Required, should be vault-encrypted by the caller.
callerid	Caller ID presented on internal calls. Default: id.
context	Dialplan context. Default: internal (extension-to-extension dialing plus the outbound trunk catch-all).

asterisk_endpoints:
  - id: "100"
    password: "{{ vault_deskphone_password }}"
    callerid: "Front Desk <100>"

Trunks

asterisk_trunks is a list of registrar-based outbound SIP trunks. Each entry runs its own outbound registration and gets a dedicated [from-<name>] dialplan context for its inbound DIDs.

Field	Description
name	Trunk name. Required.
host	Trunk SIP server hostname/IP. Required.
port	Trunk SIP server port. Default: 5060.
username	Registration username. Required.
password	Registration password. Required.
auth_username	Auth username, if different from the registration username. Default: username.
caller_id	Account's real presentable phone number, used for outbound From/PAI identity. Default: username - registering fine doesn't mean username is a valid Caller ID, and providers commonly blank an unrecognized presented number to "anonymous".
from_domain	Domain part of that From identity. Default: host.
dids	Inbound numbers mapped to an asterisk_endpoints id - see below.

Each dids entry:

Field	Description
number	Inbound number exactly as the provider sends it in the INVITE (bare national digits, E.164 with +, or something else - varies by provider). A format mismatch here means calls arrive but nothing rings, with no error anywhere. Required.
destination	asterisk_endpoints id to ring for this number. Required.

asterisk_trunks:
  - name: my-provider
    host: sip.provider.example
    port: 5060
    username: "1000"
    password: "{{ vault_trunk_password }}"
    caller_id: "+15551234567"
    dids:
      - number: "+15551234567"
        destination: "100"

Uninstall

To uninstall Asterisk:

asterisk_uninstall: true

To also remove all config, logs, spool, cache, and data (irreversible):

asterisk_uninstall: true
asterisk_prune: true