Skip to content

Ask Each Calls rtpengine Engine

github-actions[bot] edited this page Nov 21, 2026 · 1 revision

Several rtpengine engines can sit behind one SIP proxy. The proxy picks an engine for each call, and it can move a call to another engine in the middle of the call. --rtpengine-control names one engine, so a question about a call that another engine carries goes to the wrong engine.

sipnab can learn each call's engine in two ways:

  • From rtpengine's control traffic. Every offer the proxy sends goes to one engine and names the call. sipnab reads that request from a capture on the proxy's host, or from the HEP copy each engine sends. This needs no map of media addresses. See Take each call's engine from the control traffic.
  • From the call's SDP. Each engine writes its own media address into the SDP it rewrites. sipnab reads that address and asks the engine that carries the call, by a map of media addresses and port ranges.

When sipnab saw an offer for the call, that engine is the answer. Otherwise the SDP map answers, then the engine whose list names the call, and otherwise --rtpengine-control. Use this page when:

  • the relay sessions view shows Unknown call-id for calls that do have media;
  • you need the media counters of one call, and the call is on another engine;
  • a call moved to another engine, and you suspect the old engine still holds a session for it.

To ask one relay about itself, read Ask a media relay about itself first. This page adds the engine choice to the questions described there.

What sipnab asks, and where

Question Asked of
One call: GET /v1/relay/stats/call/{call_id}, compare/{call_id}, holdings/{call_id}, the MCP query_relay, relay_stats and relay_compare tools with a call_id, the TUI relay view of a call, --relay-stats-call, --relay-compare, and each query the sessions view sends The engine the call's newest offer reached, when sipnab saw one and an ng engine row allows it; else the engine the call's newest SDP names
One call whose offer and SDP sipnab has not seen, any of the questions above The engine whose list names the call, or --rtpengine-control when none does. See Ask about a call sipnab has seen nothing for
Which calls each engine holds: --relay-holdings, GET /v1/relay/holdings, query_relay without a call_id, and the list of the sessions view (--relay-sessions, GET /v1/relay/sessions, query_relay with sessions: true, the TUI's H) --rtpengine-control and every engine an engine row or an ng engine row names, each answer shown on its own
The relay's own counters: --relay-stats, --relay-stats-interval, GET /v1/relay/stats and stats/polled, relay_stats without a call_id, relay_stats_polled, and the TUI relay view with no call --rtpengine-control and every engine an engine row or an ng engine row names, each answer shown on its own
Startup reconciliation, which names the calls behind media already flowing (Let sipnab name rtpengine's media), and its later asks about a stream nothing explains --rtpengine-control and every engine an engine row or an ng engine row names
The statistic names: --relay-stats-list, GET /v1/relay/stats/names, relay_stats with names_only, the TUI's ? --rtpengine-control only

Each answer says why it went where it went. --relay-stats-call and --relay-sessions ask before sipnab reads any SIP, so they see no SDP and no offer: they choose by the engines' lists. A TUI, REST or MCP run that captures the signaling sees both.

The statistic names stay with --rtpengine-control: they are the words one rtpengine version uses for its counters, the same on every engine that runs it. To read another engine's names, name that engine with --rtpengine-control.

Before you start

  • On each rtpengine engine:
    • a listen-ng address that the sipnab host can reach. rtpengine's control protocol has no authentication, so allow only the sipnab host to reach it.
    • the media address the engine writes into SDP. That is its interface setting, or the advertised address after ! in it, for example interface = 192.0.2.5!203.0.113.5.
    • a port range, port-min and port-max. Engines that advertise one public address need port ranges that do not overlap. sipnab tells such engines apart by port alone.
    • nothing else. sipnab sends only list, query and, for the relay-statistics requests, statistics. None of them changes a call.
  • On every other system, a firewall rule at most. Where a firewall stands between the sipnab host and an engine, it must let the sipnab host reach that engine's listen-ng address. rtpengine's own configuration stays as it is.
  • On the SIP proxy: nothing to change. OpenSIPS with several engines in its rtpengine_sock set, or Kamailio with several rtpengine nodes, picks the engine as before.
  • sipnab must see the SIP on both sides of the proxy: the message that reaches the proxy and the message the proxy sends on. Capture on the proxy's host (-d <device>), or have the proxy send HEP to a sipnab listener (-L <addr>). A capture of one side only sees the engine's address in one direction, which matters only for --rtpengine-trust-sdp-address.
  • A live source. Asking transmits, so sipnab asks only on a run that captures an interface or listens for HEP. A run that reads a capture file never asks.
  • --rtpengine-control <listen-ng address> of one engine. sipnab asks it first on every question it puts to all the engines, it alone answers the statistic names, and it answers a call no offer, SDP or list places on another engine.
  • For REST, start the server with --api-allow-relay-query. For MCP, start it with --mcp-allow-relay-query.
  • Build. Every release binary has it. A source build needs the native feature, which the default build includes.

The examples use these addresses. Replace them with yours.

Engine Media address in SDP Ports listen-ng
Engine A 203.0.113.5 30000-39999 192.0.2.5:2223
Engine B 203.0.113.5 40000-49999 192.0.2.6:2223

How sipnab finds the engine in the SDP

A call through an anchoring relay carries four SDP bodies at the proxy: the caller's own, the engine's rewrite of it sent to the callee, the callee's own, and the engine's rewrite of that sent to the caller. Measured on tests/fixtures/opensips-proxy-signaling.pcap, a call through OpenSIPS and one rtpengine:

Message SDP media
INVITE, caller to proxy 198.51.100.21:6000, the caller
INVITE, proxy to callee 198.51.100.10:30020, the engine
200 OK, callee to proxy 198.51.100.20:6000, the callee
200 OK, proxy to caller 198.51.100.10:30018, the engine

sipnab reads the c= address and the port of the first m= line of each body, in the order it captured them.

  • With an engine map, a body belongs to an engine when a row claims its address and port. The parties' own addresses match no row.
  • The engine of the newest body a row claims is the call's engine. After a re-INVITE moves the call, that is the new engine.
  • The engine of the newest earlier body with another listen-ng address is the call's previous engine.
  • A call whose SDP names no address a row claims is engine unknown (no map row). sipnab asks no engine about it, not even --rtpengine-control: the map is the list of engines sipnab may ask.

Write the engine map

Give one row per engine and port range, as MEDIA-ADDRESS LOW-HIGH CONTROL-ADDRESS:PORT. On the command line, quote each row:

sudo sipnab -d eth0 \
  --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223'

Or keep the rows in the config file, [relay] engines:

[relay]
engines = [
  "203.0.113.5 30000-39999 192.0.2.5:2223",
  "203.0.113.5 40000-49999 192.0.2.6:2223",
]
  • --rtpengine-engine rows add to [relay] engines.
  • sipnab accepts a -> between the port range and the control address, as in 203.0.113.5 30000-39999 -> 192.0.2.5:2223.
  • Write an IPv6 media address plain and an IPv6 control address in brackets: 2001:db8::5 30000-39999 [2001:db8::10]:2223.
  • One engine can have several rows, for several media addresses.
  • sipnab refuses two rows that claim one address and port, because a call there would have two engines.
  • --rtpengine-control can be one of the engines in the map, or another one. sipnab lists it with the others either way, and asks it once.

Ask about a call

The output in this section came from this build of sipnab with two scripted engines on loopback, the fake ng responder sipnab's own tests use, on 127.0.0.2:2223 (engine A) and 127.0.0.3:2223 (engine B). Each answered query with a recorded rtpengine 12.5.1 reply. The SIP reached sipnab over HEP: one call's first offer and answer on engine A's ports, then a re-INVITE that moved it to engine B's. The commands use the addresses in the table above. The output shows the loopback addresses it came from, 127.0.0.2:2223 for engine A and 127.0.0.3:2223 for engine B.

Start a server that sees the SIP, with the map and the REST opt-in:

sudo sipnab -N -d eth0 \
  --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223' \
  --api 127.0.0.1:18764 --api-allow-relay-query

Ask for one call's counters. The relay label says which engine answered and which row chose it:

curl -s "http://127.0.0.1:18764/v1/relay/stats/call/moved-1@192.0.2.21" | jq '{outcome, relay}'
{
  "outcome": "ok",
  "relay": "relay (rtpengine at 127.0.0.3:2223), chosen by engine row 203.0.113.5 40000-49999 127.0.0.3:2223 for SDP media 203.0.113.5:40012, call moved-1@192.0.2.21"
}

The call's newest SDP named 203.0.113.5:40012, which the second row claims, so sipnab asked engine B and not --rtpengine-control.

A call whose SDP names media no row claims is not asked of any engine:

{
  "outcome": "not_configured",
  "detail": "call other-1@192.0.2.21: engine unknown (no map row): no engine row claims the call's SDP media 192.0.2.21:6000, 203.0.113.9:30010, 192.0.2.20:6000, 203.0.113.9:30012, 203.0.113.9:40010, 203.0.113.9:40012; nothing was asked"
}

compare/{call_id}, holdings/{call_id}, the MCP tools, the TUI and --relay-compare choose the same way. Over MCP, relay_stats with {"call_id": "moved-1@192.0.2.21"} answered:

{
  "relay_address": "127.0.0.3:2223",
  "outcome": "ok",
  "engine": "chosen by engine row 203.0.113.5 40000-49999 127.0.0.3:2223 for SDP media 203.0.113.5:40012"
}

relay_address is the engine asked. engine says why. The answer leaves it out when the run has no engine rule.

List the calls every engine holds

sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223' \
  --relay-holdings 2>/dev/null
Holdings of relay (rtpengine at 127.0.0.2:2223), asked 2026-11-05T17:59:20.119782970+00:00
1 call held.
Call-ID
------------------
moved-1@192.0.2.21

Holdings of relay (rtpengine at 127.0.0.3:2223), asked 2026-11-05T17:59:20.119782970+00:00
2 calls held.
Call-ID
-------------------
moved-1@192.0.2.21
only-b-1@192.0.2.21

Held by several engines: moved-1@192.0.2.21
  • Each engine gets a list and a block of its own. An engine that does not answer gets a line saying so, and the others' blocks still print.
  • The run exits 0 when at least one engine answered, and 1 when none did.
  • --json and GET /v1/relay/holdings add engines, each engine's own answer, and held_by_several_engines, beside call_ids, which holds every Call-ID once. query_relay without a call_id carries the same three.

Name the calls that were up before sipnab started

At startup sipnab asks every engine the run lists which calls it holds, and reads each call's ports, so sipnab names the media of a call set up before it started, whichever engine carries it. Those calls have no offer for sipnab to see. The output in this section came from the two scripted engines described in Ask about a call, on 127.0.0.2:2223 (engine A) and 127.0.0.3:2223 (engine B):

sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-ng-engine 192.0.2.6:2223
INFO sipnab::app::bootstrap: rtpengine at 127.0.0.2:2223: 1 call(s) enumerated, complete; queried 1 of them, 4 relay port(s) now attributable
INFO sipnab::app::bootstrap: rtpengine at 127.0.0.3:2223: 2 call(s) enumerated, complete; queried 2 of them, 4 relay port(s) now attributable
INFO sipnab::app::bootstrap: Held by several engines: moved-1@192.0.2.21
  • Each engine gets a line of its own. An engine that does not answer says so in its line, and the other engines' calls are still named.
  • Held by several engines names each Call-ID two or more engines held at startup, as the listings do.
  • The engines are --rtpengine-control, then each engine an --rtpengine-engine row or an --rtpengine-ng-engine row names, each once.
  • sipnab asks every engine at once, so an engine that does not answer costs one 2 s timeout however many engines are down. See What an engine that does not answer costs.
  • For a stream that turns up later with no call to name it, sipnab asks each engine in turn, until one holds its port. Asking them all at once would spend every engine's budget on a port that one engine holds. A port an engine already accounted for needs no question: sipnab names it from memory.
  • Each engine has its own budget of control transactions: 66 at most, refilled at 33 an hour. When the run ends, each engine's line says how many it spent and how many it has left. See The control-transaction budget, and how it refills.

Read every engine's own counters

--relay-stats, --relay-stats-interval, GET /v1/relay/stats, MCP relay_stats without a call_id and the TUI relay view with no call ask every listed engine for its statistics. The command line prints one table per engine, each headed by its engine:

sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-ng-engine 192.0.2.6:2223 --relay-stats \
  --api 127.0.0.1:18764 --api-allow-relay-query
Relay statistics (rtpengine at 127.0.0.2:2223, asked 2026-11-06T13:25:07Z) — relay_reported counts
Relay statistics (rtpengine at 127.0.0.3:2223, asked 2026-11-06T13:25:07Z) — relay_reported counts

Those are the first lines of the two tables. Over REST and MCP, the top level of the answer is --rtpengine-control's answer, as with one engine, and engines holds each engine's own answer, --rtpengine-control first:

curl -s http://127.0.0.1:18764/v1/relay/stats | jq '{outcome, relay, engines: [.engines[] | {relay, outcome}]}'
{
  "outcome": "ok",
  "relay": "relay (rtpengine at 127.0.0.2:2223)",
  "engines": [
    {
      "relay": "relay (rtpengine at 127.0.0.2:2223)",
      "outcome": "ok"
    },
    {
      "relay": "relay (rtpengine at 127.0.0.3:2223)",
      "outcome": "ok"
    }
  ]
}
  • An engine that does not answer reads unreachable in its entry, and the other entries are still there. sipnab never adds two engines' counters together.
  • With one engine there is no engines, and the answer reads as before.
  • --relay-stats-interval asks every engine at once on every poll, and prints each reading as --relay-stats does. GET /v1/relay/stats/polled and relay_stats_polled carry engines too: each engine's newest reading and its newest failed poll.
  • The interval is the whole poll's. Engines that do not answer hold the poll for one timeout, 2 s, however many there are, and a poll that takes longer than the interval says the cadence slipped.

What an engine that does not answer costs

Every question sipnab puts to all the listed engines asks them at once: startup reconciliation, --relay-stats, --relay-stats-interval, GET /v1/relay/stats and stats/polled, MCP relay_stats and relay_stats_polled, the TUI relay view, --relay-holdings, the sessions view's list, and the lists that find the engine of a call sipnab has seen nothing for. Each engine has a 2 s control timeout. Asked at once, engines that do not answer cost one timeout together, not one each, and sipnab prints the answers in the order you listed the engines, whichever answers first.

sipnab opens one control socket per engine for each question, never more. A thread of its own asks each engine, and every thread ends before sipnab prints the answer.

Measured with one engine that answers and three that never answer, on loopback (--rtpengine-control 127.0.0.1:42301 and three --rtpengine-ng-engine rows), from start until the third did not answer the statistics request line, three runs each:

sipnab Startup reconciliation and --relay-stats
0.5.238, engines asked one after another 12.16 to 12.20 s: six timeouts, three at startup and three for --relay-stats
This change, engines asked at once 4.10 to 4.11 s: two timeouts, one at startup and one for --relay-stats

To check it on your own run, read the timestamps of the startup lines: every engine's could not be asked line is at most about 2 s after sipnab started, however many engines are down.

A stream nothing explains is the one question still asked of each engine in turn, until one holds its port, on the thread that reconciles. Each dead engine before the one that holds the port adds 2 s to that stream's answer, and nothing else waits for it.

The control-transaction budget, and how it refills

Each engine has its own budget of control transactions for startup reconciliation and the streams nothing explains:

  • The burst is 66. That is a startup snapshot at the default list limit (one list and a query for each of 32 calls) and one refresh of the same size. A full budget never holds more, however long it sits unspent, so a capture full of unexplained streams cannot send more than 66 questions in one go.
  • It refills at 33 an hour, one transaction every 109 s. 33 is the size of one refresh. Before, the 66 were for the whole run, so a run of several days spent them and then never named a call the engine set up later. Now sipnab names a call set up later within the hour, and reconciliation never asks an engine more than 66 times plus 33 for each hour of the run. The questions you ask over the command line, REST, MCP and the TUI do not spend from this budget.
  • A refill asks nothing. Only a stream nothing explains spends a transaction. The refill only lets sipnab ask about a later stream.
  • It counts monotonic time, so a clock stepped by NTP or by hand neither fills it nor empties it.
  • sipnab forgets what has ended. A complete list that no longer names a call removes that call and its ports from what sipnab remembers. sipnab remembers at most 4096 asked-about ports per engine and forgets the oldest first; a forgotten port asked about again spends a transaction.

How to read it:

  • The startup line of an engine that emptied its budget ends The control-transaction budget is now empty; it refills at 33 per hour, up to 66, so a stream that turns up later is asked about once it has.

  • A stream that turned up while the budget was empty reads the control-transaction budget was empty, so this port was not asked about, once per engine, until the reason changes.

  • When the run ends, each engine's line gives the counts:

    rtpengine at 192.0.2.5:2223: 2 unexplained stream(s) offered, 0 attributed, 4 control transaction(s) spent; 62 of 66 left in the budget, which refills at 33 per hour
    

    4 control transaction(s) spent counts the whole run. 62 of 66 left is the budget when the run ended.

Ask about a call sipnab has seen nothing for

A call can have no offer and no SDP that sipnab saw: the proxy set it up before sipnab started, its signaling went past another capture point, or the run is --relay-stats-call, which asks before it reads any SIP. For such a call, a question about one call asks every listed engine for its list and asks the engine whose list names the call:

curl -s "http://127.0.0.1:18764/v1/relay/stats/call/only-b-1@192.0.2.21" | jq '{outcome, relay}'
{
  "outcome": "ok",
  "relay": "relay (rtpengine at 127.0.0.3:2223), sipnab has seen no ng offer for this call; this engine's list names it, call only-b-1@192.0.2.21"
}
  • With no list naming the call, sipnab asks the default engine, and the reason ends no engine's list names it.
  • When two engines' lists name the call, sipnab asks the first, and the reason adds held by several engines: and both engines.
  • The reason names an engine that does not answer its list: did not answer its list. The other engines' lists still choose.
  • The reason also names an engine whose list stopped at the limit, 32 calls, and does not name the call: stopped at 32 calls, so it may hold this call.
  • With one listed engine, or a call whose offer or SDP sipnab saw, sipnab sends no list.

What it costs. One list per listed engine, asked once per question and of every engine at once, then the question itself to the chosen engine. A question that names several calls asks each engine once. Measured on one host, with the engines on loopback, five questions each:

Engines listed Time per question
None (no engine rule) 0.9 to 2.6 ms
Two, both answering 6.7 to 20.7 ms
Three, one never answering 2.03 to 2.04 s

Those times come from when sipnab asked the lists one engine after another, so each engine that never answered added 2 s. The lists are now asked at once: engines that never answer cost one 2 s timeout on every question about such a call, however many they are. Remove the row of an engine you took out of service.

See whether media reaches each call's engine

The sessions view lists every engine, then queries each call on its own engine:

sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223' \
  --relay-sessions 2>/dev/null
Sessions of relay (rtpengine at 127.0.0.2:2223), relay (rtpengine at 127.0.0.3:2223), asked 2026-11-05T18:10:16.347476084+00:00 (relay_reported)
reachable; 2 calls listed; queried 2 of 2 (scan)
Engine relay (rtpengine at 127.0.0.2:2223): reachable; 1 call listed
Engine relay (rtpengine at 127.0.0.3:2223): reachable; 2 calls listed
Note: a relay keeps a call it was told to delete for its delete delay (30 s by default) and its answer does not mark it; a call sipnab did not see end in SIP may have ended up to about 30 s ago.
Note: stalled means no packet for more than 2 s while another socket of the same call received one; silence suppression, comfort noise, hold and loss bursts were not measured and can also produce it.

moved-1@192.0.2.21  held by several engines  from callee-tag-1: flowing; from caller-tag-1: flowing
only-b-1@192.0.2.21  from callee-tag-1: flowing; from caller-tag-1: flowing

Call moved-1@192.0.2.21 (relay_reported)
Asked relay (rtpengine at 127.0.0.2:2223) (sipnab has seen no SDP for this call; this engine's list names it).
Held by several engines.

That is the start of the answer. Each call's socket table follows. --relay-sessions asks before it reads any SIP, so it has seen no SDP: it asks each call of the first engine whose list names it. held by several engines marks a Call-ID that two engines list. A run that sees the SIP asks each call of the engine its SDP names, as below.

The cap bounds the scan across every engine together. Each engine gets one list that asks for the cap, and the scan sends at most the cap of query in all. The cap is --relay-holdings-max, or max_calls on REST and MCP, 32 by default and at most 1024. See Choose how many held calls one ask covers.

Find a session left on the old engine

After a re-INVITE moves a call, the new engine holds it, and the old engine should have released it. Add --relay-previous-engine to a run that sees the SIP, and the sessions view asks both:

sudo sipnab -N -d eth0 \
  --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223' \
  --relay-previous-engine \
  --api 127.0.0.1:18764 --api-allow-relay-query
curl -s "http://127.0.0.1:18764/v1/relay/sessions?call_id=moved-1@192.0.2.21" | jq '.calls[0].engine'
{
  "asked": "relay (rtpengine at 127.0.0.3:2223)",
  "chosen_by": "map_row",
  "held_by_several_engines": true,
  "listed_by": [
    "relay (rtpengine at 127.0.0.2:2223)",
    "relay (rtpengine at 127.0.0.3:2223)"
  ],
  "previous": {
    "chosen_by": "map_row",
    "holds": true,
    "outcome": "ok",
    "reason": "chosen by engine row 203.0.113.5 30000-39999 127.0.0.2:2223 for SDP media 203.0.113.5:30012",
    "relay": "relay (rtpengine at 127.0.0.2:2223)"
  },
  "reason": "chosen by engine row 203.0.113.5 40000-49999 127.0.0.3:2223 for SDP media 203.0.113.5:40012"
}
  • asked is the engine the newest SDP names, and previous is the engine the SDP named before the move. previous.holds is true: the old engine still holds the call.
  • held_by_several_engines is true when two engines hold the Call-ID, by their lists or by their answers.
  • In the TUI, the call's view prints the previous engine on a line that starts Previous engine and names its relay and row, and ends still holds this call; a session was left on the old engine., then Held by several engines.
  • The answer has engine only when the run has an engine rule. Each queried call has one, and so does each call in not_queried, with listed_by and held_by_several_engines. The top level adds engines, each engine's own answer to list.

rtpengine keeps a deleted call for its delete delay, 30 s by default. A call that moved a few seconds ago can still read held by several engines. Ask again after the delay before you treat the old engine's session as left behind.

Use the SDP address without a map

--rtpengine-trust-sdp-address <CONTROL-PORT> asks the engine at the media address the call's SDP names, on the control port you give. Use it only when every SDP writer on the captured network is yours.

Risk. sipnab then sends list and query to an address it read from captured traffic. Anyone who can put SDP on that network can choose where sipnab sends them. A map does not have this risk: sipnab asks only the engines its rows name.

  • An address counts as an engine's only when sipnab saw it in both a request's SDP and a response's. That is what an anchoring relay's rewrite looks like at the proxy. sipnab sees a party's own address one way only. A capture of one side of the proxy sees the engine one way, and the call reads engine unknown (no address seen both ways).
  • sipnab asks the engine of the newest such sighting, and the one before a move is the previous engine, as with a map.
  • It needs --rtpengine-control, and sipnab refuses it beside --rtpengine-engine or [relay] engines. There is no config key.
  • list goes to --rtpengine-control only. sipnab never sends list to an address it learned from SDP.

With SDP that named 127.0.0.3 both ways, and --rtpengine-trust-sdp-address 2223:

{
  "outcome": "ok",
  "relay": "relay (rtpengine at 127.0.0.3:2223), chosen from SDP media 127.0.0.3:40012, trusted as the engine's address, call only-b-1@192.0.2.21"
}

Take each call's engine from the control traffic

The proxy sends each call's offer to one engine, and the offer names the call's Call-ID. When sipnab sees that request, it knows the engine the proxy picked, with no map of media addresses. It also sees:

  • a moved call: a later offer for the same Call-ID at another engine;
  • a leftover session: an engine the call moved off that never received a delete for it after its offer.

sipnab sees the requests in one of two ways, and you choose by where sipnab runs:

sipnab runs on It reads What names the engine
The SIP proxy's host The proxy's requests, captured on their way to each engine The address the proxy sent the request to, the engine's listen-ng
An rtpengine host, or a separate host Each engine's HEP copy of the requests (homer-enable-ng = true) The engine's homer-id, which each HEP copy carries

What sipnab trusts, and what it asks

Both kinds of evidence come from captured traffic, so neither is permission to send. sipnab asks an engine only when you listed it:

  • --rtpengine-ng-engine '[HOMER-ID] LISTEN-NG', repeatable, or [relay] ng_engines in the config file. 2001 192.0.2.5:2223 names the engine that sends HEP with homer-id = 2001. 192.0.2.6:2223 names an engine seen only in captured requests.
  • For a captured request, an address that --rtpengine-control or an --rtpengine-engine row names counts as listed too.

An offer that reached an engine you did not list reads engine not listed, as not_configured, and sipnab asks nothing about that call. It does not ask another engine in its place, because the traffic says the call is not there. This is the safe default: anyone who can put a datagram on the captured network could otherwise choose where sipnab sends query.

  • The newest offer by capture time chooses the engine. A delete alone chooses nothing.
  • sipnab remembers the offer and delete requests it read last, of any call: 4 for each dialog the dialog limit allows (--limit), at most MAX_SIGHTINGS (65,536) in all. Of each call it keeps the last 16 of those. Past that it forgets the request it read first, and a call with no request left. A forgotten offer can no longer mark a call as moved. --cores N remembers the same requests as --cores 1.
  • sipnab copies only offer and delete into its evidence. answer, replies, and the query and list that sipnab itself sends (rtpengine copies those too) change nothing.
  • With no offer seen for a call, the SDP map answers as before, and with no map, --rtpengine-control.
  • --rtpengine-ng-engine needs --rtpengine-control, as the other engine rules do. It can stand alone or beside an --rtpengine-engine map.
  • --relay-holdings and the sessions view also ask every engine an ng engine row names for its list.

sipnab on the SIP proxy's host

The proxy sends every ng request itself, so a capture on the proxy's host sees every engine, on the LAN or in another data center. sipnab names each engine by the address the proxy sent the request to. Nothing changes on the engines or the proxy, and the engines need no HEP: their one homer destination can stay your Homer.

  1. Give every engine the same listen-ng port. sipnab reads a captured request only on the port of --rtpengine-control, because a bare ng datagram carries no credential. A request to another port is not read.

  2. Start sipnab with a capture filter that admits the SIP ports and that port, and list each engine:

    sudo sipnab -N -d any \
      --rtpengine-control 192.0.2.5:2223 \
      --rtpengine-ng-engine 192.0.2.6 \
      --rtpengine-ng-engine 198.51.100.2 \
      --relay-previous-engine \
      --api 127.0.0.1:18764 --api-allow-relay-query \
      'udp port 5060 or tcp port 5060 or tcp port 5061 or udp port 2223'
    • --rtpengine-control counts as listed already, so it needs no row of its own.
    • A row can be a bare address, 192.0.2.6, or an address and port, 192.0.2.6:2223. A bare address takes the port of --rtpengine-control. In the config file: ng_engines = ["192.0.2.6", "198.51.100.2"] under [relay].
    • The filter is a plain capture filter: UDP and TCP 5060 for SIP, TCP 5061 for SIP over TLS, and UDP 2223 for ng. Change the ports to yours. Both OpenSIPS and Kamailio send ng over UDP; see OpenSIPS and Kamailio.
  3. Place a call. Ask about it:

    curl -s "http://127.0.0.1:18764/v1/relay/stats/call/cap-1@192.0.2.21" | jq -r '.outcome, .relay'

Measured with two rtpengine 12.5.1 engines on 127.0.0.2:42223 and 127.0.0.3:42223, sipnab capturing on lo, and a call offered to the first engine and then to the second:

ok
relay (rtpengine at 127.0.0.3:42223), chosen by the newest ng offer for this call, which reached listen-ng 127.0.0.3:42223; listen-ng 127.0.0.2:42223 never received a delete for this call after its offer (a leftover session), call cap-1@192.0.2.21

Engines on the LAN and behind a tunnel

-d takes one interface. -d any captures every interface at once, so one sipnab sees the requests the proxy sends to an engine on eth0 and to an engine reached through a tunnel. Measured with sipnab on -d any and the command above: an engine on 192.0.2.5:2223 reached on a LAN interface, an engine on 198.51.100.2:2223 reached through an IP-in-IP tunnel, and one offer to each:

ok | relay (rtpengine at 192.0.2.5:2223), chosen by the newest ng offer for this call, which reached listen-ng 192.0.2.5:2223, call lan-1@192.0.2.21
ok | relay (rtpengine at 198.51.100.2:2223), chosen by the newest ng offer for this call, which reached listen-ng 198.51.100.2:2223, call tun-1@192.0.2.21

Which interface carries a remote engine's requests depends on the tunnel:

  • IP-in-IP and GRE: the tunnel interface carries the request as the proxy sent it. The outer interface carries it inside the tunnel's header. sipnab opens IP-in-IP and GRE, so it names the same engine from either copy, and -d any, which sees both, names one engine.
  • WireGuard and other tun devices: capture the tunnel interface (wg0, tun0), or -d any. The outer interface carries only encrypted UDP.
  • IPsec (ESP): the outer interface carries only encrypted ESP, which sipnab cannot read. Capture an interface that carries the packets before encryption, a vti or xfrm interface.
  • The run above measured the IP-in-IP case. sipnab's tests cover the GRE, WireGuard and tun cases with the frames -d any records for those interfaces. Nothing here measured IPsec.
  • A capture filter on -d any sees each copy. udp port 2223 matches the copy on the tunnel interface. It does not match the encapsulated copy on the outer interface, which nothing needs.

OpenSIPS and Kamailio

sipnab reads the proxy's ng requests off the wire, so which proxy sent them does not matter. Both proxies' rtpengine modules send ng over UDP:

Proxy rtpengine_sock transports Read by a capture
OpenSIPS 4.0 (rtpengine module) udp:, udp6: yes
Kamailio 6.0 (rtpengine module) udp:, udp6:, ws://, wss:// udp: and udp6:; not ws:// or wss://

Measured with two rtpengine 12.5.1 engines on 192.0.2.5:2223 and 192.0.2.6:2223, OpenSIPS and Kamailio each with both engines in one set (modparam("rtpengine", "rtpengine_sock", "udp:192.0.2.5:2223 udp:192.0.2.6:2223")), and sipnab capturing the network between them: four calls through each proxy, two on each engine. For all eight, sipnab asked the engine whose log shows it received the call's offer.

When the proxy is one of a pair behind a VIP

Run sipnab on both proxies' hosts. When the VIP moves, the newly active proxy's sipnab has seen no offer for the calls already up. You need to do nothing for them:

  • A question about one of those calls asks every listed engine's list, and asks the engine whose list names the call: see Ask about a call sipnab has seen nothing for.
  • The listings, --relay-holdings and the sessions view, ask every engine each time.
  • The next offer for a call, a re-INVITE through the new proxy, names its engine again.
  • On a host that captures the media too, a stream sipnab cannot name makes it ask every listed engine again, and sipnab then names a call that came up while it ran on the standby.

sipnab does not ask the engines on a timer, or when the first ng request after a quiet spell arrives. The questions above already reach the calls that are up when the VIP moves, and a standby that asked on its own would spend its control transactions (66 per engine for the run) before anyone asked it anything.

An engine the proxy uses that you did not list

An offer to an address no row names reads engine not listed, and sipnab sends that address nothing. The message gives the row that would list it, because the proxy on this host reached it. Measured on the LAN and tunnel run above, with a third engine on 192.0.2.7:2223 and no row for it:

{
  "outcome": "not_configured",
  "detail": "call unl-1@192.0.2.21: engine not listed (192.0.2.7:2223): the newest ng offer for this call was sent to 192.0.2.7:2223, an address sipnab saw only in captured traffic; nothing was asked. To list it, add --rtpengine-ng-engine '192.0.2.7:2223', or ng_engines = [\"192.0.2.7:2223\"] in the config file's [relay] section"
}

tcpdump on every interface for that run saw 4 datagrams from sipnab to each listed engine, on the LAN interface and inside the tunnel, and none to 192.0.2.7:2223.

sipnab on an rtpengine host

Each engine sends a HEP copy of every control request to sipnab, so sipnab does not need to see the proxy. On each engine, add these lines to the [rtpengine] section of /etc/rtpengine/rtpengine.conf, with a homer-id unique to the engine, and restart it:

homer = 192.0.2.40:9060
homer-protocol = udp
homer-id = 2001
homer-enable-ng = true
  • 192.0.2.40 is the host where sipnab runs. On that host's own engine you can write homer = 127.0.0.1:9060.
  • sipnab needs homer-enable-ng = true. Without it rtpengine sends RTCP statistics only, and they name no call.
  • Start sipnab before the engines send, because rtpengine stops sending to a destination that refused it. See Let sipnab name rtpengine's media.

Start sipnab with its HEP listener, and one row per engine that names its homer-id and listen-ng. A listener on an address other than loopback needs --hep-allow with each engine's address, or --hep-auth. sipnab refuses to start without one:

sudo sipnab -N -d any -L 192.0.2.40:9060 \
  --hep-allow 192.0.2.5 --hep-allow 192.0.2.6 \
  --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-ng-engine '2001 192.0.2.5:2223' \
  --rtpengine-ng-engine '2002 192.0.2.6:2223' \
  --relay-previous-engine \
  --api 127.0.0.1:18764 --api-allow-relay-query

Measured with two rtpengine 12.5.1 engines, homer-id 2001 on 127.0.0.1:42223 and 2002 on 127.0.0.1:42224, both sending HEP to sipnab on 127.0.0.1:49060, and a call offered to 2001 and then to 2002:

curl -s "http://127.0.0.1:18764/v1/relay/stats/call/moved-1@192.0.2.21" | jq -r .relay
relay (rtpengine at 127.0.0.1:42224), chosen by the newest ng offer for this call, which reached homer-id 2002 (ng engine row 2002 127.0.0.1:42224); homer-id 2001 never received a delete for this call after its offer (a leftover session), call moved-1@192.0.2.21

If the engines already send HEP to Homer, rtpengine takes one homer destination, so pointing it at sipnab takes it away from Homer. Keep Homer instead, and run sipnab where the copies pass: on an engine's host, or on the Homer host. sipnab reads a HEP copy on its way to another collector only on UDP port 9060. Capture that port:

sudo sipnab -N -d eth0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-ng-engine '2001 192.0.2.5:2223' \
  'udp port 9060'

A copy read this way is not authenticated. Prefer the listener, with --hep-auth, where you can.

sipnab on a separate host

This is the same as on an rtpengine host: each engine sends HEP to the sipnab host, and sipnab names the engine by homer-id. Two things differ:

  • homer in each engine's rtpengine.conf is the sipnab host's address, and the network must let UDP from each engine reach it.
  • Each listen-ng address in an --rtpengine-ng-engine row must be one the sipnab host can reach. An engine that binds its listen-ng to its loopback address cannot answer a question from another host. sipnab still reports its calls, moves and leftover sessions by homer-id.

The HEP copy also reports the listen-ng address the engine bound. sipnab shows it in the engine not listed message, and never sends to it. When that address is not loopback, the message also gives the row that would list the engine, as a flag and as a config line. Measured with two rtpengine 12.5.1 engines on one network, homer-id 2009 on 192.0.2.5:2223 with no row and homer-id 2010 on 192.0.2.6:2223 with one, both sending HEP to sipnab on 192.0.2.1:9060:

sipnab -N -L 192.0.2.1:9060 --hep-allow 192.0.2.0/24 \
  --rtpengine-control 192.0.2.6:2223 \
  --rtpengine-ng-engine '2010 192.0.2.6:2223' \
  --api 127.0.0.1:18764 --api-allow-relay-query
curl -s "http://127.0.0.1:18764/v1/relay/stats/call/unl-1@192.0.2.21" | jq '{outcome, detail}'
{
  "outcome": "not_configured",
  "detail": "call unl-1@192.0.2.21: engine not listed (homer-id 2009): the newest ng offer for this call reached homer-id 2009, and no --rtpengine-ng-engine row names it (the engine reports listen-ng 192.0.2.5:2223); nothing was asked. To list it, add --rtpengine-ng-engine '2009 192.0.2.5:2223', or ng_engines = [\"2009 192.0.2.5:2223\"] in the config file's [relay] section"
}
  • tcpdump on that network, from the first offer to the last question, saw no datagram from sipnab to 192.0.2.5:2223, and 4 to the listed 192.0.2.6:2223.
  • A loopback listen-ng, such as 127.0.0.1:2223, gets no suggested row: another host cannot reach it. Nor does 0.0.0.0 or ::, which names no host.
  • The sessions view gives the same row for a leftover session on an engine no row names.
  • Add the row only when the engine is yours and the sipnab host can reach that address.

Find a leftover session from the control traffic

With --relay-previous-engine, the sessions view asks each leftover engine you listed whether it still holds the call:

curl -s "http://127.0.0.1:18764/v1/relay/sessions?call_id=moved-1@192.0.2.21" | jq '.calls[0].engine'

Measured on the two engines above, before any delete:

{
  "asked": "relay (rtpengine at 127.0.0.1:42224)",
  "chosen_by": "ng_offer",
  "held_by_several_engines": true,
  "leftovers": [
    {
      "engine": "homer-id 2001",
      "relay": "relay (rtpengine at 127.0.0.1:42223)",
      "status": "confirmed"
    }
  ],
  "listed_by": [
    "relay (rtpengine at 127.0.0.1:42223)",
    "relay (rtpengine at 127.0.0.1:42224)"
  ],
  "previous": {
    "chosen_by": "ng_offer",
    "holds": true,
    "outcome": "ok",
    "reason": "chosen by the newest ng offer for this call, which reached homer-id 2001 (ng engine row 2001 127.0.0.1:42223)",
    "relay": "relay (rtpengine at 127.0.0.1:42223)"
  },
  "reason": "chosen by the newest ng offer for this call, which reached homer-id 2002 (ng engine row 2002 127.0.0.1:42224)"
}
  • leftovers lists each engine the call moved off with no delete after its offer. status is confirmed (it still holds the call), released (it does not), not_asked, unreachable or suspect.
  • Without --relay-previous-engine, a leftover reads not_asked with add --relay-previous-engine to ask it. An engine no row names reads not_asked with no --rtpengine-ng-engine row names it, and sipnab never asks it.
  • In the TUI, the call's view prints a line such as Leftover session on homer-id 2001 (relay (rtpengine at 127.0.0.1:42223)): confirmed, it still holds this call.
  • When a delete for the call reaches the old engine, the answer drops the leftover. The old engine still answers query for its delete delay, 30 s by default, so previous.holds can stay true for that long.

Check that it worked

Ask every engine of your map what it holds:

sipnab -N -L 127.0.0.1:0 --rtpengine-control 192.0.2.5:2223 \
  --rtpengine-engine '203.0.113.5 30000-39999 192.0.2.5:2223' \
  --rtpengine-engine '203.0.113.5 40000-49999 192.0.2.6:2223' \
  --relay-holdings 2>/dev/null; echo "exit $?"

The run prints one Holdings of block per engine and exit 0. It prints exit 1 when no engine answered.

  • A question about a captured call names the engine and the row that chose it, for example chosen by engine row 203.0.113.5 40000-49999 192.0.2.6:2223 for SDP media 203.0.113.5:40012.
  • --relay-holdings prints one Holdings of block per engine, and every engine in your map is there.
  • A call you know is on engine B reads Asked relay (rtpengine at 192.0.2.6:2223) in the sessions view, not engine A.
  • With ng engine rows, a question about a call placed after sipnab started names chosen by the newest ng offer for this call, and the engine.
  • The startup log has one rtpengine at line per listed engine, and --relay-stats prints one table per listed engine.

When it does not work

  • call other-1@192.0.2.21: engine unknown (no map row): no engine row claims the call's SDP media 192.0.2.21:6000, 203.0.113.9:30010, 192.0.2.20:6000, 203.0.113.9:30012, 203.0.113.9:40010, 203.0.113.9:40012; nothing was asked. The call's SDP names media no row claims. The message lists every address and port sipnab saw for the call. Add a row for the engine's address and port range. If only the parties' addresses are listed, sipnab saw no message the engine rewrote: check that the capture sees both sides of the proxy, or that the proxy anchors the call's media at all.
  • the default engine (--rtpengine-control): sipnab has seen no SDP for this call or sipnab has seen no SDP for this call; this engine's list names it. sipnab holds no SDP for the call: the run started after the call's last offer and answer, the call's SIP went past another capture point, or the run is --relay-sessions or --relay-stats-call, which ask before sipnab reads any SIP. sipnab then asks each listed engine for its list, and the first message means no list names the call. Ask from a TUI, REST or MCP run that sees the call's next re-INVITE, or ask that engine with --rtpengine-control.
  • rtpengine at 127.0.0.4:2223 did not answer its list (no reply from 127.0.0.4:2223 within 2s: Resource temporarily unavailable (os error 11)) in the reason for a call sipnab has seen nothing for. That engine's list went unanswered, and the question waited its 2 s timeout, once for all such engines. The other engines' lists still chose. Check that the sipnab host can reach that listen-ng, or remove its row.
  • Unknown call-id from the engine sipnab chose. The engine does not hold the call. Check that each row's port range is that engine's own port-min and port-max; a range that belongs to another engine sends the question to the wrong one.
  • Engine relay (rtpengine at 127.0.0.9:2223): unreachable: relay (rtpengine at 127.0.0.9:2223) did not answer (no reply from 127.0.0.9:2223 within 2s); asked, nothing came back in the sessions status. That engine did not answer its list. The calls the other engines hold are still in the answer. Check that the sipnab host can reach that listen-ng address.
  • --rtpengine-engine (or [relay] engines) needs --rtpengine-control as well: that engine is asked first, it alone answers the relay's statistic names, and it answers about a call whose engine no ng offer, SDP or engine list names. Name one engine's listen-ng address, for example --rtpengine-control 192.0.2.5:2223 and exit 2 (1 for [relay] engines). Add --rtpengine-control with one engine's listen-ng address.
  • --rtpengine-engine / [relay] engines: engine rows "203.0.113.5 30000-40000 192.0.2.5:2223" and "203.0.113.5 40000-49999 192.0.2.6:2223" overlap: both claim media 203.0.113.5 port 40000, so a call there has no single engine and exit 2 (1 when both rows are in [relay] engines). Make the port ranges the engines' own, which do not overlap.
  • error: invalid value '203.0.113.5 40000 192.0.2.6:2223' for '--rtpengine-engine <MEDIA LOW-HIGH CONTROL>': engine row "203.0.113.5 40000 192.0.2.6:2223": "40000" is not a port range LOW-HIGH with 1 <= LOW <= HIGH <= 65535 and exit 2. The row is not three fields, or one field does not parse. The message names the field. A bad row in [relay] engines reads, for example, invalid config value: [relay] engines: engine row "203.0.113.5 39999-30000 192.0.2.5:2223": "39999-30000" is not a port range LOW-HIGH with 1 <= LOW <= HIGH <= 65535, and exits 1.
  • error: the following required arguments were not provided: --rtpengine-control <ADDR> with --relay-holdings or --relay-sessions. Those flags need --rtpengine-control, with or without a map.
  • --relay-previous-engine needs an engine rule to name a previous engine: add --rtpengine-engine rows, [relay] engines, or --rtpengine-trust-sdp-address and exit 2. Add engine rows, or drop the flag.
  • --rtpengine-trust-sdp-address and an engine map (--rtpengine-engine or [relay] engines) are two rules for one question; the map is an allowlist and trusting SDP is none. Give one of them and exit 2. Keep one rule.
  • call only-a-1@192.0.2.21: engine not listed (homer-id 2001): the newest ng offer for this call reached homer-id 2001, and no --rtpengine-ng-engine row names it (the engine reports listen-ng 127.0.0.1:42223); nothing was asked. Add --rtpengine-ng-engine '2001 <listen-ng>' with an address the sipnab host can reach. When the engine reports a listen-ng that is not loopback, the message ends with the row to add, for example To list it, add --rtpengine-ng-engine '2009 192.0.2.5:2223', or ng_engines = ["2009 192.0.2.5:2223"] in the config file's [relay] section.
  • call cap-3@192.0.2.21: engine not listed (127.0.0.4:42223): the newest ng offer for this call was sent to 127.0.0.4:42223, an address sipnab saw only in captured traffic; nothing was asked. To list it, add --rtpengine-ng-engine '127.0.0.4:42223', or ng_engines = ["127.0.0.4:42223"] in the config file's [relay] section. If that address is one of your engines, add the row the message gives.
  • the default engine (--rtpengine-control): sipnab has seen no ng offer for this call; no engine's list names it. The proxy sent the call's offer before sipnab started, or it did not reach sipnab, and no engine lists the call now:
    • On the proxy's host, check that the capture filter admits the listen-ng port and that each engine listens on the port of --rtpengine-control.
    • With HEP, check homer-enable-ng = true and that sipnab listened before the engine sent.
    • A call already up when sipnab started has no offer to see. The SDP map, the engines' lists and --rtpengine-control still answer for it.
  • A question goes to the SDP map's engine although the engine sends HEP. The HEP copy carried no capture id, so it names no engine. Set homer-id in the engine's rtpengine.conf.
  • --rtpengine-ng-engine / [relay] ng_engines: ng engine rows "2001 192.0.2.5:2223" and "2001 192.0.2.6:2223" both name homer-id 2001, so a call there has no single engine and exit 2 (1 when both rows are in [relay] ng_engines). Give each engine its own homer-id and address.

Error messages lists every refusal with its exit code.

See also

Home

Getting started

Using the TUI

CLI & automation

Configuration

Integrations (API & MCP)

Your SIP server

Add to your voice stack

Development & internals

Clone this wiki locally