VoIP.infoThe independent guide to business communications.
VoIP.info Guide

Asterisk AMI PJSIP maintenance mode and status evidence

Use versioned AMI actions to drain one PJSIP endpoint without treating command acceptance, status events or SIP rejection as the same proof.

Reviewed 2026-10-21Current branch-20, branch-22, certified-22.8 and branch-23 PJSIP maintenance action, status-event and completion-event references plus current AMI, Dial and upgrade guidance were reviewed October 21, 2026. The action is documented as introduced in Asterisk 20.20.0, 22.10.0 and 23.4.0, so installed release, distributor patches, loaded modules, manager actions, permissions, endpoint names, active dialogs, node scope, reload and restart behavior remain deployment specific. No PBX, module, manager account, endpoint, dialog, registration, SIP request, channel, ARI operation, packet, route, media stream or live call was inspected or testedAdvancedDocumentation based · not lab tested

Gate the workflow on the installed maintenance release

PJSIPSetMaintenance is documented as introduced in Asterisk 20.20.0, 22.10.0 and 23.4.0. Verify the running release, loaded PJSIP modules and manager action inventory before designing an automation; branch documentation alone does not prove that an older or distributor-patched node exposes the action.

Record node identity and release alongside every result. A mixed-version cluster can accept the same AMI request on one node and reject it as unknown on another.

Set one endpoint deliberately

PJSIPSetMaintenance requires an exact Endpoint and State of on or off. The special endpoint value all targets all endpoints, so reserve it for a controlled, explicitly approved scope rather than using it as a convenient substitute for inventory.

A successful AMI response means the action request was accepted. Preserve the correlated PJSIPMaintenanceStatus event and then request a fresh status snapshot; neither one alone proves the whole operational drain completed.

Read show output as a framed snapshot

PJSIPShowMaintenance can query one endpoint. With no endpoint supplied, it emits status rows for endpoints currently in maintenance mode, followed by PJSIPMaintenanceStatusComplete. Correlate the initial response, every row and the completion event under one ActionID; AMI v2 treats EventList: complete as terminal list framing, not as another action response.

Absence from the unfiltered list means the endpoint was not returned as maintenance-enabled in that completed snapshot. It is not proof that the endpoint does not exist. A specific-endpoint query is the clearer check when the target is known.

Keep the documented traffic effects precise

While maintenance mode is enabled, new inbound out-of-dialog requests are documented as rejected with 503 Service Unavailable, except SUBSCRIBE and REGISTER requests whose Expires value is 0. Outbound origins through Dial() or ARI are refused before a SIP session and channel are created.

In-progress dialogs are documented as unaffected. Maintenance mode is therefore a targeted drain control, not a PBX shutdown, registration outage, transport failure, contact-qualification result or proof that every kind of traffic stopped.

Separate control, state and behavior evidence

Keep six timestamps distinct: manager request, initial response, emitted status-change event, completed show snapshot, observed inbound SIP result and observed outbound Dial or ARI result. An action response cannot substitute for the later layers, and a 503 without correlation does not identify maintenance mode as its cause.

In HA deployments, prove which node owns the endpoint and dialog. Node-local runtime state must not be projected across a cluster without a per-node snapshot and traffic-path evidence.

Drain, maintain and restore with an explicit exit check

Before enabling maintenance, inventory the intended endpoint, active work and rollback owner. Enable it, verify the completed snapshot, observe only authorized synthetic traffic, finish the maintenance, set the endpoint off, and repeat the snapshot plus positive and negative behavior checks.

Recheck after any reload, module restart or process restart instead of assuming persistence. No PBX, endpoint, dialog, SIP request, channel, ARI operation, packet, media stream or live call was inspected or tested.

Sources & applicability

Primary references for the technical details above. Operational examples and planning checklists are VoIP.info editorial guidance.

Examples require adaptation to your topology. No live PBX or hardware testing is claimed.

Continue your research

Troubleshooting · Current branch-20, branch-22, certified-22.8 and branch-23 PJSIP maintenance action, status-event and completion-event references plus current AMI, Dial and upgrade guidance were reviewed October 21, 2026. The action is documented as introduced in Asterisk 20.20.0, 22.10.0 and 23.4.0, so installed release, distributor patches, loaded modules, manager actions, permissions, endpoint names, active dialogs, node scope, reload and restart behavior remain deployment specific. No PBX, module, manager account, endpoint, dialog, registration, SIP request, channel, ARI operation, packet, route, media stream or live call was inspected or tested

Asterisk PJSIP maintenance mode is missing, stale or calls still start

Trace release support, AMI framing, endpoint scope, node ownership and actual SIP or channel behavior before repeating or widening maintenance actions.

Read guide →
Guide · Asterisk branch-23-generated and branch-22-generated ListCommands references plus official AMI syntax, v2 specification, manager-command, change/versioning, permission, module-loader and network-security documentation reviewed October 16, 2026; installed branch and maintenance release, build, package and module set, manager user, read and write authorizations, session mask, action registration, request framing, parameters, target objects, response, related events and service outcome remain deployment specific; no PBX, module, package, manager user, manager session, request, response, event, configuration file, channel, packet, media stream or live call was inspected or tested

Asterisk AMI command inventory and permission evidence

Use ListCommands and the administrator CLI to distinguish the actions visible to one manager user from the actions registered by the running Asterisk instance.

Read guide →
Guide · Current Asterisk branch-23-generated Events, Filter, WaitEvent, Login and Ping action references, matching branch-22 Events, Filter and WaitEvent references, the official AMI event-filtering guide and Manager TCP/IP API reviewed October 16, 2026; installed branch, manager user permissions, login mask, static and dynamic filters, connection type, event queue, client parser, reconnect behavior, action concurrency, downstream storage and call activity remain deployment specific; no PBX, AMI session, manager user, permission, configuration file, socket, HTTP session, event queue, channel, bridge, packet, media stream or live call was inspected or tested

Asterisk AMI event delivery, filters and WaitEvent

Trace event delivery through manager read permissions, login and Events masks, configured and session filters, TCP or HTTP transport, WaitEvent queueing and client processing without treating silence as a failed PBX.

Read guide →
Guide · Current branch-23 PJSIPShowEndpoints, PJSIPShowEndpoint, EndpointList, EndpointListComplete, EndpointDetail and EndpointDetailComplete references, PJSIP object guidance, res_pjsip configuration reference and AMI v2 specification were reviewed October 19, 2026. Installed branch, loaded modules, manager action inventory and permissions, configuration owner, endpoint, AoR, auth, transport, identify, contact, device-state provider, active channel, registration, qualification and call behavior remain deployment specific. No PBX, module, manager account, session, endpoint, AoR, auth, transport, identify, contact, channel, registration, qualification exchange, packet, media stream or live call was inspected or tested

Asterisk AMI PJSIP endpoint lists and object detail

Use completed endpoint-list and single-endpoint transactions without turning aggregate device state, contact text or active-channel counts into registration or call proof.

Read guide →
Troubleshooting · Asterisk 22 LTS; PJSIP endpoint maintenance controls require 22.10.0 or later

Asterisk PJSIP returns or receives SIP 503 Service Unavailable

Identify the responding SIP leg, then separate maintenance mode, local channel creation, registration retry and an upstream service response.

Read guide →
Guide · Operational guidance; Asterisk 22 / FreePBX 17 where applicable

Least privilege for PBX users and integrations

Separate the right to register, place calls, administer the PBX and read sensitive data.

Read guide →