Configuration

lnsd reads the same INI-style configuration file as Python Reticulum (rnsd). The format is a drop-in: a config that rnsd accepts, lnsd accepts, and the two share the shared-instance IPC socket so client tools (rnstatus, rncp, lnstest diag, Sideband, Nomadnet) attach to either daemon without changes. Keys lnsd does not implement are tolerated, not rejected — an unknown key never makes lnsd refuse a config a current rnsd would load (ini_config.rs:435-440).

File location and lookup order

Pass an explicit config directory with --config DIR (lnsd.rs, -c/--config). With no flag, lnsd resolves the directory using the same order as Python Reticulum (config.rs:701-718):

1. /etc/reticulum — if /etc/reticulum/config exists
2. $HOME/.config/reticulum — if that directory's config exists
3. $HOME/.reticulum — fallback, used even if absent

The config file is always named config inside that directory (config.rs:720-722). The storage directory defaults to <config_dir>/storage and can be overridden with --storage (lnsd.rs, -s/--storage).

This order is why the Debian package can install a system-wide config under /etc/reticulum and have Python clients connect to the live daemon with no extra flags (config.rs:707-711).

INI vs TOML detection

lnsd accepts both the Python INI format and native TOML. Detection is by content, not just extension (config.rs:662-689):

• An explicit .toml extension forces TOML.
• A file containing [[ (the ConfigObj subsection marker Python uses for interfaces) is parsed as INI.
• Otherwise TOML is tried first, then INI as a fallback.

In practice your config file uses the Python INI form shown throughout this page. Boolean values accept Yes, yes, True, true, 1, on (and their false counterparts); anything else is read as false (ini_config.rs:929-940).

A file with a syntax error is refused

A line that is neither a section header nor a key = value pair is a parse error, and lnsd exits non-zero without starting rather than reading the rest of the file as nothing (ini_config.rs:207-209). The error names the line number and the line, and where the format is ambiguous it reports both the INI and the TOML verdict (config.rs:949-956):

$ lnsd --config /etc/reticulum
lnsd: configuration error: Failed to parse config /etc/reticulum/config: not
valid Reticulum INI (Invalid line 1 ('[reticulum'): matched as neither section
nor keyword) and not valid TOML (...)

This is the reference's behaviour, not a house rule: ConfigObj raises Invalid line ('[reticulum') (matched as neither section nor keyword), and rnsd logs Could not parse the configuration at <path> and exits 255 (RNS/Reticulum.py:330-333). Every bracket shape ConfigObj accepts still loads here, including a header with a trailing comment ([reticulum] # note) and [reticulum = x, which ConfigObj reads as a key rather than a header (ini_config.rs:44-62).

What is NOT refused, because the reference does not refuse it either: an interface whose type we do not implement is skipped with a warning and the daemon runs with the rest (ini_config.rs:317-323), the same way rnsd logs Could not locate external interface module and carries on. A key in a section lnsd does not read is likewise kept out of the config and logged (ini_config.rs:178-191).

The [reticulum] section

Core daemon settings. Every key below is parsed in ini_config.rs:389-571; defaults come from config.rs:394-430.

control_channel_capacity and data_channel_capacity are read from TOML only; they have no INI key in apply_reticulum_key (ini_config.rs:389-571) and are best set in a TOML config or left at their defaults.

storage_path is read from both formats and resolves in one order everywhere: lnsd --storage, then the config key, then <config_dir>/storage (Python's only choice, Reticulum.py:246). The client tools resolve it the same way (resolve_storage_path, config.rs:1130), so lnstatus, lncp, lnpath and lnprobe open the same directory as the daemon and derive the same RPC authkey from its transport_identity. Point the key at an external disk and nothing else has to be told about it — but note that --storage moves the daemon alone, and the clients then still follow the config.

flush_interval and keepalive_interval are Leviculum tuning extensions — Python Reticulum ignores them. Battery-powered or SD-card deployments may want a longer flush_interval; slow links benefit from a fixed keepalive_interval:

[reticulum]
  # Seconds between periodic storage flushes (crash protection only,
  # normal shutdown always flushes). Default: 3600.
  flush_interval = 3600

  # Link keepalive interval in seconds. When set, every link uses this
  # interval instead of the RTT-derived default. Default: unset.
  keepalive_interval = 360

Table ceilings (Codeberg #421)

Every transport table has a maximum size, and a full table evicts rather than refuses: the new entry always lands, an old one goes. Without a ceiling each table's real bound was arrival rate times expiry window — a number the neighbours choose, not the operator.

The eviction order is oldest-first for most tables and argued per table in TableCaps and the field docs of memory_storage.rs; three tables deviate, because plain FIFO would do damage there: link_table drops an unvalidated link request before a live link, announce_cache drops an unretained destination before a pinned one, and receipts drops a terminal receipt before a pending one — and a pending one it does have to drop is still reported as a timeout, which is what Python does on the same overflow (Transport.py:558-561).

The defaults are entries × modelled bytes from the same model the lnstatus diagnostic dump prints, not round numbers: desktop totals about 339 MB across the tables these keys bound, compact about 22 MB. Pick the profile first and override individual tables only where the deployment differs:

[reticulum]
  # A Pi Zero 2W with a busy uplink: compact everywhere, but a reverse
  # table large enough for the traffic it actually forwards.
  storage_profile = compact
  reverse_table_cap = 40000

The [interfaces] section

Interfaces are ConfigObj subsections under [interfaces], each named in double brackets [[Name]]. The name is free-form; the type key selects the interface implementation. Twelve types pass the supported-type filter (interface_type (ini_config.rs:301-326)):

TCPServerInterface, TCPClientInterface, UDPInterface, AutoInterface, RNodeInterface, RNodeMultiInterface, SerialInterface, PipeInterface, KISSInterface, AX25KISSInterface, I2PInterface, BLEInterface.

BackboneInterface and BackboneClientInterface are accepted too: they are wire-identical to TCP and are mapped onto the TCP interface at parse time, as Python does (normalize_backbone_interface (ini_config.rs:853-883)). An interface of any other type is skipped with a log line (tracing::warn (ini_config.rs:317-322)), not an error.

The per-type tables below cover the six types most deployments use. All interface keys are parsed in apply_interface_key (ini_config.rs:617-835); the struct they land in, with its defaults, is InterfaceConfig (config.rs:242-520).

Keys common to every interface

TCP server (TCPServerInterface)

[interfaces]
  [[Loopback TCP]]
    type = TCPServerInterface
    enabled = Yes
    listen_ip = 127.0.0.1
    listen_port = 45999

TCP client (TCPClientInterface)

[interfaces]
  [[RNS TCP Node Germany 002]]
    type = TCPClientInterface
    enabled = Yes
    target_host = 193.26.158.230
    target_port = 4965

UDP (UDPInterface)

Bind and forward are independent, as in rnsd: an interface with only bind parameters receives without transmitting, one with only forward parameters transmits without listening, and only an interface that would do neither is a configuration error.

AutoInterface (AutoInterface)

Discovers other Reticulum nodes on the same broadcast domain via multicast. No router or DHCP needed; the link must carry multicast.

BLE (BLEInterface)

Joins the Columba BLE mesh (the ble-reticulum protocol, v2.2 wire format with the v0.3.0 capability record) as a dual-role BlueZ node: it advertises and serves the Columba GATT layout like an LNode board does, and it scans for and connects to nearby peers under the same connection-direction rule the boards and phones apply. One section is one Reticulum interface — a single broadcast domain across all live BLE links. Requires a BlueZ (bluetoothd) host with a BLE-capable adapter; if the adapter is missing or powered off at startup the interface keeps retrying rather than failing the daemon.

The interface is off unless a [[BLE Interface]] section exists in the config; the daemon never brings BLE up on its own. The advertised name is derived from the daemon identity as LN-<hex8> exactly like the firmware's, so scanner listings show lnsd and boards the same way.

Key names follow the reference ble-reticulum package where its options map onto this implementation:

[interfaces]
  [[BLE Interface]]
    type = BLEInterface
    enabled = yes
    # device = hci0
    # max_connections = 4
    # min_rssi = -85
    # Dial nothing but these two; still answer anyone who dials us.
    # initiate_only = b2a8bea1, AA:BB:CC:DD:EE:FF
    # Serve nothing but these two; a stranger's connection is refused.
    # accept_only = b2a8bea1, AA:BB:CC:DD:EE:FF

A node that should be a leaf rather than a hub — one uplink out, still reachable from anybody near it — is initiate_only naming that uplink. A node that should be a leaf and invisible as well adds enable_peripheral = no, which is the stronger statement: it stops advertising, so no peer can dial it either.

The two keys answer independent questions and accept_only is the one for a room the operator does not control. enable_peripheral = no refuses every incoming link, including the ones the deployment wants; accept_only names the set it wants and refuses the rest, which is what a measurement in a flat needs — a Faraday cage stops LoRa, it does not stop the phone in someone's pocket from dialling a Columba advertiser. Setting both keys to the same list pins a closed mesh: we dial nobody else and we serve nobody else. Setting neither is the default and is what every existing deployment does.

RNode and Serial (RNodeInterface, SerialInterface)

RNodeInterface drives an RNode LoRa modem; SerialInterface is a raw serial HDLC link. They share the serial-port and LoRa keys.

Divergence from Python: there, only RNodeInterface honours the LoRa keys (frequency, bandwidth, spreadingfactor, codingrate, txpower) and SerialInterface reads port settings only. Leviculum's SerialInterface honours them too and configures the attached LNode's radio over the serial port — the LNode frames HDLC, so it cannot be driven by the KISS-framed RNodeInterface.

Serial keys:

LoRa keys, derived from source — the meanings below describe the radio parameters the interface configures; the fields sit together in the RNode block of InterfaceConfig (InterfaceConfig::frequency (config.rs:623-654)):

A board that does not take the config

A SerialInterface with a LoRa block pushes the radio config at the board up to three times, waiting 2 s for the firmware's ACK each time. Then — ACK or no ACK — it sends the radio query (TYPE_RADIO_QUERY, Codeberg #349) and waits a further 2 s for the board's report, which the firmware answers out of what its LoRa task actually configured. The ACK alone does not settle it: the legacy config frame's entire vocabulary is three bytes or silence, so a board that only wrote the config to its flash page acks it exactly like a board that keyed it (Codeberg #363).

• Report received, same profile — the board is running what was asked for. The interface comes up on it. (Without an ACK this is the same outcome: the config did arrive, only its receipt did not.)
• Report received, different profile — the interface comes up priced at the profile the board reported, and logs RADIO_BRINGUP iface=<name> outcome=running-differs with the requested and the running parameters side by side.
• Query refused as busy or not-running — the board is talking and says no radio is running this boot, which on an LNode means it booted lora=off. The interface refuses to come up and logs RADIO_BRINGUP iface=<name> outcome=dead-radio lora=off. An ACK does not change this; it is the case that ACK is unable to distinguish.
• Neither answered — the interface refuses to come up. It logs RADIO_BRINGUP iface=<name> outcome=refused naming both frames and both waits, reports Down to rnstatus, and the daemon keeps running with its other interfaces. It does not retry on that port; fix the board and restart.

Both refusals report Down to rnstatus and leave the rest of the daemon running.

A modem the host cannot price is a modem the host does not drive. Airtime accounting and transmit spacing are computed from the PHY, so an interface pricing SF7 in front of a board keying SF12 under-counts duty by an order of magnitude and hands the serial queue frames faster than the modem can key them; guessing the other way is a silent lie about airtime that nothing downstream can tell from a measurement.

Firmware older than #349 does not answer the radio query — it refuses it as a frame it does not know, or says nothing. That is not a board stating its radio is off, so such a board still comes up on its ACK, with a debug line saying the running profile could not be read; an LNode running it that also misses the config ACK is refused rather than driven blind. (radio_bring_up, radio_pricing_phy (interfaces/serial.rs))

Test-only: test_drop_direct_ingress (bool, default off) emulates out-of-range placement on a co-located rig: the interface drops every received frame whose wire hops byte (raw[1]) is 0 — frames heard directly from their originator — before they reach the transport, while relayed copies (hops ≥ 1) pass. Two endpoints with this knob on one bench are mutually deaf but both hear a relay, giving the A–B–C repeater topology without attenuators; the consumer is the 3-node relay hardware scenario (periculum hardware/lora_3node_relay.toml). Python-RNS has no such option — frames are dropped locally on ingress and nothing on the air changes, so this is a test-harness affordance, not a wire or semantic deviation. Supported on RNodeInterface and SerialInterface; incompatible with IFAC (which prepends material before the flags byte), and that combination is refused at startup.

IFAC (Interface Access Codes)

IFAC keys apply to any interface and authenticate / isolate a virtual network on the link. They are common to all interface types:

networkname and passphrase are secrets: lnstest diag redacts them before serialising a bundle (see the lnstest diag section).

Example configurations

Simple AutoInterface node

A node that talks to other Reticulum peers on the same LAN, no transport routing:

[reticulum]
  enable_transport = No
  share_instance = Yes

[interfaces]
  [[Default Interface]]
    type = AutoInterface
    enabled = Yes

TCP-server transport node

A routing entrypoint that accepts inbound TCP peers and bridges them with the local LAN:

[reticulum]
  enable_transport = Yes
  share_instance = Yes
  instance_name = entrypoint

[interfaces]
  [[Public TCP]]
    type = TCPServerInterface
    enabled = Yes
    listen_ip = 0.0.0.0
    listen_port = 4965

  [[Local LAN]]
    type = AutoInterface
    enabled = Yes

LoRa RNode node

A node on a LoRa RNode modem (radio values below are an EU 868 MHz example; set them for your region and hardware):

[reticulum]
  enable_transport = Yes
  share_instance = Yes

[interfaces]
  [[LoRa RNode]]
    type = RNodeInterface
    enabled = Yes
    port = /dev/ttyACM0
    frequency = 867200000
    bandwidth = 125000
    spreadingfactor = 8
    codingrate = 5
    txpower = 14

See the upstream Reticulum Manual for the protocol-level meaning of the radio and IFAC parameters.