#include <config.h>
Public Types | |
| enum class | Security { Noise , Plaintext } |
| Secure channel to use for peer connections. More... | |
Public Attributes | |
| uint16_t | listen_port = 0 |
| Listen port for inbound peers. | |
| bool | enable_listen = true |
| bool | enable_tcp = true |
| Accept and dial over TCP. | |
| bool | enable_udp = true |
| Accept and dial over the datagram transport. | |
| TransportKind | preferred_transport = TransportKind::Udp |
| Which transport a dial tries first. | |
| uint32_t | transport_fallback_ms = 1200 |
| How long the preferred transport dials alone before the other one is raced alongside it. | |
| CongestionAlgorithm | congestion_control = CongestionAlgorithm::Bbr |
| Congestion controller every datagram stream runs. | |
| size_t | udp_receive_window = 0 |
| Bytes one UDP connection's flow-control window may grow to. | |
| size_t | udp_receive_budget = 0 |
| Bytes all UDP connections together may hold out of order. | |
| std::chrono::milliseconds | udp_idle_timeout {0} |
| Silence from a peer after which its UDP connection is closed as lost (CloseReason::IdleTimeout); keep-alives go out at least four times within it. | |
| bool | udp_offload = true |
| Whether UDP uses the kernel's segmentation offload where the running system has it (Linux UDP_SEGMENT/UDP_GRO, Windows USO/URO): a run of packets to one peer then crosses the network stack as one buffer, which is most of the CPU difference between a user-space stream and kernel TCP. | |
| size_t | send_queue_limit = 0 |
| Bytes a peer's send queue may hold before an application that keeps sending anyway has the peer dropped as a slow consumer. | |
| uint32_t | path_sample_ms = 0 |
| How often each established peer's path is sampled for on_peer_path and path_stats() (see PathStats). | |
| std::string | bind_address = "" |
| Interface to bind the listener to. | |
| size_t | reactor_threads = 1 |
| Number of reactor threads. | |
| size_t | max_peers = 0 |
| Maximum number of established peers. | |
| Security | security = Security::Noise |
| std::string | protocol = "librats/1.0" |
| Application protocol identity, bound into the Noise handshake prologue, so two nodes whose protocol differs cannot complete a handshake — a cheap, cryptographically-enforced way to keep separate apps (or app versions) from cross-connecting. | |
| std::string | data_dir = "" |
| Directory for persistent state. | |
| bool | enable_network_monitor = true |
| Watch the host for network configuration changes (interface up/down, IP add/remove, route flip, wake-from-sleep) and publish NetworkChanged on the node's EventBus so subsystems can renew port mappings, re-run STUN and re-announce. | |
|
strong |
| std::string librats::NodeConfig::bind_address = "" |
Interface to bind the listener to.
The address family is derived from it:
| CongestionAlgorithm librats::NodeConfig::congestion_control = CongestionAlgorithm::Bbr |
Congestion controller every datagram stream runs.
BBRv3 by default: it keeps its rate on links that lose packets for reasons other than congestion (Wi-Fi, mobile, long hops), where a loss-based controller backs off on every one of them; Reno is there for comparison and for paths where a loss-based sender is specifically wanted. TCP connections are governed by the kernel and ignore this.
| std::string librats::NodeConfig::data_dir = "" |
| bool librats::NodeConfig::enable_network_monitor = true |
Watch the host for network configuration changes (interface up/down, IP add/remove, route flip, wake-from-sleep) and publish NetworkChanged on the node's EventBus so subsystems can renew port mappings, re-run STUN and re-announce.
Costs one mostly-idle monitor thread. See node/host_events.h.
| bool librats::NodeConfig::enable_tcp = true |
| bool librats::NodeConfig::enable_udp = true |
| uint16_t librats::NodeConfig::listen_port = 0 |
| size_t librats::NodeConfig::max_peers = 0 |
Maximum number of established peers.
0 means unlimited. The limit guards inbound connections (a flood is refused at accept, before any handshake); outbound dials we initiate are always honored. Runtime-adjustable via Node::set_max_peers().
| uint32_t librats::NodeConfig::path_sample_ms = 0 |
How often each established peer's path is sampled for on_peer_path and path_stats() (see PathStats).
0 samples nothing — unless an on_peer_path handler is registered, which asks for samples and gets them every 100 ms: about as often as an encoder can usefully change its rate, and still a fraction of a round trip on most paths.
| TransportKind librats::NodeConfig::preferred_transport = TransportKind::Udp |
Which transport a dial tries first.
UDP is the default because it is the better fit for peer-to-peer: every peer shares one socket and therefore one NAT mapping, the port a peer sees us send from is the port it can dial back, which is what makes hole punching possible at all, and no middlebox holds per-connection state that can be exhausted or timed out from under us. TCP remains a first-class equal, and is what the fallback below exists for — some networks block or throttle UDP outright.
| std::string librats::NodeConfig::protocol = "librats/1.0" |
Application protocol identity, bound into the Noise handshake prologue, so two nodes whose protocol differs cannot complete a handshake — a cheap, cryptographically-enforced way to keep separate apps (or app versions) from cross-connecting.
An opaque string compared for exact equality; by convention "<name>/<version>". Both peers must match. (Under Plaintext it is still checked, but not cryptographically bound — see PlaintextSecurity.)
| size_t librats::NodeConfig::reactor_threads = 1 |
| Security librats::NodeConfig::security = Security::Noise |
| size_t librats::NodeConfig::send_queue_limit = 0 |
Bytes a peer's send queue may hold before an application that keeps sending anyway has the peer dropped as a slow consumer.
0 uses the library default (8 MiB).
It is not a maximum message size. A single message is always queued whatever its size — a message cannot be sent by halves, and a healthy connection must not die over one large frame — so the queue's real ceiling is this plus one message. What gets a peer dropped is offering another message while the queue is still over the mark.
A quarter of this is the mark at which send() starts answering "no room" and on_peer_writable is what says the room is back — so lowering it makes an application feel backpressure sooner, and raising it lets a bursty one buffer more before anything is said. The two move together on purpose: a warning that arrives at the same moment as the disconnection is no warning at all.
| uint32_t librats::NodeConfig::transport_fallback_ms = 1200 |
How long the preferred transport dials alone before the other one is raced alongside it.
The first to complete its handshake wins and the loser is dropped, so a UDP-blocking network costs this delay rather than a failed connection. 0 disables the fallback: only the preferred transport is tried.
| std::chrono::milliseconds librats::NodeConfig::udp_idle_timeout {0} |
Silence from a peer after which its UDP connection is closed as lost (CloseReason::IdleTimeout); keep-alives go out at least four times within it.
0 uses the library default (45 s). Shorter finds a lost peer sooner — ReconnectionService then dials it again — and costs keep-alives.
| bool librats::NodeConfig::udp_offload = true |
Whether UDP uses the kernel's segmentation offload where the running system has it (Linux UDP_SEGMENT/UDP_GRO, Windows USO/URO): a run of packets to one peer then crosses the network stack as one buffer, which is most of the CPU difference between a user-space stream and kernel TCP.
Probed per socket and dropped on its own if the kernel refuses a send, so turning it off is for comparison and for hosts where it misbehaves.
| size_t librats::NodeConfig::udp_receive_budget = 0 |
Bytes all UDP connections together may hold out of order.
0 uses the library default (64 MiB). The bound on what peers can make this node buffer however many there are and however they fill their windows with holes; past it, out-of-order packets are refused (their senders repair them and slow down), except for a small share every connection keeps regardless.
| size_t librats::NodeConfig::udp_receive_window = 0 |
Bytes one UDP connection's flow-control window may grow to.
0 uses the library default (16 MiB). This is the ceiling, not where it starts: every connection starts at 1 MiB and grows while the window turns out too small for the path, which is what a long, fast one needs (the window bounds throughput at window / round trip — 16 MiB is ~1.3 Gbit/s at 100 ms). A window is a promise of room, not an allocation: only what arrives out of order is ever held, and that is bounded across all connections by udp_receive_budget.
