Managing PJSIP Outbound Registrations from the Asterisk CLI
Managing PJSIP Outbound Registrations from the Asterisk CLI
pjsip send unregister tells Asterisk to unregister one or more outbound PJSIP registrations. It is useful when you need to temporarily remove Asterisk's contact from an upstream SIP registrar, stop future registration attempts, test provider behavior, or move traffic during maintenance.
This command operates on outbound registration objects from pjsip.conf, not phones that register to Asterisk. That distinction matters.
| Thing | Direction | Example command |
|---|---|---|
| Outbound registration | Asterisk registers to a provider or upstream registrar | pjsip send unregister provider-reg |
| Inbound registration contact | A phone or endpoint registers to Asterisk | pjsip show contacts |
| Endpoint | PJSIP object that defines call handling behavior | pjsip show endpoint provider |
| AOR | Address of record used for contacts and outbound dialing | pjsip show aor provider-aor |
If a SIP phone is registered to Asterisk and you want to inspect or remove that contact, pjsip send unregister is not the right tool. This command is for type = registration objects where Asterisk is the SIP user agent registering outward.
Syntax
*CLI> pjsip send unregister <registration>
*CLI> pjsip send unregister *all
<registration> is the section name of a type = registration object in pjsip.conf.
Example:
[provider-reg]
type = registration
server_uri = sip:registrar.example.com
client_uri = sip:15551234567@registrar.example.com
contact_user = inbound-provider
outbound_auth = provider-auth
The CLI command uses provider-reg:
*CLI> pjsip send unregister provider-reg
Use *all with care. It queues unregistration for every outbound registration on the system.
What the Command Does
For the selected outbound registration, Asterisk queues an unregister operation. In SIP terms, Asterisk sends a REGISTER request that removes its contact from the registrar, typically by sending an expiration of zero for the registered contact.
In current Asterisk generated documentation and source behavior, pjsip send unregister also stops future registration attempts. Some older outbound-registration docs describe behavior differently, so verify your branch with pjsip show registrations after testing. When you specifically want to resume without a broader config operation, use pjsip send register for the same registration.
*CLI> pjsip send register provider-reg
The related AMI actions are PJSIPUnregister and PJSIPRegister.
What It Does Not Do
pjsip send unregister does not:
- Delete the registration object from
pjsip.conf. - Delete or modify endpoint, AOR, auth, identify, transport, or contact configuration.
- Disconnect existing calls.
- Remove inbound phone registrations from Asterisk.
- Guarantee the provider immediately stops all inbound traffic if the provider caches routing state.
- Fix endpoint qualify failures, NAT problems, authentication problems, or codec negotiation.
Existing calls keep running unless something else hangs them up. New inbound calls from the provider may stop after the registrar accepts the unregister, but exact behavior depends on the provider.
Outbound Registration, Endpoint, and AOR Behavior
A common PJSIP trunk has several separate objects:
[provider-reg]
type = registration
server_uri = sip:registrar.example.com
client_uri = sip:15551234567@registrar.example.com
contact_user = inbound-provider
outbound_auth = provider-auth
[provider-auth]
type = auth
auth_type = userpass
username = 15551234567
password = strong-password
[provider]
type = endpoint
context = from-provider
disallow = all
allow = ulaw
aors = provider-aor
outbound_auth = provider-auth
[provider-aor]
type = aor
contact = sip:registrar.example.com
[provider-identify]
type = identify
endpoint = provider
match = 203.0.113.10
pjsip send unregister provider-reg affects only [provider-reg], the outbound registration. The endpoint and AOR remain configured. If your dialplan sends outbound calls through Dial(PJSIP/${EXTEN}@provider), that endpoint still exists after you unregister.
The contact_user option on the registration controls the user portion of the Contact URI Asterisk registers. Providers often route inbound calls back to that value. It is independent from the endpoint name.
When to Use It
Use pjsip send unregister when you want to:
- Temporarily stop inbound calls from a provider during maintenance.
- Move provider traffic away from this PBX before a restart or migration.
- Clear a stale contact binding at a registrar.
- Test whether a provider accepts and honors unregister requests.
- Stop retry noise from a registration while troubleshooting credentials or provider reachability.
- Unregister first, then intentionally re-register with
pjsip send register.
Do not use it as a first response to every trunk issue. If calls fail because of authentication, NAT, DNS, TLS, routing, or endpoint matching, unregistering may only hide the real problem.
Expected CLI Output
For all registrations, Asterisk prints a queued message:
*CLI> pjsip send unregister *all
Unregister all queued
For a missing registration name, Asterisk reports that it could not find the object:
*CLI> pjsip send unregister wrong-name
Unable to retrieve registration wrong-name
For a single valid registration, some Asterisk versions are quiet on success because the operation is queued asynchronously. Verify the result with status and SIP traces instead of relying only on immediate CLI output.
*CLI> pjsip show registrations
*CLI> pjsip show registration provider-reg
If Asterisk cannot queue the task, it may print:
Failed to queue unregistration
Verify Before and After
Check current registration state:
*CLI> pjsip show registrations
*CLI> pjsip show registration provider-reg
Enable SIP logging before the test:
*CLI> pjsip set logger on
Send the unregister:
*CLI> pjsip send unregister provider-reg
Watch the SIP trace for an outbound REGISTER that removes the contact. Then check status again:
*CLI> pjsip show registrations
Turn logging off after the test:
*CLI> pjsip set logger off
To restore registration:
*CLI> pjsip send register provider-reg
*CLI> pjsip show registrations
Troubleshooting Example
Scenario: a provider still sends inbound calls to this PBX after you unregister.
- Confirm you used the registration object name, not the endpoint name.
*CLI> pjsip show registration provider-reg
- Enable PJSIP logging and send unregister again.
*CLI> pjsip set logger on
*CLI> pjsip send unregister provider-reg
-
In the SIP trace, verify that Asterisk sends REGISTER to the expected registrar and that the Contact being removed matches the Contact that was registered.
-
Check the registrar response. A 200 response means the provider accepted the request at the SIP transaction level. It does not always prove that every routing cache changed immediately.
-
If the provider challenges the unregister with 401 or 407, confirm the retry completes with authentication. If the authenticated unregister never succeeds, check
outbound_auth, username, password, realm expectations, and provider policy. -
Restore the trunk when finished.
*CLI> pjsip send register provider-reg
*CLI> pjsip set logger off
If the provider keeps sending calls after a successful unregister, collect the SIP trace and ask the provider whether it honors REGISTER expiration zero for that trunk type.
Common Failure Modes
| Symptom | Likely cause | What to check |
|---|---|---|
Unable to retrieve registration |
Wrong object name | Use pjsip show registrations and copy the registration name before the slash |
| No SIP REGISTER appears | Task was not queued, module issue, or logger filter mismatch | Check module show like res_pjsip_outbound_registration and pjsip set logger on |
| REGISTER goes to the wrong host | Registration configuration issue | Check server_uri, transport, DNS, and outbound proxy settings |
| Registrar rejects unregister | Authentication or provider policy | Check outbound_auth, provider credentials, and SIP response code |
| Status remains Registered immediately after command | Operation is asynchronous or provider rejected it | Watch the SIP trace and re-check after the transaction completes |
| Inbound calls still arrive | Provider did not remove routing immediately or incoming traffic is matched by IP | Check provider behavior, endpoint identify rules, and incoming SIP trace |
| Outbound calls still work | Expected behavior | The endpoint and AOR still exist unless you changed them separately |
| Registration does not come back | Future attempts were stopped | Run pjsip send register <registration> or perform an intentional config reload or restart |
| A phone registration remains | Wrong direction | This command does not remove inbound phone contacts from Asterisk |
Related Commands
| Command | Purpose |
|---|---|
pjsip show registrations |
List outbound registration status |
pjsip show registration |
Show details for one outbound registration |
pjsip send unregister |
Unregister outbound registration and stop future attempts |
pjsip send register |
Unregister, then start registration and schedule future attempts |
pjsip show endpoints |
List PJSIP endpoints |
pjsip show aors |
List PJSIP AORs |
pjsip show contacts |
Show contacts known to Asterisk |
pjsip set logger |
Capture SIP messages on the CLI |
Safe Maintenance Pattern
For planned maintenance on a PBX that receives calls through outbound registration:
*CLI> pjsip show registrations
*CLI> pjsip set logger on
*CLI> pjsip send unregister provider-reg
*CLI> pjsip show registrations
Wait for the provider to stop routing new calls, then perform the maintenance. Existing calls should be drained or handled separately.
After maintenance:
*CLI> pjsip send register provider-reg
*CLI> pjsip show registrations
*CLI> pjsip set logger off
For multiple trunks, avoid *all unless you really intend to unregister every provider registration on the system.
Related Guides and References
User Notes
Know a tip or gotcha for this topic? Share it below and help others.
Contribute a note
Share a tip, gotcha, or practical example. Keep it under 2000 characters. No questions (use the Asterisk community forums for support). Wrap code in backticks.