RFC: res_pjsip_maintenance – per-endpoint maintenance mode module

Asterisk Asterisk General
1

Hello all,

I’ve written a small module for Asterisk that puts individual PJSIP endpoints into a runtime “maintenance mode” without touching configuration files or reloading the stack.

What it does:

  • New inbound INVITE/SUBSCRIBE dialogs to a maintenance endpoint are rejected with 503 Service Unavailable + Retry-After: 300

  • Outbound originations (Dial, ARI originate) to a maintenance endpoint are refused before a channel is created

  • In-progress calls are completely unaffected

  • State is controlled at runtime via AMI (PJSIPSetMaintenance/PJSIPShowMaintenance) or CLI (pjsip set maintenance on|off <endpoint>)

  • State is volatile — it does not survive a restart, which is intentional

Our Use Case:

We operate multiple ARI applications against shared Asterisk servers, making outbound calls across dedicated SIP trunks, 24/7. The need for this module arose from three concrete operational requirements:

  1. Trunk maintenance and migration — when a trunk needs repair, upgrade, or replacement, we need to stop new calls using it while allowing calls already in progress to complete naturally. Waiting for the entire server to drain before touching a single trunk is impractical — in a busy system this can take hours.

  2. Granular infrastructure upgrades — being able to drain a specific endpoint means individual components of our infrastructure can be upgraded independently without a full service window affecting everything.

  3. Testing — maintenance mode provides a controlled, repeatable mechanism for regression and failure testing of the ARI applications themselves, simulating trunk unavailability without requiring actual infrastructure changes.

I’ve opened a PR: res_pjsip_maintenance: Add PJSIP endpoint maintenance mode by danieldonoghue · Pull Request #1820 · asterisk/asterisk · GitHub

Before it goes further in review, I’d like to know:

  • Does this solve a problem others have run into?

  • Is the AMI/CLI interface the right shape, or would you expect something different?

  • Any concerns about the approach?

All feedback welcome — including “this already exists, see X.”

many thanks