Extension Management

Extensions connect agents, devices, or bots to RustPBX. This chapter covers creation, bulk administration, and protection controls.

1. Extension model

• Core fields: number, display name, department, SIP password or certificate bundle.
• Policy fields: concurrency limit, outbound permissions, media parameters (DTMF mode, RTP ports, codec order).
• Related objects: queues, billing templates, and frequency limits (models/frequency_limit.rs).

2. Creating an extension

1. Console → Extensions → Create.
2. Fill basic information and select an authentication method:
   • Password: auto-generate or manually supply a strong secret.
   • Certificate: pair with WebRTC clients.
3. Configure calling permissions—black/white lists and domestic vs. international dialing policies.
4. Save and distribute the credentials to the assigned device.

File / script import

For bulk onboarding, call the API or insert rows that match models/extension.rs, then refresh caches.

3. Registration & devices

• SIP softphones: enter server address, extension, and password; import certificates when TLS/SRTP is required.
• JWT-based registration: extensions can register without a password by presenting a JWT token in the X-Auth-Token SIP header or ?token= WebSocket query parameter. See Section 5 for details.
• Desk phones: use auto-provision templates or manual configuration; restrict allowed IP ranges.
• WebRTC clients: leverage static/phone_jssip.html or phone_sipjs.html samples to establish secure browser sessions.

4. Extension Lifecycle Hooks

Since v0.4.10, addons can hook into extension lifecycle events — create, update, and delete — through the Addon::on_extension_created, on_extension_updated, and on_extension_deleting trait methods. These hooks run automatically whenever extensions are modified via the console, API, or CSV import.

Voicemail addon example: when the voicemail addon (addon-voicemail) is enabled, creating an extension automatically creates a corresponding voicemail mailbox. Deleting an extension automatically deletes the mailbox and its recorded messages. No separate mailbox provisioning step is required.

Errors in addon hooks are logged but do not block the extension operation.

5. JWT-based authentication

Extensions can register without a SIP password using JWT tokens. When [proxy.jwt_auth].enabled = true, the proxy checks for a JWT in the X-Auth-Token SIP header (or ?token= query parameter on WebSocket). If the JWT is valid and the user_id_claim matches an extension number, registration proceeds without a digest challenge.

JWT auth also supports a pre-auth registry: once an extension is authenticated via JWT, the proxy stores a short-lived binding so that subsequent in-dialog requests (BYE, re-INVITE, ACK) are fast-tracked without re-validation.

For WebSocket clients, include the token as a query parameter:

wss://<host>:<ws_port>/ws?token=<jwt>

JWT-based registration is ideal for voice agents, automated dialers, and browser-based WebRTC softphones where managing SIP passwords per extension is impractical.

6. Security & limits

• Frequency limits: define policies in models/frequency_limit.rs, attach them via the console to mitigate abusive dialing.
• ACL: coordinate with config/acl/ to restrict IP or network access.
• Login alerts: enable failed-login alerts in Diagnostics; spike detection can auto-block offending IPs.

7. Operational routines

8. Common issues

• Cannot register: verify password, proxy port, device clock, TLS certificate, and ACL rules.
• Call fails: confirm routing rules allow the extension to dial out and ensure frequency limits were not tripped.
• Poor audio: lower codec complexity, enable QoS on the device, or move the media server closer to the user.

Applying these practices keeps extensions secure, observable, and aligned with routing/queue policies.