Configuration - NormB/sipnab GitHub Wiki

sipnab reads configuration from a TOML file. CLI flags (cli-reference.md) always override config file values.

Configuration is optional.

• With no file present, sipnab runs on its built-in defaults.
• A config file exists to set persistent defaults for your environment.

If you only need to override a few defaults, keep it short:

# ~/.config/sipnab/sipnab.toml
[capture]
device = "eth0"
# Your trunks also use 5080: widen the signaling ports.
portrange = "5060-5080"

[diagnosis]
# Local traffic: report setup slower than 6 seconds.
post_dial_delay_secs = 6.0

sipnab -D prints the configuration it loaded. So you can check the file took effect.

sipnab reads configuration from the first file it finds in this order:

sipnab reads only that first file.

• It does not merge a later one into it.
• So a setting in ~/.sipnabrc does nothing while ~/.config/sipnab/sipnab.toml exists.

When more than one of rows 3 to 5 exists, sipnab says which file it read and which it did not. It says so in three places:

• a warning on stderr;
• a line in --dump-config output;
• the status line when the terminal UI opens.

A --config file or $SIPNAB_CONFIG is your choice, so it raises no such notice.

# Loaded from: /home/you/.config/sipnab/sipnab.toml
# Also present and NOT read: /home/you/.sipnabrc

• Use --no-config (-F) to skip all file loading.
• Use --dump-config (-D) to print which file sipnab loaded and the keys it set. See the note under Full example for what -D does and does not show.

Unknown keys produce a warning and go no further. So one config can span versions.

Any string value may contain ${NAME}. sipnab substitutes that environment variable's value when it reads the file:

[crash]
report_dir = "/home/${SUDO_USER}/sipnab"

The case this exists for is sudo.

• Capture needs privileges, so sipnab often runs under sudo.
• After sudo -i, a file written by that run lands in root's directory. It does not land in the directory of whoever ran the command.
• ${SUDO_USER} is the only thing that can say which one that is at the moment sipnab reads the file.

Four rules, and they hold everywhere a string does:

• ${NAME} expands.
  • NAME is an ASCII letter or _ followed by letters, digits or _.
  • sipnab rejects shell's ${NAME:-default} and ${NAME-other} outright rather than half-supporting them.
• An unset variable is an error.
  • sipnab names the setting and the variable and does not start.
  • Expanding to nothing would turn /home/${SUDO_USER}/sipnab into /home//sipnab.
  • That is a real, writable directory that is not the one you meant.
• $$ is a literal $. Write $${NAME} for a literal ${NAME}.
• A bare $NAME is literal text. Braces are the whole syntax.

What a variable expands to is data. sipnab never scans it again. So a value that itself contains ${...} stays as it is.

--dump-config prints values after expansion. That is what sipnab is actually using.

Standard TOML. All sections and keys are optional. Only set values you want to change from defaults.

A file sipnab cannot read, or a value in it sipnab refuses, stops the run before anything starts.

• The exit status is 1, and the message names the key.
• The same value given as a flag exits 2.
• See Exit codes.

Packet capture defaults.

[capture]
device = "eth0"
portrange = "5060-5080"
ws_ports = "8080-8090"
snaplen = 65535
buffer = 16
buffer_budget_mb = 64
no_rtp = false
promisc = true

The loopback HEP deployment, from the file alone. A proxy mirrors HEP to UDP/9063 on lo, and any number of readers sniff it at once:

[capture]
device = "lo"
portrange = "1-65535"
ws_ports = "1-65535"
hep_parse = true
bpf_filter = "udp dst port 9063"

sipnab reads the copies without any process listening on UDP/9063. But a port with no listener costs messages with some senders.

• The kernel answers each datagram sent to a closed port with an ICMP port-unreachable message.
• A sender that uses a connected UDP socket then fails its next send.
• Measured on 2026-10-07 with sipnab's own sender before it changed:
  • sipnab -H 127.0.0.1:19063 sent a 7-message call to a port with no listener;
  • 3 of the 7 sends failed;
  • a reader on lo saw 4 messages.
• sipnab's -H now sends UDP from an unconnected socket.
  • The kernel does not report the ICMP message to that socket.
  • So it loses no message this way.
  • On 2026-10-08 the same run to a port with no listener reported 7 sent and none failed.
• Other senders, such as a proxy's HEP module, still may.
  • Whether a proxy loses copies this way depends on whether its HEP sender uses a connected socket.

Keep a receiver bound to the port while you sniff it. sipnab -L 127.0.0.1:9063 is one, and it reads the copies itself.

Output and TUI display settings.

[display]
color = "always"
payload_limit = 4096
delta_time = true
from_to = "user-host-port"
view_filter_detail = "full"
visible_columns = ["method", "from", "to", "source", "destination", "state", "msgs", "pdd"]

Default filter presets applied at startup.

[filter]
from = "^1001@"
to = "^1002@"
expression = "method == 'INVITE'"

Named filters. Each key is a name and each value a filter expression.

Use a name as @name wherever sipnab takes a filter expression:

• --filter;
• --export-vcon-when;
• [filter] expression;
• the REST filter parameter;
• an MCP tool's filter argument;
• the TUI filter dialog's Named filter field.

See Named filters.

[filters]
carrier-a = "src.ip in_subnet '203.0.113.0/24'"
support   = "to.user == '7000' OR header.X-Queue == 'support'"
sales     = "@carrier-a AND to.user =~ '^8[0-9]{3}$'"

sipnab resolves every name when it starts. It refuses to start, exit code 1, naming the entry, when:

• a name does not parse or is a built-in alias;
• an entry references a name nothing defines;
• entries reference each other in a loop;
• an expansion is not a valid expression.

vCon export settings: the export rules and enrichment services, each an array of tables that you write once per entry, and the sealing keys every rule inherits when it does not set its own.

Export rules. Each pairs a filter with the directory its vCon containers go to and what they carry.

• A run can hold several.
• sipnab writes a call matching several once per rule.
• See Write calls by rule.

[[vcon.rule]]
name  = "support-with-audio"
when  = "to.user == '7000'"
dir   = "/var/spool/sipnab-vcon/support"
audio = "inline"

Enrichment services.

• sipnab sends each one the calls of the rules it names, before it writes their containers.
• It appends the Analysis Objects of its answer.

See Enrich a call before it is written.

The PBX sipnab runs beside, for the filter field side.

[pbx]
addresses = ["192.0.2.10", "198.51.100.0/24"]

SIP protocol handling.

[sip]
xcid_headers = ["X-Call-ID", "X-CID"]
leg_correlation_window_ms = 8000
active_idle_window_secs = 7200

Security detection defaults.

HEP HMAC token version 2, and what a mixed fleet sees. sipnab 0.5.131 moved HMAC_TOKEN_VERSION from 1 to 2 and refuses v1 by name. Two things follow.

• A sender still on 0.5.130 or earlier against a newer collector has every packet refused.
  • The symptom is a collector receiving nothing.
  • Operators reliably attribute that to routing, a firewall, or a dead agent long before they suspect a token version.
  • Upgrade the collector last, or upgrade both together.
• The second thing is the reason it is not a compatible change.
  • v1's MAC did not cover the addressing chunks.
  • So an attacker who captured a v1 token from one sender could replay it against a third party.
  • The attacker could also point a published --hep-allow-kill control somewhere nobody issued it for.
  • v2 covers them.
  • There is no flag to accept v1 again, deliberately.

sipnab bounds reg_flood_window_secs and reg_flood_transaction_timeout_ms at both ends.

• A value outside the range fails validation. The message holds the key, the range and the value.
• The --reg-flood-window and --reg-flood-transaction-timeout flags refuse the same values.
• That is because both doors read the same constants in src/security/reg_flood.rs:
  • MAX_WINDOW_SECS (3,600);
  • MIN_TRANSACTION_TIMEOUT_MS (1,000);
  • MAX_TRANSACTION_TIMEOUT_MS (600,000).

Every scanner_* key above rejects 0 and names the key.

• A zero count reports the first probe of any kind as a scanner.
• A zero window resets the counters on every packet, so nothing ever accumulates.
• A zero grace restores the very defect scanner_answer_grace_ms exists to prevent.

[security]
kill_scanner = true
kill_response = 403
kill_rate_limit = 10
fraud_detect = true
business_hours = "8-18"
fraud_short_call_secs = 2
fraud_wangiri_window_secs = 900
reg_flood_threshold = 10
reg_flood_window_secs = 10
reg_flood_transaction_timeout_ms = 64000
scanner_window_secs = 60
scanner_behavioral_probes = 40
scanner_enumeration_targets = 12
findings_history = 5000
alert = ["syslog", "json"]
alert_exec = "/usr/local/bin/sipnab-alert.sh"

The peer this needs. These read TFPS through its tfps_ctl program in JSON mode, the --json flag.

• TFPS gained that mode in sippulse/tfps#6, merged on 2026-09-18.
• No tagged release carries it yet. v0.2.1, the newest, rejects --json.

Until the next release, build TFPS from its master branch.

• To check the tfps_ctl you have, run tfps_ctl status --json.
  • One line of JSON means it is ready.
  • unknown option: --json means it predates the mode.
• Against an older tfps_ctl, these answer with that error and name what to install.

The kernel-drop question (GET /v1/tfps/dropped, the tfps_dropped MCP tool) is the exception. It needs a dropped subcommand that no TFPS build has, released or on master.

Where the toll-fraud prevention system (TFPS) is, when one runs on this host.

TFPS is optional peer software. It condemns sources and enforces that decision in the firewall.

• sipnab bans nothing on its own.
• It asks TFPS to ban only when you turn that on under [actions].
• The tfps_* MCP tools and the /v1/tfps/ REST routes ask it through its tfps_ctl program.
• This section says where that program and its database are.
• Leave the section out, and sipnab:
  • looks for tfps_ctl on PATH the moment a TFPS tool runs;
  • does nothing about TFPS at any other time.

[tfps]
ctl = "/usr/local/bin/tfps_ctl"
db = "/var/lib/tfps/tfps.db"

What sipnab may change in another system, and from where. Empty by default: sipnab changes no system outside itself.

• It publishes what it saw to destinations you name.
• It asks other software read-only questions.
• An action, such as asking TFPS to ban a source, runs only when enabled here or with --allow-action. The two add together.

One key per target. Each is a list of the surfaces that may ask:

• "rest" for the REST API;
• "mcp" for the MCP tools.

A target or surface sipnab does not know stops it at startup. sipnab does not read it as "nothing enabled".

Enabling anything needs the actions journal. sipnab refuses to start without a directory it can use for it.

[actions]
tfps = ["rest"]

The limits every action passes. They exist for two reasons:

• so a stolen credential or a runaway agent can do only so much;
• so that every ban ends on its own.

Rules for the keys:

• Each key left out keeps the value shown.
• None can be 0. That would turn the limit off, so sipnab refuses to start instead.
• The limits survive a restart. sipnab rebuilds them from the journal, so crashing it does not reset them.

Whatever these say, sipnab never bans some addresses:

• 0.0.0.0;
• the broadcast address;
• loopback and multicast addresses.

[action_limits]
per_minute = 20
per_caller_per_minute = 5
address_cooldown_secs = 60
default_ban_secs = 1800
max_ban_secs = 86400

Where sipnab records the actions it takes. After a restart or a crash, it then knows:

• which bans are its own;
• what was in flight;
• how much of each limit it has spent.

sipnab --journal-show prints what it holds. sipnab --revert-actions backs actions out.

[journal]
dir = "/srv/sipnab/journal"

Thresholds the signaling and media checks compare against.

• A number here decides whether a call that is working gets reported as broken.
• So the defaults are standards figures.
• A network that knows its own numbers beats a recommendation written for the general case.

Every value must be a finite number greater than zero.

• sipnab refuses 0, a negative number, nan and inf, naming the key.
• duration_asymmetry_pct must also be 100 or less.
• cn_suppression_ratio must be 1 or less.
• late_media_ms is a whole number of at least 1.
• The matching flags follow the same rules.

[diagnosis]
post_dial_delay_secs = 6.0
ack_timeout_secs = 32.0
no_final_response_secs = 180.0
duration_asymmetry_pct = 5.0
duration_asymmetry_secs = 2.0
late_media_ms = 500
cn_suppression_ratio = 0.3

Properties of the observed media path that a passive tap cannot measure for itself.

[media]
one_way_delay_ms = 45.0
listening_context = "diotic"   # the far end uses a stereo headset or speakerphone

# Impairment factors for codecs sipnab has no published value for.
[media.codec_ie]
G722 = 12.0
iLBC = 11.0

Where the quality color column turns yellow, and where it turns red.

• A number here decides only what catches an operator's eye during triage.
• That is a different question from [diagnosis]. That one decides whether a call that is working counts as broken.

The defaults suit a general-purpose trunk. The right values belong to the network you are watching.

• 30 ms of jitter is already a fault on a LAN PBX.
• 1 percent loss is unremarkable on an international one.

Rules for the values:

• Unset keys keep the shipped default. So a file may move one boundary without restating the other seven.
• Every value must be a finite number of zero or more.
• Each warn boundary must leave a reachable middle against its matching bad boundary. A set that does not fails validation and names the key.
• Zero itself counts as a real setting. loss_warn_pct = 0.0 means any loss at all is worth a color.

These bands paint the TUI.

• A -N run prints the measurements themselves rather than a color.
• So sipnab validates a band set on a non-interactive run and then never consults it.

[quality]
jitter_warn_ms = 10.0
jitter_bad_ms = 20.0
loss_warn_pct = 0.5
loss_bad_pct = 2.0
mos_warn = 4.2
mos_bad = 3.5
rtt_warn_ms = 120.0
rtt_bad_ms = 300.0

Resource limits to prevent unbounded memory growth.

[limits]
dialog_limit = 50000
max_streams = 25000
max_reassembly = 5000
hep_rate_limit = 25000
max_header_line = 8192
max_headers_per_message = 200
max_messages_per_dialog = 500
idle_compact_after_secs = 600
keep_messages_per_idle_dialog = 20
max_audio_bytes = 1073741824

How the limits behave when they fill:

• The compaction pair is idle_compact_after_secs and keep_messages_per_idle_dialog.
  • This is where a limit discards a ladder sipnab already holds.
  • So a call that went quiet shows fewer messages than crossed the wire.
  • sipnab warns once per run when this first happens.
• The retention logs (max_audio_frames when set, max_audio_bytes, max_lost_sequences) drop their oldest entries as they fill.
• Every other key here refuses to take something in.

Raise both when the ladder matters more than the footprint. These all go quiet for longer than ten minutes while still being the thing under investigation:

• a call parked on hold;
• a dialog waiting on a slow PSTN leg;
• a capture you paused.

For example:

[limits]
idle_compact_after_secs = 3600
keep_messages_per_idle_dialog = 500

The terminal UI, and any run with --retain-audio, keeps each RTP stream's G.711, G.722 and Opus payload. Then sipnab can write it to a WAV file or a vCon.

• By default sipnab keeps the whole call, from the first frame.
• max_audio_bytes bounds the memory this uses, across every stream at once.

sipnab charges each retained frame against the budget:

• the payload, plus a quarter of its length, plus 32 bytes: an upper bound on what the memory allocator spends on it;
• 32 bytes for each slot of the stream's frame buffer, spare capacity included.

For 20 ms G.711 (160 bytes a frame) that is 264 bytes a frame:

• 13,200 bytes a second for each direction;
• 26,400 bytes a second for a call with media both ways.

The default of 1 GiB (1,073,741,824 bytes) therefore holds 40,672 call-seconds, which is:

The charge is an upper bound.

• Measured on aarch64 Linux with the allocator the sipnab binary ships with (mimalloc), a 20 ms G.711 frame used 192.6 bytes.
• So at the budget, the heap the audio really holds is about 0.73 GiB.
• With --cores N, each worker gets 1/N of the budget. So the run as a whole stays inside it.

When retained audio reaches the budget, sipnab releases frames:

• It releases the earliest frames of the oldest stream that still holds audio.
• It releases one frame at a time, until the total is back inside it.
• On a live capture the oldest stream is normally a call that has already ended.

sipnab counts the frames released on the stream.

• That call's WAV export, its vCon media_note, and the note inside the WAV then say PARTIAL: the [limits] max_audio_bytes retention budget was reached and released N earlier frame(s).
• Its vCon wraps the recording in a recording-set that carries the call's own start and duration.
• sipnab never drops audio without counting it.

A live capture that writes vCon containers (--export-vcon-when or --export-vcon with a device) releases each call's audio once it writes the call's container. The container carries it. An export of that call made later says how many frames sipnab released and why.

Raise max_audio_bytes for a host that keeps more or longer calls in memory at once.

• In the source, the default is DEFAULT_MAX_AUDIO_BYTES (1073741824).
• The minimum is MIN_MAX_AUDIO_BYTES (1048576).
• Set max_audio_frames to cap each stream as well. For example, 1500 frames is the last 30 seconds of a 20 ms stream.

Which tools the MCP server registers, and whether it sends their output schemas.

• Every tool sipnab offers a client costs its context window before the agent asks anything.
• So give a client that needs a few tools only those few.
• See Choosing which tools load for what each bundle holds.

[mcp]
tools = ["core", "voice"]

[mcp.bundles]
voice = ["media", "get_sdp_timeline", "check_codec_negotiation"]

Which Host names the REST API answers, beyond localhost, 127.0.0.1, ::1 and the address --api binds (any IP address on a 0.0.0.0 or :: bind).

• The check stops a web page from reaching the API through your browser by pointing its own name at 127.0.0.1 (DNS rebinding).
• See Which Host names the API answers.

[api]
allowed_hosts = ["sipnab.example.com"]
tls_cert = "/etc/sipnab/api.pem"
tls_key = "/etc/sipnab/api.key"

[api], [mcp] and [metrics] each take a tls_cert and tls_key. [hep] takes the HEP sender's and listener's TLS files.

• The listener itself still starts on the command line (--api, --mcp --mcp-transport http, --metrics, --hep-send, --hep-listen).
• The keys say what it serves with when it starts.

How the flags and keys combine:

• Each flag replaces its own key. A certificate from the command line and its key from the file make a pair.
• Once sipnab combines the flags and the file, a certificate without a key, or a key without a certificate, stops it at startup.
  • The message names the half you set.
  • It also names both the flag and the key that would set the other.
  • This check covers every listener's keys, whether or not this run starts it.
• Each of these stops sipnab at startup when the listener starts, naming the file:
  • a file sipnab cannot read;
  • a file with no certificate or no private key;
  • a key any other user can read;
  • a key that is not the certificate's.

How the metrics endpoint serves when --metrics starts it.

[metrics]
tls_cert = "/etc/sipnab/metrics.pem"
tls_key = "/etc/sipnab/metrics.key"

TLS for HEP:

• the CA the sender (--hep-send-transport tls) checks the collector's certificate against;
• the certificate a TLS listener (--hep-listen-transport tls) presents.

The sender's trust is one setting.

• When the command line names --hep-tls-ca or --hep-tls-extra-ca, it replaces both tls_ca and tls_extra_ca.
• So a tls_ca in the file cannot combine with an --hep-tls-extra-ca on the command line.

[hep]
tls_extra_ca = "/etc/sipnab/collector-ca.pem"

The vCon forwarder's settings (sipnab --vcon-forward <SPOOL_DIR>, see Deliver the spool to a store).

• The spool and --vcon-forward-once stay on the command line.
• The credential's value has no key.
  • auth_file names the file that holds it.
  • --vcon-forward-auth or the SIPNAB_VCON_FORWARD_AUTH environment variable carries it without a file.
• A flag replaces its key.
• With neither, a kind other than generic supplies the value. Then the default applies.

[vcon_forward]
kind = "vcon-store"
url = "https://api.vcon.store"
auth_file = "/etc/sipnab/vcon-store.key"
done = "/var/spool/sipnab-vcon-sent"
failed = "/var/spool/sipnab-vcon-held"
interval = 10

The vCon fetcher's settings (sipnab --vcon-fetch <UUID>..., see Fetch a stored vCon).

• The uuids, --vcon-fetch-out and --vcon-fetch-overwrite stay on the command line.
• The credential's value has no key. auth_file names the file that holds it.
• A flag replaces its key.
• With neither, a kind other than generic supplies the value. Then the default applies.

[vcon_fetch]
kind = "vcon-store"
url = "https://api.vcon.store"
auth_file = "/etc/sipnab/vcon-store.key"
timeout = 60

How the vCon readers open a signed or encrypted container (see A signed, encrypted or compressed container).

• The readers are -I, the MCP analyze_vcon and validate_vcon tools, and POST /v1/vcon/analyze and POST /v1/vcon/validate.
• A flag replaces its key.
• sipnab reads the files when it reads the first container.

[vcon_input]
key = "/etc/sipnab/vcon-recipient.key"
signer_ca = "/etc/sipnab/vcon-signer-ca.pem"

Privilege separation settings (Linux only).

[privilege]
user = "sipnab"
no_priv_drop = false
chroot = "/var/lib/sipnab"

Address name-resolution settings (display host:port instead of ip:port).

[names]
enabled = true
reverse_dns = false
hosts_file = "/etc/sipnab/hosts"
persist_to_config = true

# Inline mappings (also written here when persist_to_config = true):
[names.manual]
"192.0.2.1" = "sbc-edge"
"2001:db8::1" = "core6"

What happens when sipnab panics. The panic hook:

• restores the terminal (release builds abort without unwinding, so raw mode / mouse capture would otherwise stay on);
• writes a crash report;
• then either exits cleanly or aborts so the OS can produce a core dump.

[crash]
reports = true
backtrace = true
report_dir = "/var/log/sipnab"
core = false

TUI color theme with 11 semantic color slots (plus highlight, a legacy alias for selected).

• Each field accepts a color name or a hex RGB value.
• Unset fields use built-in defaults.
• See theme-guide.md for the full customization guide and its preset themes.

Supported color values:

• Named: black, white, red, green, yellow, blue, magenta, cyan, gray, dark_gray, reset
• Hex RGB: "#RRGGBB" (e.g., "#ff8800")

[theme]
background = "#1a1a2e"
foreground = "#e0e0e0"
header = "cyan"
selected = "#e94560"
accent = "magenta"
good = "green"
warning = "yellow"
bad = "red"
muted = "dark_gray"
border = "#444466"

TUI key binding overrides. The 12 configurable actions appear below. Unset fields use built-in defaults.

Accepted key formats:

• Single characters: "q", "/", "A"
• Function keys: "F1" through "F12"
• Special names: "Esc", "Space", "Enter", "Tab", "Backspace"

See keybindings.md for the full shortcut reference, including the keys that are not remappable.

[keybindings]
quit = "q"
help = "F1"
filter = "F7"
save = "F2"
search = "/"
settings = "F8"
pause = "p"
autoscroll = "A"
extended_flow = "F4"
clear_calls = "F5"
column_selector = "F10"
filter_detail = "F"

A configuration for a SIP monitoring server:

# /etc/sipnab/sipnab.toml
# Production SIP monitoring configuration

# -- Packet capture --
[capture]
device = "eth0"                    # Primary SIP-facing interface
portrange = "5060-5080"            # Cover SIP, SIP-TLS, and alternate ports
snaplen = 65535                    # Full packet capture (no truncation)
buffer = 32                        # 32 MiB kernel buffer for burst tolerance
buffer_budget_mb = 128             # Cap on the in-flight capture->processing queue
no_rtp = false                     # RTP analysis enabled

# -- Display settings --
[display]
color = "always"                   # Force color even when piped
payload_limit = 8192               # Show up to 8K of SIP body (large SDP)
delta_time = true                  # Show timing between messages by default
from_to = "host-port"              # From/To columns show host:port
# visible_columns = ["method", "from", "to", "state", "msgs", "pdd"]  # Persistent column prefs

# -- Default filter (optional) --
[filter]
from = "^1001@"
to = "^1002@"
expression = "method == 'INVITE' OR method == 'REGISTER'"

# -- Security detection --
[security]
kill_scanner = true                # Detect SIP scanners (sipvicious, etc.)
kill_response = 403                # Reply to scanners with 403
fraud_detect = true                # Heuristic fraud detection
alert = ["syslog", "json"]        # Send alerts to syslog and JSON log
alert_exec = "/usr/local/bin/sipnab-alert.sh"  # Custom alert handler
reg_flood_threshold = 10           # Refused credentialed REGISTERs per window that is a flood
reg_flood_window_secs = 1          # The counting window, in seconds of capture time
reg_flood_transaction_timeout_ms = 32000  # RFC 3261 Timer F: 64 x T1 (500 ms)
kill_rate_limit = 10               # Kill responses/sec sipnab may transmit
business_hours = "8-18"            # Enables off-hours fraud detection (UTC hours)
scanner_window_secs = 60           # Wide enough to hold a sweep paced at one probe/10s
scanner_behavioral_probes = 40     # Raised: this site aggregates behind one SBC address
fraud_wangiri_window_secs = 900    # A lure paced over fifteen minutes is still one lure

# -- Diagnosis thresholds --
[diagnosis]
post_dial_delay_secs = 8.0         # Toll-call target; the default 11.0 is international
ack_timeout_secs = 32.0            # RFC 3261 Timer H
late_media_ms = 500                # Media allowed to start this late after the 200 OK

# -- Resource limits --
[limits]
dialog_limit = 50000               # Max tracked dialogs (tune for RAM)
max_streams = 25000                # Max RTP streams
max_reassembly = 5000              # Max TCP reassembly sessions
hep_rate_limit = 25000             # Max HEP packets/sec
lint_max_per_rule = 25             # Repeats of one lint finding per dialog
exec_queue_depth = 20              # Hook commands allowed to run at once

# -- Privilege separation (Linux) --
[privilege]
user = "sipnab"                    # Drop to unprivileged user after device open
no_priv_drop = false               # Keep privilege dropping enabled
chroot = "/var/lib/sipnab"         # Chroot after initialization

# -- Address naming --
[names]
enabled = true                     # Resolve addresses to names at startup
hosts_file = "/etc/sipnab/hosts"   # Preloaded IP -> name mappings

[names.manual]
"192.0.2.1" = "sbc-edge"

# -- Crash handling --
[crash]
reports = true                     # Write a crash report on panic
backtrace = true                   # Include a full backtrace
core = false                       # Exit 101 rather than dumping core

# -- Theme: Catppuccin Mocha --
[theme]
background = "#1e1e2e"
foreground = "#cdd6f4"
header = "#89b4fa"
selected = "#f9e2af"
accent = "#cba6f7"
good = "#a6e3a1"
warning = "#fab387"
bad = "#f38ba8"
muted = "#585b70"
border = "#6c7086"

# -- Keybindings (defaults shown) --
[keybindings]
quit = "q"
help = "F1"
filter = "F7"
save = "F2"
search = "/"
settings = "F8"
pause = "p"
autoscroll = "A"
extended_flow = "F4"
clear_calls = "F5"
column_selector = "F10"

Tip: Use sipnab --dump-config to see which file sipnab actually loaded and what that file set.

• It prints the path it came from.
• It then prints every section header with the keys that file supplied under each.

Read the omissions carefully, because -D shows less than "effective configuration" suggests:

• Built-in defaults do not appear.
  • A key you did not set prints nothing, not its default.
  • sipnab -F --dump-config therefore prints a list of empty section headers. That is correct output and not a fault.
  • The defaults are the ones in the tables on this page.
• CLI flags do not appear.
  • They arrive later in startup, so -D cannot show what a flag would override.
  • Compare against the CLI reference for that.
• There is no environment-variable override layer. SIPNAB_CONFIG only selects which file to read.

So -D answers "did sipnab read the file I meant, and did it accept my keys?". That is the question behind most configuration surprises. It does not answer "what value is this setting running with?".