# Gossipper Run

> 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.

- Skill: `voicenterteam/gossipper-run` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add voicenterteam/gossipper-run`
- Raw SKILL.md: https://api.skillmd.com/api/skills/voicenterteam/gossipper-run/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: VoicenterTeam (https://skillmd.com/u/voicenterteam)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/voicenterteam/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

| 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.

```xml
<!--
  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

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

```bash
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:

```bash
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

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.