# Passive AMI capture

`tools/ami_capture.php` captures selected Asterisk Manager Interface events for PBX compatibility analysis. It connects only to AMI. It contains no database, CRM, TCP bridge or WebSocket operation and does not modify PBXManager records or download recordings.

Related architecture: MPBX-000, MPBX-001 and MPBX-006. This is an implementation and operations guide; those documents remain authoritative for platform boundaries, CEM semantics and security requirements.

Implementation milestone: sanitized AMI capture support, commit `2cf5dd9` (`Add sanitized AMI capture support to CEM shadow gateway`).

The reusable example target is a DEV Grandstream UCM appliance at `<dev-pbx-host>:5038`. The active address is intentionally absent from tracked documentation and configuration. Compatibility regression against other supported appliances must use separately reviewed local configuration.

## Local configuration

Create the ignored local configuration from the repository root:

```bash
cp ami/config/ami_capture_config.inc.php.sample \
  ami/config/ami_capture_config.inc.php
```

Edit `ami/config/ami_capture_config.inc.php` and replace every `CHANGE_ME`. Keep the active file local: it is ignored by Git and must never be committed because it contains AMI credentials.

The default output directory is `runtime/ami-capture/`, also ignored by Git. The sample limits a capture by both duration and event count. An empty `event_allowlist` captures every event while still retaining only the selected safe fields and sanitized variables.

## Commands

Show help without connecting:

```bash
php tools/ami_capture.php --help
```

Run using the default ignored configuration:

```bash
php tools/ami_capture.php
```

Capture for at most two minutes and 500 events:

```bash
php tools/ami_capture.php --duration 120 --max-events 500
```

Limit capture to selected event types:

```bash
php tools/ami_capture.php \
  --events Newchannel,DialBegin,BridgeEnter,Hangup
```

Use alternative local paths:

```bash
php tools/ami_capture.php \
  --config /secure/local/ami-capture.php \
  --output-dir runtime/ami-capture
```

Options also accept the `--option=value` form. Press `Ctrl+C` to request a clean stop. SIGTERM is handled in the same way when the PHP `pcntl` extension is available.

## Output and sanitization

Each run writes two timestamped files:

- `*.ami-events.jsonl` — one JSON object per captured event;
- `*.ami-capture-metadata.json` — start/end timestamps, configured AMI host, event count, duration and tool version.

The tool does not store raw AMI packets. It never logs the AMI username or secret. Authorization, password, secret, token and key fields are excluded, and values of AMI variables with sensitive names are replaced by `[REDACTED]`. Call identifiers and channel details required for compatibility analysis are preserved.

The explicit AMI `Queue` field is retained as authoritative PBX queue-identity evidence. Its value is PBX routing identity, not CRM display metadata. Generic fields such as `Exten`, `Context`, `Application`, `ConnectedLineNum` and channel names are retained only for their existing diagnostic purposes and must not be substituted for an absent `Queue` field.

Captures may still contain personal telephone numbers, caller names and call-routing information. Keep them on the isolated DEV host with restrictive permissions. Do not commit, email or place captures in shared storage. Delete them after the compatibility findings have been recorded:

```bash
rm runtime/ami-capture/<verified-capture-file>
```

Resolve and review the exact filename before deleting it. The command above is intentionally not recursive.

## Required UCM6301 scenarios

Perform separate, clearly timed test calls for:

1. inbound answered call;
2. inbound missed call;
3. queue call;
4. caller hangup;
5. agent hangup;
6. transfer;
7. outbound call.

Record the scenario and approximate time outside the capture file so events can be correlated without adding test-specific personal data to the tool.