Gossipper Run

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

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.

<!--
  Scenario: <name>
  Role: <UAC | UAS | 3PCC-master | 3PCC-slave>
  Intent: <one-paragraph description>
  Partial-support features used: <list, or "none">
  Required runtime vars:
    -s <service>        ...
    -au <username>      ...
    -ap <password>      ...
    -rsa <host:port>    ...
    -mi <media_ip>      ...
    -mp <media_port>    ...

  3PCC coordination (if applicable):
    -cmd_peers peers.txt
    -cmd_name <master|slave>
    -cmd_listen_port <port>
-->

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

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.

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:

-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):

OTLP (event stream):

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)

Do not classify failure shapes here (timeout vs unexpected_sip vs transport_error etc.) — that's the analyze skill's vocabulary.

Always-remember gotchas

1. -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).
2. -fd <n> auto-enables -trace_stat — don't set both.
3. -t s1 / sn are UDP aliases, not TLS, despite the "s" prefix. TLS server modes are l1 / sl. TLS client is l1 / cl.
4. Port 5060 as non-root needs CAP_NET_BIND_SERVICE (not CAP_NET_RAW — gossipper uses normal sockets).
5. -summary_json is written only on clean shutdown. SIGKILL loses it. Use SIGINT to drain in-flight calls and finalize.
6. HTTP management API is OPEN by default — -api_addr :8080 has no auth unless wired via -config JSON. Don't expose beyond VPN.
7. 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.