| name | gossipper-run |
| description | Invoke the sipcapture/gossipper SIP load generator. Use whenever the user wants to run a Gossipper scenario, set CLI flags / transport mode / rate / volume / output flags, wire correlation identifiers for HEP or OTEL, author a 3PCC peer file, convert a PCAP to scenarios via `pcap2scenario`, smoke-test a freshly authored scenario, build a run-profile JSON for systemd or long-running deployment, set health thresholds, or interpret a Gossipper exit code. Also use for questions about the `gossipper -h` surface or `gossipper server` management mode. |
gossipper-run — Scenario Execution
Invoke Gossipper. Pinned to Gossipper 0.1.60-rtcpmuxpatch2 (sipcapture/gossipper
on main, audited 2026-05-18).
When to use this skill
- Run an existing scenario (one-shot CLI or long-running).
- Pick transport mode, rate, concurrency, output flags, correlation IDs.
- Author a 3PCC peer file (CSV
name;host:port).
- Convert a PCAP to scenarios via
gossipper pcap2scenario.
- Smoke-test a freshly authored scenario before the real run.
- Build a run-profile JSON for systemd / long-running deployment.
- Wire
-health_* thresholds when given threshold values.
- Interpret a Gossipper exit code at the operational level.
When NOT to use this skill
| Task | Owner |
|---|
| Write or modify a scenario XML | gossipper-build |
| Decide what XML belongs in the scenario | gossipper-build |
| Parse summary JSON, trace CSVs, call records | gossipper-analyze |
| Classify failures (timeout / unexpected_sip / …) | gossipper-analyze |
Decide threshold values for -health_* | gossipper-analyze or user |
| Cross-correlate with HEP/qryn production traffic | gossipper-analyze |
This skill picks flags and runs the process. It does not decide what
the scenario should do, and it does not interpret what came out beyond
exit-code level (0 / 1 / 2).
Inputs from gossipper-build
Every scenario authored by gossipper-build starts with a top-of-file
XML comment block. Read it — don't re-derive from message content.
Two sections drive flag selection:
- Required runtime vars → the flags you must set on the command line.
- 3PCC coordination → you author the peer file (see below) and wire
-cmd_* flags.
If the block is missing or thin, ask the user — don't guess.
Decision tree — pick the launch form
| Use case | Launch form |
|---|
| Single scenario, finite calls, exit when done | gossipper -sf … -rsa … -m … -r … |
| Repeatable named runs, ops-friendly | gossipper -config profile.json -run-alias=<name> |
| Long-running management UAS + HTTP API | gossipper server -config flat.json |
| Composite: UAS listener + parallel UAC clients | gossipper server -config flat.json (with server + clients[]) |
Both run-profile JSON shapes and the systemd pattern are in
references/patterns.md.
Common invocation patterns
Minimal flag set per pattern. Add output flags from the next section.
| Intent | Invocation |
|---|
| Vanilla UAC, finite | gossipper -sf uac.xml -rsa <host:port> -r 5 -m 100 |
| UAS listener | gossipper -sf uas.xml -sn uas -i <bind_ip> -p 5060 |
| REGISTER with digest | add -au <user> -ap <pass> -s <service> |
| 3PCC master | add -cmd_peers peers.txt -cmd_name master -cmd_listen_port <port> |
| 3PCC slave | add -cmd_peers peers.txt -cmd_name slave -cmd_listen_port <port> |
| INVITE + RTP media | add -mi <media_ip> -mp <media_port> |
| TLS client | -t l1 -tls_ca <ca.pem> (+ -tls_skip_verify=false for strict) |
| TLS server | -t l1 -tls_cert <cert.pem> -tls_key <key.pem> |
For TLS, see the gotcha below: -t s1 / sn are UDP, not TLS.
Full flag surface → references/cli-reference.md.
Output flags — always wire these
Without output flags, gossipper-analyze has nothing to read. Defaults:
| Flag | Purpose | When to omit |
|---|
-summary_json <path> | Top-level run summary, schema gossipper_summary_v1 | Never — always set |
-trace_stat -fd 5 | Per-5s stats CSV (*_stats.log) | Only for one-call debug runs |
-call_records_jsonl <path> | Per-call records (gossipper_call_record_v1) | If analyze is summary-only |
-trace_msg -message_file <path> | Full SIP send/recv human-readable | Debug only — verbose |
-trace_err -error_file <path> | Unexpected SIP + runtime errors | Always useful, cheap |
-record_wav_dir <dir> | Per-call WAV capture, Call-ID keyed (16-bit PCM mono 8 kHz; add -record_wav_duplex for stereo) | Most runs — set only when media-quality investigation needs per-call audio |
-fd <n> auto-enables -trace_stat. The full output channel matrix
(rtt, screen, counts, shortmsg, error_codes, WAV capture) →
references/cli-reference.md.
Correlation identifiers
Set these so gossipper-analyze can join run outputs with HEP traffic
in HOMER/qryn and OTLP events downstream.
HEP (SIP signaling mirror):
| Flag | Value pattern | Joins on |
|---|
-hep_addr <host:port> | HOMER/heplify-server endpoint (default port 9060) | Enables HEP3 mirror |
-hep_capture_id <n> | Distinct integer per run | HEP filtering |
-hep_password <pw> | If destination requires auth | HEP auth |
OTLP (event stream):
| Flag | Value pattern | Joins on |
|---|
-log_otel_endpoint <host:port> | OTLP receiver | Enables OTLP export — required for any OTEL data to flow |
-log_otel_proto <grpc|http> | Default grpc | Wire protocol |
-log_otel_insecure | Set for plaintext (lab / intra-VPN) | TLS off |
-log_attr self_tag=<id> | Per-run unique ID (e.g. gossipper-<region>-<ts>) | OTEL resource attr — the run-correlation key |
-log_attr <other>=<val> | Free-form (repeatable) | Additional resource attrs |
For autonomous Cowork-scheduled runs: generate one logical run
identifier (string), then derive a correlated pair:
self_tag=<run_id> — full string (e.g. cowork-soak-20260521T0930Z)hep_capture_id=<int_derived_from_run_id> — deterministic mapping,
e.g. CRC32(run_id) mod <reserved_capture_id_range>
Analyze consumes both. The string→int derivation must be reproducible
(or logged in the Run report's Notes) so cross-channel pivot works.
A single identifier cannot serve both channels — hep_capture_id is
int, self_tag is string.
3PCC peer file
When the scenario block declares 3PCC coordination, this skill authors
the peer file. Format is CSV, one row per peer:
master;<master_ip>:<master_cmd_port>
slave;<slave_ip>:<slave_cmd_port>
Naming matches -cmd_name on each instance. Slave must be running
before master starts — master immediately tries to connect.
Full coordination pattern (multi-slave, init-block, Call-ID adoption) →
references/patterns.md.
pcap2scenario
Convert a captured PCAP to paired UAC/UAS XML scenarios:
gossipper pcap2scenario -in capture.pcap -out-uac uac.xml -out-uas uas.xml
The produced XML often needs cleanup before reliable runs — CDATA
fixes, timing tuning, partial-support feature trimming. Hand the raw
output to gossipper-build, then come back here to run it.
Loopback smoke run (optional pre-flight)
Catches gossipper-specific XML loader complaints that
well-formedness validation (build's job) doesn't surface:
gossipper -sf scenario.xml -sn uas
Binds locally and starts the UAS listener; the scenario goes through
gossipper's stricter XML loader during startup. Send SIGINT
(Ctrl-C) to exit cleanly. Load-time errors surface immediately as
stderr output with exit code 1. Run once after authoring, before the
first real run. Not required on every subsequent run.
Health thresholds
When the user (or analyze) provides threshold values, wire -health_*
flags on the command line. On clean shutdown, gossipper compares
final summary metrics against thresholds; breach exits 2.
This skill sets the flags. It does not decide the values —
threshold values come from analyze or directly from the user. Full
flag list → references/cli-reference.md.
Exit codes (operational interpretation only)
| Exit | Meaning | Operational action |
|---|
| 0 | Clean run, no health breach | Hand off outputs to analyze |
| 1 | Engine or parse error | Re-check scenario (hand back to build) or flags |
| 2 | Health threshold breach | Run completed; analyze for the failing dimension |
Do not classify failure shapes here (timeout vs unexpected_sip vs
transport_error etc.) — that's the analyze skill's vocabulary.
Always-remember gotchas
-m 0 is not "unlimited" — it means zero calls. Use a large
number, or -config with total_calls: 0 in the JSON (which IS
unlimited in run-profile form).-fd <n> auto-enables -trace_stat — don't set both.-t s1 / sn are UDP aliases, not TLS, despite the "s" prefix.
TLS server modes are l1 / sl. TLS client is l1 / cl.- Port 5060 as non-root needs
CAP_NET_BIND_SERVICE (not
CAP_NET_RAW — gossipper uses normal sockets).
-summary_json is written only on clean shutdown. SIGKILL
loses it. Use SIGINT to drain in-flight calls and finalize.- HTTP management API is OPEN by default —
-api_addr :8080 has
no auth unless wired via -config JSON. Don't expose beyond VPN.
- No Docker image is published. Build your own; package layout
is under
/usr/local/gossipper/ per the upstream conventions.
Going deeper
Read on demand:
references/cli-reference.md — full flag surface grouped (engine,
transport, rate, auth, TLS, media, output/trace, HEP, OTEL, profiling,
3PCC, health, config bootstrap), subcommand routing, transport mode
matrix, signals (SIGINT drain, SIGUSR1 screen snapshot), exit
codes, HTTP management API (/api/v1/* and /api/v2/* with
-ui_data_dir).references/patterns.md — run-profile JSON (aliased form for
root command, flat composite for gossipper server), 3PCC peer
authoring + multi-slave coordination, pcap2scenario workflow,
loopback smoke pattern, HEP/OTEL correlation wiring for autonomous
runs, health threshold authoring, systemd unit pattern, deployment
notes.
Run report (handoff to gossipper-analyze)
After every run, surface this structured block in chat. Analyze
consumes it to know which artifacts to ingest and which correlation
identifiers to use.
Run report
----------
Invocation: <command line, or profile path + alias>
Started / ended: <ISO 8601> / <ISO 8601>
Exit code: <0 | 1 | 2>
Outputs produced:
summary_json: <path>
trace_stat: <path or omitted>
call_records_jsonl: <path or omitted>
message_file: <path or omitted>
error_file: <path or omitted>
wav_dir: <path or omitted>
Correlation identifiers:
hep_capture_id: <int or omitted>
self_tag: <id or omitted>
hep_addr: <host:port or omitted>
otel_endpoint: <host:port or omitted>
Notes:
<anything operationally relevant — e.g. SIGINT drained, retries observed,
any flag fallbacks that happened>
Hand this block to gossipper-analyze. Do not also paste the summary
JSON content here — analyze reads files itself.
