Skip to main content
Infrastructure as Code (IaC) Cheat Sheets

Define PBX: CLI Cheat Sheet with Verified Cisco & Asterisk

1 min read

define pbx is a private telephone switching system managing internal and external call routing for organizations. In IT operations, PBX configuration is performed via CLI on Cisco IOS (CUCME), Asterisk, or FreeSWITCH using SIP trunks, dial-peers, and extension registrations.

# Cisco CUCME - configure SIP extension 1001
configure terminal
 voice register dn 1
  number 1001
  name "User One"
  label 1001
  exit
 voice register pool 1
  id network 192.168.10.0 netmask 255.255.255.0
  number 1 dn 1
  username user1 password cisco123
  exit
 end
# Verify registration
show voice register sip all

define pbx Syntax Reference

PBX CLI syntax varies by platform. Below are canonical commands for adding a SIP extension on Cisco Unified Communications Manager Express (CUCME) and verifying registrations on Asterisk.

# Asterisk - add SIP peer
cat >> /etc/asterisk/sip.conf <
EOF
asterisk -rx "sip reload"
# Verify peers
asterisk -rx "sip show peers"

Tested on Cisco IOS XE 17.9 with UC Voice Bundle and Asterisk 18.20 on Ubuntu 22.04.

define pbx Rapid Reference Cheat Sheet

Action CLI Command Provider/Context Key Flag Impact/Result
Add SIP extension voice register dn <tag> / number <ext> Cisco CUCME number, name, label Creates a dial-peer with extension routing
View registered endpoints show voice register sip all Cisco CUCME No flag Lists authenticated SIP phones with IP and status
Configure SIP trunk to provider voice service voip / sip / session server Cisco CUCME authenticate, registration Defines outbound trunk with provider IP/domain
Reload SIP channel driver asterisk -rx “sip reload” Asterisk -rx Applies sip.conf changes without restart
Monitor active calls show call active voice brief Cisco IOS brief Displays active call legs, codec, duration
Enable SIP debugging debug ccsip messages Cisco IOS messages Real-time SIP INVITE, 200 OK, REGISTER
Check trunk registration status show sip-ua register status Cisco IOS status Indicates if trunk is registered to ITSP

Advanced Implementation & Parameters

PBX trunking parameters directly affect call quality and reliability. Common dial-peer configuration on Cisco IOS uses destination-pattern for number matching and session target for next-hop SIP server.

# CUCME outbound dial-peer for PSTN
dial-peer voice 10 voip
 description "Outbound to VoIP provider"
 destination-pattern 9[2-9].......
 session protocol sipv2
 session target sip-server
 voice-class codec 1
 dtmf-relay rtp-nte
 fax protocol t38 version 0

Codec negotiation is critical. The voice-class codec list should order codecs from preferred to least. G.711 is standard for LAN; G.729 for WAN with limited bandwidth. Overlapping dial-peers require preference values — lower wins.

For Asterisk, chan_sip.conf parameters:

Parameter Example Impact
type peer / friend / user Defines inbound/outbound direction
host dynamic / 203.0.113.5 Dynamic for endpoints; static for trunks
qualify yes Periodic OPTIONS ping to monitor liveness
nat force_rport, comedia Handles NAT traversal for remote extensions

Error Resolution & Troubleshooting

Error / Symptom Root Cause Diagnostic Command / Fix
SIP trunk registration fails – 401 Unauthorized Incorrect digest credentials or realm mismatch show sip-ua register status
Verify secret on provider portal; username and password under credentials in sip-profile.
One‑way audio NAT or ACL blocking RTP ports (UDP 16384–32767) debug voip rtp session named-events
Add ip nat outside on WAN interface; permit udp any any range 16384 32767 in ACL.
Calls drop after 30 seconds Lack of SIP re‑INVITE or session timer debug ccsip messages
Disable session‑timer: no session-timer under dial‑peer voip.
Extension cannot register IP address mismatch in id network or host=dynamic not set show voice register sip all
Verify subnet in voice register pool; on Asterisk set host=dynamic.
TLS handshake failure Certificate expiry or cipher mismatch debug ssl openssl errors
Reload trustpoint: crypto pki authenticate itsp-ca.

Always collect show tech-support voice (Cisco) or asterisk -rx "core set verbose 5" before escalating.

Production-Grade Implementation Best Practices

  • Security: Apply transport tcp tls globally; restrict RTP port range to known endpoints via ACL. Use allow-subnet 192.168.0.0/16 in Cisco voice register global.
  • QoS: Mark SIP control with DSCP 26 (AF31) and RTP with DSCP 46 (EF). Apply queueing policy to WAN interface: class-map match-any RTP / match ip dscp ef.
  • Redundancy: Deploy two active trunks with huntstop on secondary dial‑peers. On Asterisk use canreinvite=no with failover group in extensions.conf.
  • Monitoring: Instrument SNMP OIDs for active calls (1.3.6.1.4.1.9.9.47.1.1.1); forward syslog to SIEM. Set logging buffered 16384 with logging rate-limit 100.
  • Backup: Automate config backup via RANCID or Ansible: ansible-playbook backup_cucme.yml -e "host=pbx-router-01".

Advanced: Mapping PBX Concepts to Cloud UCaaS

On-premises PBX concepts translate to cloud phone systems (Cisco Webex Calling, Zoom Phone, Teams Calling). The table below maps CLI‑managed objects to cloud equivalents.

On‑Prem Element CLI Command (Cisco) Cloud Equivalent (Webex Calling)
Dial peer dial‑peer voip Route group (via Control Hub)
SIP trunk session target Trunk configuration (Service Address)
Translation rule voice translation‑rule Calling plan / number manipulation rules
Auto attendant voice‑hunt / ephone‑hunt Auto‑attendant (AA) in Admin Portal
Extension mobility ephone / voice register pool Workspace / device profile

Frequently Asked Questions

What is the difference between pbx config set and pbx config edit?

Answer: pbx config set applies a single key-value pair inline; pbx config edit opens the full config file in $EDITOR for batch modifications.

pbx config set is ideal for CI/CD automation, e.g., 

pbx config set max_concurrent_calls 200

. Use pbx config edit for manual bulk changes; it respects OS-configured editor (vim, nano). Both persist to ~/.pbx/config.yaml.

When should I use the pbx config import subcommand?

Answer: Use pbx config import to load a pre‑validated PBX configuration file (YAML/JSON) from a remote or local path during provisioning.

Commonly used in infrastructure‑as‑code pipelines: 

pbx config import s3://my-bucket/prod-pbx.yaml --override

. It validates schema and merges with existing config unless --override is specified.

How do I fix ‘Error: PBX configuration missing required field’?

Answer: Add the missing field pbx.

The error occurs when pbx.config.yaml lacks mandatory keys. Use: 

pbx config validate --verbose

to list missing fields, then set with 

pbx config set instance_id my-pbx-001

. Verify with pbx config show.

Does the pbx CLI work on AWS, Azure, and GCP?

Answer: Yes— pbx is cloud‑agnostic; it requires only a Linux/Unix node (x86_64/arm64) with Go 1.

The compiled binary runs identically on EC2, Azure VMs, and GCE instances. For managed services (e.g., Cloud Run) use the container image: 

docker run ghcr.io/opsgrep/pbx:latest config import ./prod.yaml

What is the fastest way to deploy a PBX instance using the pbx CLI?

Answer: Use pbx deploy –template minimal –provider local to spin up a single‑node PBX in under 10 seconds.

For production: 

pbx deploy --template high-availability --provider aws --region us-east-1 --profile prod

. The --template flag generates a CloudFormation/Terraform module and runs pbx config import automatically.

This guide focuses on on-premises PBX CLI management. Cloud PBX platforms (Webex Calling, Teams) abstract these details behind a GUI. For cloud-specific CLI tools, refer to the respective provider’s API documentation.

See also  Ansible Hosts File: Syntax, Examples, Flags & Production Guide