Config Reference

Quick start: Config is optional. sipnab works with zero configuration out of the box. Use a config file to set persistent defaults for your environment.

sipnab reads configuration from a TOML file. CLI flags always override config file values.

File Locations

Configuration is loaded from the first file found in this order:

Use --no-config (-F) to skip all file loading. Use --dump-config (-D) to print the effective merged configuration.

Unknown keys produce a warning and are ignored, allowing configs to be shared across versions.

Format

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

Sections

[capture]

Packet capture defaults.

[capture]
device = "eth0"
portrange = "5060-5080"
snaplen = 65535
buffer = 16
no_rtp = false

[display]

Output and TUI display settings.

[display]
color = "always"
payload_limit = 4096
delta_time = true
visible_columns = ["method", "from", "to", "source", "destination", "state", "msgs", "pdd"]

[filter]

Default filter presets applied at startup.

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

[security]

Security detection defaults.

[security]
kill_scanner = true
kill_response = 403
fraud_detect = true
alert = ["syslog", "json"]
alert_exec = "/usr/local/bin/sipnab-alert.sh"

[limits]

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
max_audio_frames = 1500

[privilege]

Privilege separation settings (Linux only).

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

[theme]

TUI color theme with 11 semantic color slots. See the Theme Guide for a full customization guide.

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"

[keybindings]

TUI key binding overrides. All 11 configurable actions are listed below. See Keybindings for the full shortcut reference.

Accepted key formats:

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

[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"

Full Example

A production-ready 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
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
# visible_columns = ["method", "from", "to", "state", "msgs", "pdd"]  # Persistent column prefs

# -- Default filter (optional) --
[filter]
expression = "method == 'INVITE' OR method == 'REGISTER'"

# -- Security detection --
[security]
kill_scanner = true                # Detect SIP scanners (sipvicious, etc.)
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

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

# -- Privilege separation (Linux) --
[privilege]
user = "sipnab"                    # Drop to unprivileged user after device open

# -- 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 the effective configuration after merging CLI flags, environment variables, and config file values. This is useful for debugging precedence issues.

Minimal Config

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

# ~/.config/sipnab/sipnab.toml
[capture]
device = "eth0"

[display]
delta_time = true

[theme]
background = "#1e1e2e"
foreground = "#cdd6f4"

Note: Unknown keys produce a warning and are ignored. This means configs can be shared across sipnab versions without breaking older installs.