Asterisk AMI ModuleCheck and ModuleLoad: state, lifecycle and risk evidence

Name the exact module and responding node

Record the responding Asterisk node, installed branch and build, expected module filename, package or build source, effective modules directory, configuration owner and symptom. ModuleCheck documents its Module argument without the extension, while ModuleLoad expects a module name including .so or a documented subsystem identifier. Preserve the exact request form instead of silently normalizing it.

A module file on disk, a library loaded into the process, a module reporting Running, valid configuration, registered CLI or API capability and successful call behavior are separate states. Start with the smallest state the action actually reports.

Treat ModuleCheck as a loaded-state query

ModuleCheck returns Success or Failure for whether the named module is loaded. Its documented empty Version header is not a module revision number and must not be used for upgrade or compatibility proof. Correlate one unique ActionID, response time and node.

A Success response does not prove that the module is Running, that its configuration parsed, that dependencies are healthy or that its exported functionality works. Compare module show like output and the first capability the module should register before moving to a lifecycle action.

Choose load, unload, reload or refresh deliberately

ModuleLoad supports load, unload, reload and refresh. Reload asks a loaded module or subsystem to re-read supported state. Refresh completely unloads and loads the named module again. The optional Recursive field can cycle dependent modules when needed to complete a refresh, widening the change surface.

A subsystem identifier may only be reloaded. An omitted module on a reload request targets all reloadable modules. Keep these operations distinct from a process restart and from CLI force or hard unload options, which official guidance warns can cause crashes.

Correlate the response with lifecycle events and state

Retain the action response and relevant Load, Unload or Reload events, but interpret each message locally. The current Load event can report Success, Failure or Decline; Decline means the module is not configured, not that the binary is absent. A reload event reports a module reload result rather than proof of every internal object or dependent feature.

After the event, query the module again, inspect Running status and verify only the first exported capability. Event visibility also depends on the manager identity’s read permissions and filters.

Keep runtime action separate from startup policy

modules.conf controls autoload, preload, require, preload-require, noload and explicit load behavior at startup. A successful runtime load does not prove that the module will return after restart, and a runtime unload does not persist a startup prohibition. Update persistent policy only through the deployment’s supported configuration owner.

Load order and dependencies matter. A required module that cannot load can terminate startup with status 2, while a non-required module can fail or decline without making the whole process unavailable.

Verify effective capability with least privilege

After one authorized lifecycle operation, compare module state, configuration parse result, registered commands or API surface and the first feature-specific observation. Validate channels, registrations, routing and media separately only when they are part of the approved test.

Grant AMI identities only the required action and event classes, restrict network access and avoid broad Command authority that can expose equivalent administrative operations. No PBX, module file, dependency, configuration, manager action, channel, packet, media stream or live call was inspected or tested.

Do not load res_monitor after its Asterisk 21 removal

The AMI Monitor diagnostic distinguishes a removed module from a missing legacy deployment dependency.

Check chan_dahdi before querying its actions

The AMI DAHDI diagnostic verifies module and driver context before reading empty or unknown results.

Prove chan_dahdi before PRI actions

The AMI PRI diagnostic establishes module, libpri and DAHDI context before interpreting an unknown action or missing span.

Treat chan_sip removal as a release boundary

The AMI chan_sip migration guide distinguishes a removed module from a supported module that failed to load.

Prove bridge module registration after load state

The bridge-technology diagnostic keeps installed, loaded and registered technology states distinct.