Skip to content

Siple configuration reference ​

Siple is configured only by a TOML file: every setting is a key in config.toml and hot-reloads. The GUI and the control API (config.edit, see Editing from the GUI and the API) are only writers of that file; state.toml holds runtime state that is not a setting. The embedded, commented example is crates/siple-config/config.example.toml; print it with siple-cli config-example. It is written to the config directory on first run (mode 0600, because it holds passwords). The schema is crates/siple-config/src/schema.rs; unknown keys are rejected (a typo is an error, not silently ignored).

Location ​

OSDefault config file
macOS~/Library/Application Support/Siple/config.toml
Windows%APPDATA%\Siple\config.toml
Linux$XDG_CONFIG_HOME/siple/config.toml

Override with --config PATH (both binaries; also for ctl/events/mcp) or the SIPLE_CONFIG environment variable (handy with docker exec). Lock file, runtime.json, state.toml, the default control socket and the default log directory all live next to the config file, so different --config directories are independent instances. Relative file paths inside the config (tls_ca_file, tls_cert, tls_key, file:/record: audio specs, log_dir) are relative to the config directory.

Reloading ​

Edits are picked up while Siple runs: the config directory is watched (500 ms debounce; unchanged content is ignored). siple-cli ctl config.reload (and SIGHUP on macOS) forces a reload and returns what changed.

  • An invalid file never replaces the last good config: the error is logged, a config.error event is emitted, the GUI shows a banner, and the previous settings stay in effect.
  • Every applied change is logged at INFO and emitted as config.applied (summary of what was done).
  • Runtime overrides (account.set_dnd, account.set_sip_trace) last until that account's same field changes in the file.
  • Accounts are compared by id: a new id starts an account, a removed id (or enabled = false) unregisters, hangs up its calls and stops it. Changing an id is therefore remove + add.

Editing from the GUI and the API ​

config.edit (JSON-RPC, MCP tool config_edit) and the GUI change the file through typed edits executed by one writer, the config actor. A write

  1. reads the file; with a base_hash (from config.view) that no longer matches, it fails with a conflict;
  2. refuses if the file does not parse as it stands (fix it first; a file that parses but fails validation can still be edited, so an edit such as disabling the bad account can repair it, as long as the result validates);
  3. changes exactly the named keys with toml_edit, so comments, blank lines, key order and quoting are preserved;
  4. re-validates the result like the loader (parse, resolve paths, validate) and reports problems with the path of the key;
  5. replaces the file atomically (temp file with the same permissions, fsync, re-read compare, rename, directory fsync);
  6. reloads, then replies with the reload report and the new hash. The file watcher then sees an unchanged hash and does nothing.

Writing rules: an existing key is updated in place (its trailing comment stays); a key that is absent and whose new value equals its effective default (the vendor profile's value, else the built-in default) is not added; new accounts and sections are appended with only the keys that differ from the default; unknown sections and keys are rejected. config.view returns the effective config with the origin of each key (file, profile or default; profiles fill only the keys the file omits, so a write pins a value), the file hash and path. Passwords and the control token are never returned: an account's password is {"set": true|false}, and a masked value is never accepted as input. Only the UI-editable account fields (enabled, profile, display_name, username, auth_username, password, password_store, domain, registrar, outbound_proxy, transport, local_port, tls_verify, tls_fingerprint, srtp, dnd, auto_answer, answer_delay_ms, allow_intercom, auto_hold, mwi, sip_trace, pickup, pickup_prefix, pickup_replaces_target), the [[account.blf]] list (all its keys) and the keys of [calls], [ui], [network], [logging], [audio] and [general] (user_agent and log_level only; log_dir, log_retention_days and reconfig_force are file-only) are editable this way. A read-only file is refused rather than replaced; everything else stays file-only. The full edit schema is in API.md.

Downgrade note: a file with keys an older build does not know is rejected by that build (unknown keys are errors). The writer adds a key only when it differs from its default.

Reload classes ​

ClassWhat happensActive calls
hotApplied immediately in place.untouched
next callStored now; calls placed/answered afterwards use it.untouched
re-registerA fresh REGISTER (with the new credentials/lifetime). An address-of-record change (username/domain) unregisters the old AOR first and re-subscribes BLF/MWI.untouched
rebuildThe account's transport/sockets are torn down and rebuilt (unregister, then register again). Deferred while the account has calls: status shows pending_rebuild and it is applied when the last call ends, unless [general] reconfig_force = true.hung up if forced
rebind[control] listeners are restarted; only the endpoints that changed are replaced (others keep their connections). runtime.json is rewritten.untouched
restartOnly takes effect at the next start of Siple (logged as "takes effect after restart").

[general] ​

OptionTypeDefaultReloadDescription
user_agentstring"Siple/<version>"hotDefault User-Agent header; an account may override it.
log_levelstring"info"hotA level (trace|debug|info|warn|error|off) or full EnvFilter syntax (info,siple_sip=debug). A bare level expands to <level>,rsipstack=warn. Invalid values are rejected (a bare typo would otherwise silence logging).
log_dirstring""restartLog directory. "" = <config dir>/logs; relative paths are relative to the config dir.
log_retention_daysinteger14restartDelete log files older than this at startup; 0 = keep forever.
reconfig_forceboolfalsehotRebuild an account's transport on config change even while it has active calls (the calls are hung up).

[logging] ​

OptionTypeDefaultReloadDescription
redact_srtp_keysboolfalsehotMask SRTP master keys (inline: of a=crypto lines) in the application log and SIP traces. Leave off while debugging key exchange.
redact_credentialsboolfalsehotMask the response, nonce and cnonce values of digest Authorization / Proxy-Authorization headers, the control token and every configured account password (4 characters or longer) in the application log and SIP traces. Username, realm and URI stay readable.

Logs and secrets ​

What reaches the logs is your choice, and today's defaults are kept: the per-account SIP trace is on (sip_trace), and neither redaction option is on. Turn them on before sharing a log or a trace (the bug-report template asks for a trace with credentials redacted):

toml
[logging]
redact_credentials = true   # digest responses, the control token and passwords
redact_srtp_keys = true     # SRTP master keys

[general]
log_level = "info"          # trace/debug show more; log_dir and log_retention_days as before
# and per account: sip_trace = false switches that account's wire trace off

Plaintext passwords are never written to a log or trace by Siple itself, whatever these options say (a digest response is a hash, not the password); the options only mask what already reached a line. A password shorter than 4 characters is not searched for literally. There is no telemetry; the only request Siple makes on its own is the optional update check ([updates]).

[control] ​

OptionTypeDefaultReloadDescription
unix_socketstring""rebindUnix socket (macOS/Linux). "" = <config dir>/control.sock, or a short path if that is too long for sun_path (~100 bytes): $TMPDIR on macOS; on Linux $XDG_RUNTIME_DIR, else a private /tmp/siple-<uid>/ (0700; refused if it is a symlink or owned by someone else). Mode 0600.
named_pipestring""rebindWindows named pipe; must start with \\.\pipe\. "" = \\.\pipe\siple-<user>-<hash of config dir>.
tcp_listenstring""rebindLoopback TCP listener, e.g. "127.0.0.1:5079"; "" = off. Non-loopback addresses are rejected. The token from runtime.json is always required on TCP.

[network] ​

Network-change resilience. Accounts re-probe their route and re-register as soon as the network changes, instead of waiting for the next refresh or a REGISTER timeout. All options are hot: they apply to the running monitor and never re-register an account by themselves.

OptionTypeDefaultReloadDescription
watchbooltruehotWatch OS address/route changes (macOS SystemConfiguration, Windows NotifyIpInterfaceChange, Linux rtnetlink) and detect sleep/wake (a wall-clock jump of more than 20 s). false leaves only the periodic probe and the API. A watcher that fails to start degrades to probe-only with one INFO log.
probe_secsint30hotRe-probe the route and DNS of every account (and the default route) every N seconds; only a different result acts. 0 = events only, else 5..3600.
debounce_msint1500hotCoalesce change triggers for this long before acting (interfaces flap while Wi-Fi roams or a VPN connects). 100..60000.
move_callsbooltruehotAfter a network change that moves the local address (or the registrar), keep established calls: rebind their RTP sockets to the new address and send a re-INVITE with the new Contact and SDP c= (hold direction and SRTP keys are kept). The call ends with cause network_lost when the peer answers 481 / 408, gives no final answer within 10 s, or refuses the re-INVITE. false ends established calls with network_lost at once. Calls that are still ringing are left alone.

With no route to the registrar an account shows waiting_for_network (not failed) and sends nothing until the network returns. API: network.refresh, account.reregister; events network.changed, account.reconnecting, call.reconnecting, call.reconnected.

[media] ​

Shared by all accounts. All options are next call (new offers/answers use them); the DTMF options (dtmf_mode, dtmf_duration_ms, dtmf_gap_ms) also apply to calls in progress. Running audio streams are not renegotiated.

OptionTypeDefaultDescription
rtp_port_range[start, end][16384, 32767]Inclusive range for RTP/RTCP port pairs. start must be even and >= 1024; range at least 2 ports. Open it in firewalls.
codecsarray["opus","g722","pcmu","pcma"]Preference order: opus, g722, pcmu, pcma. At least one; no duplicates.
jitter_min_msint40Lower bound of the adaptive jitter buffer. Must not exceed jitter_max_ms.
jitter_max_msint200Upper bound; 1..1000.
comfort_noiseboolfalseUse CN (RFC 3389) if offered by the peer.
symmetric_rtpboolfalseLatch the RTP destination to the source of authenticated incoming packets (NAT help).
rtcp_muxboolfalseOffer/use a=rtcp-mux.
rx_history_secsint60Seconds of received audio (kept at 16 kHz, about 32 KB/s per call) available to call.listen / call.rx_audio; 5..600.
codec_answer_orderoffer|local"offer"Answering: offer = first codec in the caller's offer that we support (desk-phone behaviour); local = first codec in our list present in the offer.
dtmf_moderfc4733|info|inband|auto"auto"RFC 4733 telephone-event, SIP INFO (application/dtmf-relay), in-band tones, or auto (RFC 4733 if negotiated, else INFO).
dtmf_duration_msint100Duration of a sent digit; 10..10000.
dtmf_gap_msint70Silence between digits; at most 5000.

[audio] ​

Default devices (hot) and the backend switch (restart). The GUI's device pickers and audio.set_devices write input, output and ringer of this section through config.edit's write path (comments preserved), so this section is the only place a device is chosen (status shows the effective device and its source: config or default). Device names are matched exactly as listed by audio.devices. An unplugged device falls back to the system default until it returns; the setting is not changed. Older builds kept a GUI choice in state.toml that overrode this section. On the first start of a build with this change such a choice is written into [audio] once slot by slot exactly where it was in effect under that rule (a choice newer than the [audio] value it saw overwrites that value; an [audio] value that was newer stays) and the legacy data is removed from state.toml.

OptionTypeDefaultDescription
backendauto|none|always"auto"none never opens sound devices (headless servers, containers; calls still work with silence/tone:/file: sources). On Linux auto also turns audio off, with one INFO line (status.audio.disabled_reason), unless /dev/snd/pcmC*, $XDG_RUNTIME_DIR/pulse/native, $XDG_RUNTIME_DIR/pipewire-0, $PULSE_RUNTIME_PATH/native, $PIPEWIRE_RUNTIME_DIR/pipewire-0 exists, or PULSE_SERVER / PIPEWIRE_REMOTE is set. auto probes once at startup, so a USB headset plugged in after boot, or PulseAudio configured only through client.conf default-server, is not seen: set always to skip the probe and always start the device thread (the macOS/Windows behaviour). --no-audio (both binaries) forces none. On Linux the device list hides ALSA pseudo-PCMs (null, dmix, dsnoop, surround*, iec958, front, rate/route plugins) and keeps default, pipewire, pulse, sysdefault, hw, plughw, hdmi; alsa-lib's own error messages go to the log at DEBUG (target alsa). Restart required.
inputstring""Microphone; "" = system default.
outputstring""Speaker; "" = system default.
ringerstring""Ringer; "" = same as output.

[calls] ​

Multi-line behaviour shared by all accounts. Hot.

OptionTypeDefaultDescription
decline_codeint486SIP status the GUI's Reject sends for an incoming call while another call is live on any account (call waiting; the far end of the same call, such as a self-call between two local accounts, does not count); a lone call is rejected with 486. call.reject takes an explicit code. 400-699.
hold_scopeall|account"all"Which calls an auto-hold puts on hold when a call is answered, dialed or activated (call.activate). all: every account's device-bound calls, so at most one device-bound call is un-held in the process. account: only the calls of the account that answers/dials; set this for automation and for two local accounts that call each other.
resume_after_failed_transferbooltrueA transfer that failed for good (final non-2xx, REFER refused, local error) takes the original call off hold again when the transfer put it on hold and no other device line is live. A transfer with no result after 32 s (unconfirmed) is never resumed automatically.

Always exempt from auto-hold: calls that use no audio device (agent/automation sources and sinks), and the other leg of a call between two accounts of the same process (equal SIP Call-ID). A call that the remote has put on hold (remote_held) can be auto-held like an active one. Per-account auto_hold = false exempts that account's calls from being auto-held and stops it from triggering an auto-hold. An explicit call.activate, or call.answer with mode = "hold_others", is a user request rather than an auto-hold: it ignores auto_hold and holds every other device-bound call in scope (same exemptions as above).

[ui] ​

Desktop UI settings, all hot with no effect on accounts or calls. The Settings page of the GUI writes this table; the GUI starts to read each key as the matching feature arrives. A key you leave out keeps its default.

OptionTypeDefaultDescription
themesystem|light|dark"system"Colour theme.
densitycomfortable|compact"comfortable"Row density.
reduced_motionsystem|on|off"system"Reduce animation.
blf_viewkeys|lamps|list"keys"Layout of monitored extensions.
blf_clickdial|prefill"dial"Click on an idle BLF: call at once, or fill the dial field.
blf_click_in_callmenu|consult|blind"menu"Click on a BLF during a call.
blf_click_ringingpickup|call"pickup"Click on a ringing BLF (pickup applies only where a pickup method is configured).
blf_group_byaccount|group|none"account"BLF grouping.
transfer_enterconsult|blind"consult"Enter in the transfer composer.
traybooltrueTray / menu-bar mode.
close_to_traybooltrueClosing the window hides it.
hide_from_taskbarbooltrueNo taskbar button / Dock icon while hidden.
start_hiddenboolfalseStart with the window hidden.
show_on_incomingbooltrueRaise the window on an incoming call.
show_on_answerboolfalseRaise the window when a call is answered.
notificationsbooltrueDesktop notifications.
handle_linksbooltrueHandle sip:, sips:, tel: and callto: links.
launch_at_loginboolfalseStart Siple when you log in (macOS LaunchAgent, Windows Run key, Linux XDG autostart). Combine with start_hidden = true to start in the tray.
developer_toolsboolfalseShow developer tools in the GUI. The control API and MCP stay on either way.

Desktop shell notes (tray, links, login item):

  • Tray / close-to-tray. With tray = true and close_to_tray = true closing the window hides it; only the tray menu's Quit (or Cmd+Q on macOS, Ctrl+Q on Windows / Linux, SIGTERM) exits. While hidden there is no Dock icon (macOS, hide_from_taskbar) and no taskbar button (Windows, Linux). hide_from_taskbar = false keeps the Dock icon on macOS and minimizes to the taskbar elsewhere. tray = false makes close quit. On Linux the tray is a StatusNotifierItem (KDE, XFCE, GNOME with the AppIndicator extension); without a host, closing minimizes instead so the app stays reachable. On Wayland sessions the window cannot be unmapped (winit limitation), so closing minimizes there too and start_hidden has no effect; start it under XWayland for full hide-to-tray: env -u WAYLAND_DISPLAY -u WAYLAND_SOCKET siple (winit uses Wayland whenever either variable is set).
  • Links. sip:, sips:, tel: and callto: links put the number in the dial field and raise the window; they never dial. A second siple <link> hands the link to the running instance. Windows: Siple registers itself under HKCU as a candidate for these schemes (choose it in Settings > Default apps); handle_links = false removes that registration. macOS and Linux register links through the app bundle / .desktop file at install time (Linux: xdg-mime default io.zyno.siple.desktop x-scheme-handler/sip etc.), so the key has no runtime effect there.
  • Launch at login. launch_at_login = true writes ~/Library/LaunchAgents/io.zyno.siple.plist (macOS), HKCU\...\Run (Windows) or ~/.config/autostart/io.zyno.siple.desktop (Linux) for the running executable; false removes it. A non-default --config profile has its own entry (the id plus a short hash of the config path) that starts that profile, so profiles never touch each other's entry. Pair with start_hidden = true.
  • Notifications. Incoming (with Answer / Decline on Linux), missed calls and transfer results appear while the window is not focused. macOS needs the signed app bundle (an unbundled binary logs once and skips them). The control API can show or hide the window (ui.show, ui.hide, ui.state, ui.attention, app.open_uri) when a GUI runs.

[ui.shortcuts] maps an action name to a key chord such as answer = "Mod+Shift+A"; actions not listed keep their defaults. Hot (read every frame; Settings > Shortcuts shows the chord in effect). An unknown action name or a malformed chord is a config error.

ActionDefaultDoes
answerMod+Shift+AAnswer the selected ringing call, else the newest ringing one (with another line live: answer and hold it)
hangupMod+Shift+EHang up the selected line; cancel a dialing call or consult (returns to the original); decline a ringing call
muteMod+Shift+MMute / unmute
holdMod+Shift+HHold / resume (resume swaps lines, never two live calls)
transferMod+Shift+TOpen the transfer composer
line_1 ... line_9Mod+1 ... Mod+9Select that line slot; a held line becomes the active line (a connected consult swaps)
line_prev, line_nextMod+[, Mod+]Select the previous / next line (selection only, wraps)
focus_dialMod+LFocus the dial field (opens it when collapsed)
filter_extensions/Focus the extensions filter (ignored while typing in a field)
settingsMod+,Open / close Settings

Chord syntax: modifiers and one key joined by +, case-insensitive: Mod+Shift+A, Mod+,, Alt+F4, /. Modifiers: Mod (Cmd on macOS, Ctrl elsewhere), Ctrl, Alt (Option), Shift, Cmd (the macOS Command key itself). Keys: a letter or digit, one of , . / ; ' [ ] \ - = ` , Plus, Enter, Tab, Space, Escape, Backspace, Delete, Insert, Home, End, PageUp, PageDown, Up, Down, Left, Right or F1-F12. Shift and Alt must match exactly for letters, digits and named keys (Mod+M is not Mod+Shift+M); on punctuation keys such as / Shift is ignored unless the chord names it (it is part of typing / on many layouts). Digit and bracket chords also match the physical key, so Mod+] works where the layout moves it. These are errors: Escape as the key (Esc only closes popovers), a digit with no Mod / Ctrl / Cmd / Alt (it is typed), Mod+C / Mod+V / Mod+X (clipboard), and a chord that is the same key press as another action's effective chord (Ctrl+X is Mod+X off macOS, Cmd+X is on macOS). Cmd off macOS never fires and is a warning; Settings > Shortcuts lists problems. Remove a bad entry with config.edit reset_section ui shortcuts.<name>.

Typing: digits, * and # send DTMF while the stage shows an Active line and no text field has focus; otherwise they type into the dial field (opening it when collapsed). Esc only closes popovers and the transfer composer; it never hangs up or cancels a consult. OS-wide (global) hotkeys are not available.

[speech] ​

Optional external text-to-speech and speech-to-text commands, used by call.say, call.listen{transcribe} and speech.*. Hot (each job snapshots the section when it starts). Off by default; nothing is bundled.

OptionTypeDefaultDescription
tts_commandarray[]argv of the TTS program; [] = TTS off. Placeholders: {text_file} (UTF-8 text file), {out} (WAV to write), {voice}. If {out} is not referenced the WAV is read from stdout.
tts_timeout_msint30000Kill the process (group) after this long; 1000..120000.
tts_voicestring""Default voice for {voice}.
stt_commandarray[]argv of the STT program; [] = STT off. Placeholders: {in} (16 kHz mono 16-bit WAV), {lang}, {out_base}, {out_txt}. If {out_txt} is not referenced the transcript is read from stdout.
stt_timeout_msint60000As tts_timeout_ms; 1000..120000.
stt_languagestring"en"Default language for {lang}.

Rules: no shell is ever involved; placeholders are replaced inside argv elements only, {{ and }} produce literal braces, and an unknown placeholder is a config error. tts_voice, stt_language and any per-request voice/language must match [A-Za-z0-9][A-Za-z0-9_.+:-]{0,63} (no leading -). Text to speak is passed on stdin and in {text_file}, never in argv.

[updates] ​

The update check: Siple tells you when a newer release exists. Hot. Detection only: nothing is downloaded or installed; a pill in the header (and Settings > Advanced) links to the release page. Mac App Store and Microsoft Store builds do not contain the check at all (they update through the store); there [updates] is accepted and ignored.

OptionTypeDefaultDescription
checkbooltrueLook for a newer release about 30 seconds after start (not when a check found nothing newer less than 24 hours ago), then every 24 hours of wall-clock time, so time spent asleep counts (and on app.check_updates or "Check now"; a manual check restarts the 24 hours).
channelstable|prereleaseunsetstable offers final releases only; prerelease also offers release candidates (-rc.N). Unset = automatic: prerelease while the running build is itself a release candidate, otherwise stable. reset_section updates channel returns to automatic.

What is sent: one anonymous HTTPS GET https://api.github.com/repos/zyno-io/siple/releases?per_page=20 with the headers User-Agent: Siple/<version> and Accept: application/vnd.github+json (plus If-None-Match with the ETag of the previous answer, so an unchanged list costs almost nothing). Nothing else: no identifier, account, install ID or usage data, and the request carries no cookies. GitHub sees your IP address, as any web server does. Failures (offline, rate limited, odd answer) are logged and shown in Settings; they never raise a dialog. API: app.update_status, app.check_updates, the event app.update_available and the update summary of status. The user guide has a page, "Updates".

[[account]] ​

Repeat the table for each account. Only id, username and domain are needed for a working account; the shipped example is enabled = false so a fresh install never tries to register.

Identity and registration ​

OptionTypeDefaultReloadDescription
idstring(required)identityUnique (case-insensitive); [A-Za-z0-9_.-] only. Used in API calls and file names (logs/sip/<id>/sip.<date>.log).
enabledbooltruedisable: immediate; enable: rebuildtrue -> false disables at once (calls hung up, binding removed). false -> true starts the account (a rebuild).
profilegeneric|yealink|polycom|cisco|grandstream"generic"hotVendor preset, see Vendor profiles. Fills the options the file leaves out; explicit options win.
display_namestring""hotDisplay name in the From header.
usernamestring(required if enabled)re-registerUser part of the AOR. No whitespace or @.
auth_usernamestring""re-registerDigest username; "" = username.
passwordstring""re-registerDigest password. Redacted (***) in config.get / logs. Must be empty with password_store = "keyring".
password_storefile|keyring"file"re-registerWhere the password lives: file = the password key above (default); keyring = the system credential store, see Passwords in the system keyring.
domainstring(required if enabled)re-registerDomain of the AOR, bare host. Also the registrar if registrar is empty; in that case a change also moves the next hop and is a rebuild.
registrarstring""rebuildNext hop / request-URI host (host[:port]); "" = domain.
registerbooltruere-registerfalse = peer mode: no REGISTER, but calls still work (direct IP / PBX with IP auth).
expiresint300re-registerRequested registration lifetime in seconds; 10..86400.
user_agentstring""hotOverrides [general].user_agent; "" = inherit.
extra_headerstable{}hotHeaders added to outgoing requests, e.g. { "X-Test" = "1" }. Names must be valid tokens; Via, From, To, Call-ID, CSeq, Contact, Content-Length are reserved.

Transport, NAT and TLS ​

OptionTypeDefaultReloadDescription
transportudp|tcp|tls|auto"udp"rebuildSignalling transport. auto picks it from DNS SRV, see transport = "auto".
local_portint0rebuildLocal SIP port; 0 = ephemeral. Two enabled accounts cannot share a non-zero port (UDP and TCP/TLS are separate port spaces).
bind_addressstring""rebuildLocal IP to bind and advertise; "" = auto (interface toward the next hop). Must be an IP.
public_addressstring""rebuildIP/host to advertise in Via/Contact/SDP without binding to it (static NAT).
rewrite_contactbooltruere-registerLearn the registrar-observed IP/port from the REGISTER response's Via received/rport and immediately re-register with that Contact. false keeps the configured Contact. An explicit public_address disables automatic rewriting.
outbound_proxystring""rebuildForced next hop for all requests, host[:port].
outbound_proxy_routeboolfalserebuildAlso add Route: <proxy;lr>.
keepalive_secsint30hotNAT keep-alive interval; 0 = off, else 5..3600.
keepalive_methodcrlf|options"crlf"hotDouble-CRLF ping or SIP OPTIONS. options also detects dead flows: any SIP response counts as alive.
keepalive_fail_thresholdint2hotWith keepalive_method = "options": this many consecutive unanswered keep-alives mark the flow dead; the account re-probes and re-registers at once. 0 = never, max 20.
use_sips_uriboolfalserebuildOn TLS use a sips: Contact instead of sip:...;transport=tls.
tls_verifybooltruerebuildVerify the server certificate (OS trust store + tls_ca_file). false ignores certificate errors (test PBXs).
tls_ca_filestring""rebuildPEM file with extra trusted CAs.
tls_server_namestring""rebuildSNI / verification name override (registrar/proxy only).
tls_fingerprintstring""rebuildPin the server's leaf certificate: SHA-256 of its DER as 64 hex digits (colons optional). That exact certificate is accepted regardless of chain, expiry or name (handshake signatures are still checked); tls_verify and tls_ca_file are then not consulted. Get it with openssl x509 -in pbx.pem -noout -fingerprint -sha256.
tls_cert / tls_keystring""rebuildPEM certificate and key for the TLS listener / client auth; "" = self-signed. Must be set together. A missing file is a warning, not an error.

Changing rewrite_contact clears the learned Contact and re-registers over the existing transport; active calls continue. With rewriting enabled, later registration refreshes keep using the learned Contact until the connection changes. The observed public address remains available in account status when rewriting is disabled.

Passwords in the system keyring ​

password_store = "keyring" keeps an account's password in the operating system's credential store instead of config.toml. It is opt-in and selected by the file itself (the only setting whose value lives outside the file); the default stays the password in the 0600 file.

  • Backends: macOS Keychain, Windows Credential Manager, Linux Secret Service (GNOME Keyring, KWallet) over a pure-Rust D-Bus client; Siple does not link libdbus.
  • Entry: service io.zyno.siple, user account:<id>.
  • With keyring, password must be empty (a validation error otherwise). Set the password with the account.set_password API method (or the settings UI); it writes the entry, then reloads so the account registers with it.
  • The loader reads the entry once per reload into memory, never per REGISTER (a Keychain access can prompt). Disabled accounts are not read.
  • No credential store (headless Linux, Docker) or no entry: that account is switched off in memory and the reload reports account <id>: keyring unavailable; set password_store = "file" (or no password in the keyring ...) in status.config.last_error, the log and the config.error event. There is never a silent fallback to a plaintext password. Other accounts are unaffected.
  • config.edit keeps the entry in step: set_account password_store moves the existing password between the file and the entry, rename_account moves the entry, remove_account deletes it, and add_account with password_store = "keyring" stores the draft's password in the entry instead of the file.
  • macOS ties keychain access to the code signature: unsigned development builds ask again after every rebuild; signed builds do not.
  • Passwords never appear in logs, API results or error messages.

transport = "auto" ​

The account selects its transport from DNS SRV records of the next hop (the outbound proxy, else the registrar, else the domain): the first of _sips._tcp (TLS), _sip._tcp (TCP) and _sip._udp (UDP) that has a record wins, with that record's targets and ports. Without any SRV record it uses UDP on port 5060. There is no NAPTR lookup. An IP address or an explicit host:port skips SRV and uses UDP.

  • status / account.get report transport: "auto" and transport_effective (udp|tcp|tls) once a transport was picked; the GUI shows it as "TLS (auto)".
  • The choice is made when the transport is built and again whenever the network is re-probed ([network]): a changed answer rebuilds the transport and re-registers, like any other change of next hop. While the account has calls the transport is kept; the next probe without calls re-selects.
  • With auto and tls_verify, tls_ca_file, tls_fingerprint etc. apply only if TLS is the one picked.

Media and SRTP ​

OptionTypeDefaultReloadDescription
srtpoff|optional|mandatory"optional"next calloff: plain RTP only (SAVP-only offers get 488). optional: offer RTP/AVP plus a=crypto (OSRTP-style) and use SRTP if the peer does too; if the PBX refuses the offer (488/415/606) the call is retried once with plain RTP (srtp_fallback in the call snapshot); once the plain retry gets a final 2xx the refusal is remembered per destination (next hop host:port[:transport], max 64): later calls to it offer plain RTP first, and if that is refused (488/415/606) they retry once with the OSRTP offer and forget the destination when that retry gets a final 2xx (a redirect re-evaluates for the new destination; calls cancelled while ringing change nothing); srtp_optional_downgraded in status / account.get lists the remembered destinations; cleared when srtp, registrar, outbound_proxy, domain, transport, codecs or srtp_suites change, and on an account rebuild or re-probe rebuild. Some PBXes (FreeSWITCH without rtp_allow_crypto_in_avp=true) build the callee leg before refusing, so the first call rings the callee twice: against such a PBX use srtp = "off" or "mandatory". mandatory: RTP/SAVP only; offers without acceptable crypto get 488.
srtp_suitesarray["AES_CM_128_HMAC_SHA1_80","AES_CM_128_HMAC_SHA1_32"]next callOffered/accepted SDES suites in preference order; also AES_256_CM_HMAC_SHA1_80/32 (alias AES_CM_256_...). Required (non-empty) unless srtp = "off".
codecsarray[]next callCodec order override; [] = inherit [media].codecs.
dtmf_modestring""next callrfc4733|info|inband|auto override; "" = inherit [media].dtmf_mode.
audio_sourcestring"device"next callDefault transmitted audio: device (microphone), silence, tone:<hz>, file:<path.wav> (looped). For headless/CI runs use tone: or silence.
audio_sinkstring"device"next callDefault received audio: device (speaker), null, record:<path.wav>.

Call behaviour ​

OptionTypeDefaultReloadDescription
dndboolfalsehotDo not disturb: reject incoming calls (call.rejected with reason dnd). Also settable at runtime (account.set_dnd) until this field changes.
dnd_reject_codeint486hotSIP status for DND rejects; 400..699.
auto_answerboolfalsehotAnswer incoming calls automatically.
answer_delay_msint0hotDelay before auto-answering; at most 60000.
allow_intercomboolfalsehotAlso auto-answer on Call-Info: answer-after / Alert-Info intercom/paging requests.
auto_holdbooltruehotAnswering or dialing puts the other active device-bound calls on hold (all accounts' with [calls] hold_scope = "all", this account's with "account"). false also exempts this account's calls from being auto-held.
hold_stylesendonly|inactive"sendonly"hotSDP direction when we hold. sendonly becomes inactive automatically if the remote already holds us.
hold_send_cnboolfalsehotSend periodic comfort noise while holding (keeps PBX media timeouts quiet).
follow_redirectsbooltruehotFollow 3xx on outgoing calls (max 3 hops).
auth_foreignboolfalsehotAnswer digest challenges (401/407) from servers that are not your provider. Default: a challenge is answered only when the address the request was actually sent to belongs to your provider: the outbound_proxy / registrar / domain addresses and every address the outbound proxy / registrar resolved to (all SRV / A results, kept while the runtime for those hosts lives; the AOR domain is not resolved when a separate registrar is set). The request-URI, Contact and Record-Route are never trusted. Otherwise the call / request fails with Authentication refused: <ip> is not your provider (set auth_foreign = true ...) and no Authorization header is sent. true = answer everything (a rogue host can then collect a crackable digest of your password); needed only if your provider uses servers outside that set, e.g. an unrelated Record-Route edge.
max_callsint4hotConcurrent calls; further INVITEs get 486. At least 1.
prackdisabled|supported|required"supported"hotReliable provisional responses (RFC 3262) when we answer. disabled: never (420 to Require: 100rel, 100rel not advertised). supported: reliable 180 only if the caller sends Require: 100rel. required: reliable 180 whenever the caller lists 100rel in Supported or Require. The 200 waits for the PRACK; the 180 is retransmitted at T1, 2T1, ... and the call is rejected with 504 after 64T1 without PRACK. Outgoing calls PRACK reliable 18x unless disabled.
session_timersbooltruehotRFC 4028. Advertises Supported: timer; sends Session-Expires/Min-SE on outgoing calls; as UAS honours the caller's interval (422 + Min-SE below min_se) and picks the refresher (the caller if it supports timer, else us). The refresher role refreshes at half the interval with UPDATE (if the peer's Allow has it) or a re-INVITE with an unchanged SDP (o= version stays); a peer that fails to refresh before interval - min(32, interval/3) gets a BYE (Reason: SIP;cause=408, call ends with code 408). false: Session-Expires ignored, Require: timer gets 420.
session_expiresint1800hotSession-Expires requested on outgoing calls, seconds; 1..86400 and at least min_se.
min_seint90hotMin-SE: shortest interval accepted (and sent on outgoing calls), seconds; 1..86400. RFC 4028 sets a floor of 90; lower values are allowed so tests can run short sessions.
accept_referbooltruehotAccept incoming REFER (act as transferee).
attended_refer_targetaor|contact"aor"hotIdentity in the Refer-To URI of attended transfers.
attended_refer_onoriginal|consult"original"hotDialog carrying the attended-transfer REFER (Replaces points at the other call).

Subscriptions, tracing ​

OptionTypeDefaultReloadDescription
mwisubscribe|unsolicited|off"subscribe"hot (resubscribes)subscribe: SUBSCRIBE to message-summary (unsolicited NOTIFYs are accepted too). unsolicited: only accept unsolicited NOTIFYs. off: ignore MWI.
mwi_uristring""hot (resubscribes)URI to subscribe on; "" = own AOR.
blf_expiresint600hot (resubscribes)Requested expiry of BLF subscriptions; 10..86400.
pickupoff|prefix|replaces"off"hotDirected pickup of ringing BLF extensions (call.pickup, the GUI "Pick up" action). off: not offered. prefix: dial <pickup_prefix><extension> on this account (or the entry's pickup_target). replaces (experimental, PBX support varies): INVITE the monitored URI with Replaces. Per-entry override: [[account.blf]] pickup. No resubscribe.
pickup_replaces_targetcaller|monitored"caller"hotWith pickup = "replaces" (experimental): INVITE the caller (RFC 5359) or the monitored phone.
pickup_prefixstring"**"hotFeature code dialled before the extension with pickup = "prefix" (** is the FreePBX / FreeSWITCH directed-pickup code; Asterisk setups often use *8 for group pickup). No whitespace.
sip_tracebooltruehotWrite the wire-level SIP trace <log dir>/sip/<id>/sip.<date>.log (retransmits, keep-alives and unparsable messages included) and keep a per-call ring for call.sip_trace. Runtime override: account.set_sip_trace.

[[account.blf]] ​

Busy-lamp-field watch list; add the tables directly after the account they belong to. Adding, removing and editing entries is hot (the list is diffed by uri). Only a changed uri resubscribes; label, group and all pickup* keys apply immediately without touching the subscription.

OptionTypeDefaultDescription
uristring(required)Extension or full SIP URI to monitor (Event: dialog). Unique within the account; no whitespace.
labelstring""Human-readable label shown in the GUI and status.
groupstring""Group the entry belongs to in the GUI and in blf.list; "" = grouped by account.
pickup""|off|prefix|replaces""Per-entry override of the account's pickup; "" = inherit. off hides pickup for this entry.
pickup_prefixstring""Per-entry override of the account's pickup_prefix; "" = inherit.
pickup_targetstring""With prefix: dial exactly this instead of <pickup_prefix><extension> (queue pickup codes, park slots). Extension, user@host or sip: URI.

Directed pickup ​

Pickup is offered only while the entry is ringing (an incoming early dialog at the monitored phone), its state is fresh (not stale, subscription active) and the resolved method (entry override, else account) is not off; otherwise call.pickup fails with invalid_state. It goes through the normal dial path, so auto_hold applies as for any call; a refusal (404, 480, 486, ...) ends the call with that code.

  • prefix dials pickup_target if set, else <pickup_prefix><extension> on the entry's account. The extension is the user part of uri (sip:1004@pbx and 1004 both give 1004). Example: **1004.
  • replaces (experimental, not interop-verified): INVITE with Require: replaces and Replaces: <call-id>;to-tag=<remote-tag>;from-tag=<local-tag>;early-only, built from the dialog-info of the ringing dialog. The tags are those of the UA that originated the dialog (RFC 3891 reads them from the receiver's point of view; dialog-info reports the monitored phone's view, so its remote-tag is the originator's local tag). By default (RFC 5359 §2.16) the INVITE goes to the caller: the <remote> target of the dialog-info, falling back to the remote identity; RFC 3891 §4 forbids replacing an early dialog on a UA that did not originate it. pickup_replaces_target = "monitored" sends it to the monitored URI instead (B2BUA setups where the PBX originated the callee leg): only the Request-URI changes, the tags stay the same. Call-id, tags and target must be well-formed (RFC 3261 word / token, no control or format characters; NOTIFY content is untrusted) and the notifier must send them; otherwise the pickup fails with invalid_state. Use prefix there.
  • Routing. Every pickup is sent through the account's outbound proxy / registrar, whatever host the target names, so a NOTIFY cannot steer the INVITE (or the digest credential) to another host. A target taken from a NOTIFY is reduced to sip[s]:user@host[:port]: URI parameters (maddr, transport, ...) and ?headers are dropped.
toml
[[account]]
pickup = "prefix"       # off | prefix | replaces
pickup_prefix = "**"

[[account.blf]]
uri = "1004"
label = "Support queue"
group = "Support"
pickup = "replaces"     # optional per-key override
pickup_target = ""      # optional: dial this instead of <prefix><ext>

BLF subscription health ​

blf.list (and status) report per entry subscription {phase, last_code, last_reason, expires_at, retry_at} and stale. phase is pending, active, retrying (an attempt is scheduled at retry_at) or failed (refused for good, last_code is the SIP status). stale is true while retrying (the last known state stays and retry_at says when the next attempt runs) and when neither a NOTIFY nor a refresh arrived within 30 s after expires_at; the last known state is kept. With many entries consider a longer blf_expires: each entry is its own SUBSCRIBE dialog.

Vendor profiles ​

profile = "yealink" | "polycom" | "cisco" | "grandstream" makes an account behave like a desk-phone family by filling in defaults. Precedence: explicit option in the file > profile value > built-in default. An option counts as explicit when its key is present in the account's table; for the two "empty = inherit" options (user_agent, dtmf_mode) an empty string counts as not set, so the shipped example (which lists every key) can simply gain a profile line.

Profiles are resolved while the file is parsed (so a reload re-resolves them); config.get shows the resolved values, and saving that text back makes them explicit. The bundles are best-effort approximations of factory behaviour (the User-Agent strings are realistic, the protocol details are not certified); override any single value in the account.

Optiongeneric (built-in)yealinkpolycomciscograndstream
user_agent[general].user_agentYealink SIP-T54W 96.86.0.70PolycomVVX-VVX_450-UA/6.4.4.5239Cisco-CP-8845-3PCC/12.0.1Grandstream GXP2170 1.0.11.74
hold_stylesendonlysendonlysendonlyinactivesendonly
dtmf_modeinherit (auto)rfc4733rfc4733rfc4733rfc4733
dnd_reject_code486480486480486
attended_refer_target (Refer-To form)aoraorcontactcontactaor
pracksupporteddisabledsupportedsupporteddisabled
session_timerstruefalsetruetruetrue

Allow is the same for all profiles; Supported follows the bundle (replaces, plus 100rel unless prack = "disabled", plus timer with session_timers).

Validation summary ​

A file is rejected (nothing is applied) when: it is not valid TOML or has unknown keys; account ids are empty, malformed or duplicated; an enabled account lacks username/domain; ranges above are violated; tls_fingerprint is not a SHA-256 hex string; password_store = "keyring" has a non-empty password; session_expires is below min_se; tls_cert and tls_key are not set together; control.tcp_listen is not a loopback address; network.probe_secs / network.debounce_ms / keepalive_fail_threshold are out of range; log_level is not a valid filter; calls.decline_code is not 400-699 or a [ui.shortcuts] entry has an unknown action or a malformed chord; or [speech] has an unknown placeholder, an out-of-range timeout or a malformed voice/language. Missing TLS files only produce warnings.

Files written next to the config ​

FilePurpose
state.tomlApp-owned runtime state that is not a setting (settings, audio devices included, live in config.toml). Today it holds first_run_completed: the GUI's first-run wizard was finished or skipped (delete the file to see the wizard again). Absent while there is none. Safe to delete.
runtime.jsonApp-owned, mode 0600: pid, control endpoints, per-run token. Removed on clean shutdown (a stale one after a crash is harmless).
siple.lockSingle-instance lock (one instance per config directory).
control.sockControl socket (macOS/Linux), unless overridden or too long a path.
logs/siple.<date>.log, logs/sip/<id>/sip.<date>.logApplication log and per-account SIP traces (daily rolling).

Source-available under FSL-1.1-ALv2. Questions: oss@zyno.io