# Gossipper Build

> Write or modify Gossipper XML scenarios for SIP load testing. Use whenever the user wants to create, edit, port, or convert SIP scenarios for the sipcapture/gossipper load generator — UAC/UAS flows, REGISTER with digest auth, 3PCC master/slave coordination, scenarios with RTP media, or porting SIPp XML to Gossipper. Also use for questions about Gossipper XML syntax, supported actions/keywords, or SIPp compatibility status of a feature.

- Skill: `voicenterteam/gossipper-build` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add voicenterteam/gossipper-build`
- Raw SKILL.md: https://api.skillmd.com/api/skills/voicenterteam/gossipper-build/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-build

---


# gossipper-build — SIP Scenario Authoring

Author valid Gossipper XML scenarios. Pinned to **Gossipper 0.1.60-rtcpmuxpatch2**
(sipcapture/gossipper on `main`, audited 2026-05-18).

## When to use this skill

- Write a new XML scenario for a specific SIP call flow.
- Modify an existing scenario.
- Port a SIPp scenario to Gossipper.
- Answer "is feature X supported / how do I express Y in Gossipper XML?"

## When NOT to use this skill

| Task | Owner |
|---|---|
| Invoking gossipper, picking transport/rate, deployment | gossipper-run |
| Interpreting summary JSON / trace CSVs / call records | gossipper-analyze |
| Authoring the 3PCC peer file (CSV `name;host:port`) | gossipper-run (deployment artifact) |
| Running `gossipper pcap2scenario` to convert a PCAP | gossipper-run |

If the user hands you a PCAP and asks for an XML scenario, the right
move is: have gossipper-run invoke `pcap2scenario` first, then this
skill cleans up the produced XML.

## Authoring workflow

1. Clarify intent: UAC vs UAS (vs 3PCC). Sequence, expected response
   codes, auth requirements, media expectations, branching, retries.
2. **Check built-ins first.** If a `-sn <name>` covers the case, no
   XML is needed. See the built-ins table below.
3. Pick the closest file in `examples/` as a starting point.
4. Declare any needed `<Global>` and `<User>` variables up front.
5. Write SIP flows inside `<![CDATA[ ... ]]>`. Use keywords liberally.
6. Add `rtd="name"` / `start_rtd="name"` on the steps that matter for
   latency measurement.
7. Add `counter="name"` on steps that should aggregate into summary JSON.
8. Add the top-of-file comment block (see "Output contract" below).
9. Validate XML well-formedness (see "Validation").
10. Hand off to gossipper-run with: scenario path, optional injection
    CSV path, intended role, required runtime vars.

## Built-in scenarios (no XML needed)

| `-sn <name>` | Role | Behavior |
|---|---|---|
| `uac` (default) | client | INVITE → 200 → ACK → BYE |
| `uas` | server | UAS answering INVITE → 180 → 200, BYE handler |
| `management` | server | UAS with HTTP API + hot-reload |
| `invite_media` | client | INVITE with RTP media |
| `invite_media_early` | client | Early media via 183 + SDP |
| `invite_media_early_180` | client | Early media variant signaled with 180 |

Built-ins are hard-coded — they cannot be PUT via `/api/v1/scenario`.
To override the shape, write a custom XML.

## File skeleton

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<!--
  Scenario: <name>
  Role: <UAC | UAS | 3PCC-master | 3PCC-slave>
  Intent: <one-paragraph description of what this scenario tests>
  Partial-support features used: <list, or "none">
  Required runtime vars: <list, or "none">
-->
<scenario name="descriptive-name">
  <Global variables="g1,g2"/>
  <User variables="u1,u2"/>

  <init>
    <!-- pre-call setup if needed -->
  </init>

  <send retrans="500"><![CDATA[
    INVITE sip:[service]@[remote_ip]:[remote_port] SIP/2.0
    Via: SIP/2.0/[transport] [local_ip]:[local_port];branch=[branch]
    ...
    Content-Length: [len]

  ]]></send>

  <recv response="100" optional="true"/>
  <recv response="180" optional="true"/>
  <recv response="200" rtd="invite"/>

  <!-- ... -->

  <timewait milliseconds="4000"/>
</scenario>
```

## Top-level commands

| Command | Purpose |
|---|---|
| `<send>` | Emit a SIP message. UDP retrans via `retrans="<ms>"`. |
| `<recv>` | Expect a SIP message. `request="METHOD"` OR `response="N"`. |
| `<pause>` | Wait. `milliseconds="N"`, optional distribution. |
| `<nop>` | No-op container for actions / branching. |
| `<label>` | Jump target. `id="name"`. |
| `<timewait>` | Post-call linger. |
| `<sendCmd>` / `<recvCmd>` | 3PCC peer coordination. |
| `<init>` | Pre-call setup block. |

Full attribute reference (timers, counters, branching, `auth=true`,
`rrs=true`, etc.) and the action catalog →
`references/xml-reference.md`.

## Always-remember gotchas

These bite on first authoring. Burn them in.

1. **Every SIP body lives in `<![CDATA[ ... ]]>`.** Bare `<`, `>`, `&`
   in SDP otherwise break XML parsing.
2. **Every message with a body needs `Content-Length: [len]`.** Missing
   it doesn't fail loudly — peers parse oddly.
3. **`retrans="<ms>"` is UDP-only.** Silently ignored on TCP/TLS.
4. **Line endings: author with `\n`.** Gossipper inserts `\r\n` on the
   wire.
5. **`[tdmmap]` is a stub** — always renders `0.0.0/0`. Don't use it.
6. **`setdest` works only on `u1` / `ui` / server-UDP.** Don't author
   dynamic destination switching for TCP/TLS scenarios — split into
   multiple scenarios instead.
7. **`-t s1` / `sn` are UDP aliases, not TLS** despite the "s" prefix.
   TLS server modes are `l1` / `sl`. Affects what the scenario can
   rely on at runtime.

Full partial-support inventory (`lookup`, `exec command`, `rtpcheck`,
`sample`, `insert`, `replace`, video/image PCAP forwarding) →
`references/xml-reference.md`.

## Going deeper

Read these on demand:

- **`references/xml-reference.md`** — full commands and attributes,
  full action catalog with support status, full keyword/template
  vocabulary, variable scopes, transport mode authoring constraints,
  comprehensive gotchas.
- **`references/patterns.md`** — specialized authoring patterns:
  - Auth: UAC handling 401/407, UAS validating digest via
    `verifyauth`, TLS mutual auth (runtime-controlled).
  - 3PCC: master entry, slave entry, init-block coordination,
    Call-ID adoption rules.
  - Media/RTP: codec table, stream sources, DTMF, recording,
    SRTP/ICE caveats.

## Canonical examples (start by copying one)

| Intent | Example file |
|---|---|
| Vanilla UAC: INVITE → 200 → ACK → BYE | `examples/uac_basic.xml` |
| REGISTER with digest 401/407 challenge | `examples/uac_register_with_auth.xml` |
| Simple UAS answering INVITE → BYE | `examples/uas_basic.xml` |
| UAC with RTP audio stream attached | `examples/uac_invite_with_media.xml` |
| 3PCC master entry pattern | `examples/3pcc_master.xml` |
| 3PCC slave entry (first step `recvCmd`) | `examples/3pcc_slave.xml` |

These are educational reference scenarios. The authoritative example
corpus lives in gossipper's `testdata/scenarios/` directory at the
pinned version — point users there when they want every variant.

## Validation

Required before handing off: XML must be well-formed.

```bash
python3 -c "import xml.etree.ElementTree as ET; ET.parse('scenario.xml'); print('OK')"
```

This catches CDATA misuse, attribute typos, unclosed tags. It does
NOT validate Gossipper-specific semantics (e.g., that `setdest` is
only used in compatible transport modes) — those failures surface at
runtime with classification `scenario_error`.

Optional (gossipper-run's job): loopback smoke run.
`gossipper -sf scenario.xml -sn uas` on the same host validates that
the scenario parses through gossipper's stricter XML loader.

## Output contract

Every scenario produced by this skill includes:

1. **Top-of-file XML comment** with: name, role, one-paragraph intent,
   list of partial-support features used (or "none"), required runtime
   vars (or "none").
2. **Explicit `Content-Length: [len]`** on every message with a body.
3. **CDATA-wrapped** SIP message bodies.
4. **No `[tdmmap]` and no `setdest` outside `u1` / `ui` / server-UDP.**
5. **Well-formed XML** — passes the validation command above.

## Handoff to gossipper-run

When done, hand over:

| Item | Why run needs it |
|---|---|
| Scenario file path(s) | `-sf` flag |
| Companion injection CSV path(s), if any | `-inf` flag |
| Intended role (UAC / UAS / 3PCC-master / 3PCC-slave) | Picks transport mode, bind, peer file |
| Required template vars | Maps to `-s` / `-au` / `-ap` / `-sip_from` / etc. |
| Partial-support features used | Run-skill may warn or adjust flags |