Struct Config 

pub struct Config {

    pub key_state: PersistState,
    pub client_name: Option<String>,
    pub control_server_url: Url,
    pub allow_http_key_fetch: bool,
    pub requested_hostname: Option<String>,
    pub requested_tags: Vec<String>,
    pub ephemeral: bool,
    pub reauth_on_expiry: bool,
    pub accept_routes: bool,
    pub accept_dns: bool,
    pub exit_node: Option<ExitNodeSelector>,
    pub advertise_routes: Vec<IpNet>,
    pub advertise_exit_node: bool,
    pub forward_tcp_ports: Vec<u16>,
    pub forward_udp_ports: Vec<u16>,
    pub forward_all_ports: bool,
    pub forward_exit_egress: bool,
    pub block_incoming: bool,
    pub exit_proxy: Option<ExitProxyConfig>,
    pub tcp_buffer_size: Option<usize>,
    pub persistent_keepalive_interval: Option<Duration>,
    pub enable_ipv6: bool,
    pub network_monitor: bool,
    pub wireguard_listen_port: Option<u16>,
    pub transport_mode: TransportMode,
    pub wire_ingress: bool,
    pub advertise_services: Vec<String>,
    pub advertise_app_connector: bool,
    pub auto_update_apply: Option<bool>,
    pub auto_update_check: bool,
    pub operator_user: Option<String>,
    pub node_nickname: Option<String>,
    pub posture_checking: bool,
    pub run_web_client: bool,
    pub exit_node_allow_lan_access: bool,
    pub taildrop_dir: Option<PathBuf>,
    pub auth_key: Option<String>,
    pub client_id: Option<String>,
    pub client_secret: Option<String>,
    pub id_token: Option<String>,
    pub audience: Option<String>,
}

Config for connecting to Tailscale.

Fields

key_state: PersistState

The cryptographic keys representing this node’s identity.

client_name: Option<String>

The name of this client.

This is reported to control in the Hostinfo.App field.

control_server_url: Url

The URL of the control server to connect to.

allow_http_key_fetch: bool

Allow fetching the control server’s machine public key (GET /key) over plain http when control_server_url is http://.

By default (false) the key bootstrap is always upgraded to https, even for an http:// control URL — so registration fails against a control plane that only serves plain http (e.g. a self-hosted Headscale on a http://host:port LAN endpoint / NodePort with no TLS). Set true for such a deployment. Only safe when you control both ends over a trusted network path; no effect when the control URL is https://. Fail-closed default is false.

requested_hostname: Option<String>

The hostname this node will request.

If left blank, uses the hostname reported by the OS.

requested_tags: Vec<String>

Tags this node will request.

ephemeral: bool

Whether this node registers as ephemeral.

This is the equivalent of tailscale up --ephemeral. An ephemeral node is garbage-collected by the control server shortly after it disconnects, which is the right default for short-lived clients. A long-lived node that must survive brief disconnects — such as a persistent exit node or subnet router — should set this to false, or control will GC it out of the tailnet while it is momentarily offline. Defaults to true.

reauth_on_expiry: bool

Whether to automatically re-authenticate when this node’s node key expires (rotate the node key + re-register with the stored auth key, Go doLogin) instead of going terminally offline.

Defaults to true: an auth-key-registered node whose key expires recovers itself automatically — the common reusable-auth-key deployment (a persistent exit node / subnet router) self-heals rather than requiring manual re-pairing. Set to false for the historical, most conservative behavior (an expired key surfaces DeviceState::Expired and the node stays offline until re-paired). Even when true, auto-reauth is gated on a usable auth key being retained and Tailnet Lock NOT being enforced; a one-shot auth key that was already consumed cannot re-register and degrades to the terminal state.

accept_routes: bool

Whether to accept (and route traffic to) subnet routes advertised by peers.

This is the equivalent of tailscale up --accept-routes. Defaults to false: only each peer’s own tailnet address is reachable. Set to true to use peers that act as subnet routers, so traffic destined for an advertised subnet egresses via the advertising peer.

accept_dns: bool

Whether to accept the tailnet’s DNS configuration (MagicDNS + pushed resolvers/search domains).

This is the equivalent of tailscale up --accept-dns (the CorpDNS pref). Defaults to true, matching Go’s NewPrefs(). When true, the MagicDNS responder serves the control-pushed DNS config. When false, the node ignores the pushed DNS config and the responder answers every query REFUSED — so a node can join the tailnet for connectivity without taking over its DNS. Runtime-settable via Device::set_accept_dns.

exit_node: Option<ExitNodeSelector>

The peer to route internet-bound traffic through (exit node).

This is the equivalent of tailscale up --exit-node. The peer may be named by stable node ID, tailnet IP, or MagicDNS name via ExitNodeSelector (a bare IP or name can be parsed with selector.parse()). Defaults to None: internet-bound traffic has no overlay route and is dropped (fail-closed). When set to a peer that advertises a default route, all traffic not matching a more-specific route egresses through that peer. The selection is re-resolved as the netmap changes.

advertise_routes: Vec<IpNet>

Subnet routes to advertise as a subnet router.

This is the equivalent of tailscale up --advertise-routes. Defaults to empty: this node advertises no routes. Each prefix is sent to the control server in HostInfo.RoutableIPs; once the route is approved, peers with accept_routes may send traffic for that subnet through this node. Only IPv4 prefixes are advertised — IPv6 prefixes are dropped to uphold the IPv6-off posture (we never forward IPv6, so advertising it would be a black hole).

advertise_exit_node: bool

Whether to advertise this node as an exit node.

This is the equivalent of tailscale up --advertise-exit-node. Defaults to false. When true, the default route 0.0.0.0/0 is advertised so that, once approved, other peers may route their internet-bound traffic out through this node’s real origin IP. Because that means other peers’ traffic egresses via our IP, it is strictly opt-in. ::/0 is never advertised (IPv6-off).

forward_tcp_ports: Vec<u16>

TCP ports the inbound forwarder accepts and splices to real OS sockets, for every advertised route (advertise_routes / advertise_exit_node).

Acting as a subnet router or exit node means inbound overlay flows to advertised destinations are dialed out as real OS connections (mirroring Go tsnet’s forwarders). The underlying netstack has no all-port accept mode, so the set of forwarded ports is explicit rather than the full 1–65535 range. Defaults to empty: a node may advertise routes but forward nothing until ports are configured (fail-closed — nothing is dialed).

forward_udp_ports: Vec<u16>

UDP ports the inbound forwarder accepts and splices to real OS sockets, for every advertised route. See forward_tcp_ports; defaults to empty.

forward_all_ports: bool

Forward all TCP/UDP ports (1–65535) on every advertised route, like a Go subnet router.

This is the equivalent of a tailscale up --advertise-routes node forwarding every port, instead of the explicit forward_tcp_ports / forward_udp_ports sets. When true, those explicit sets are ignored and the forwarder runs an on-demand per-port listener manager. Anti-leak is unchanged: every flow still routes through the same dialer chokepoint, so forward_exit_egress still governs exit-node egress. Defaults to false.

forward_exit_egress: bool

Whether exit-node (0.0.0.0/0) inbound flows are actually egressed via this host’s real origin IP.

Anti-leak opt-in, separate from advertise_exit_node: advertising the default route only offers this node as an exit to control; it does not by itself egress a peer’s internet-bound traffic. Defaults to false (fail-closed): the forwarder structurally refuses exit-node egress, dropping 0.0.0.0/0 flows at dial time rather than leaking them out our real IP. Set to true only on a node whose real IP is the intended egress (e.g. a residential exit), never on a host whose IP must stay hidden (e.g. a cloud VPS). Subnet routes are dialed identically regardless of this flag.

block_incoming: bool

Shields-up (Go tailscale set --shields-up / ipn ShieldsUp): when true, refuse all inbound connections from peers that terminate on this node. The packet filter drops inbound packets destined to this node’s own addresses; forwarded subnet/exit transit and replies to connections this node itself initiated are unaffected. Defaults to false.

exit_proxy: Option<ExitProxyConfig>

Optional upstream proxy that exit-node egress is routed through, so the node egresses via the proxy’s IP rather than its own origin IP.

This is a product capability beyond strict Go tsnet parity: it lets a cloud exit node route the traffic it egresses through a residential proxy provider configured by the deployer, so the cloud host’s real IP never appears upstream. Only consulted when forward_exit_egress is true. When Some, the forwarder is wired with a SOCKS5 / HTTP CONNECT proxy dialer that fails closed — any proxy connect or handshake failure drops the flow rather than dialing direct, so the real IP never leaks. When None (the default) and exit egress is enabled, egress uses this host’s real IP. See the proxy-egress section of the repo’s AGENTS.md/CLAUDE.md.

tcp_buffer_size: Option<usize>

Per-direction TCP send/receive buffer size (bytes) for the userspace netstack, or None to use the netstack default (256 KiB per direction, ~512 KiB per socket).

The underlying smoltcp stack has no TCP window auto-tuning, so this value is the hard cap on a single flow’s bandwidth-delay product: at an 80 ms RTT a 16 KiB window throttles a flow to ~1.6 Mbps, which visibly slows large model-API responses even at 1x. Each socket allocates this size for both its rx and tx buffer, so a socket consumes ~2× this value. The default (256 KiB) suits high-RTT links carrying a few large flows; lower it on memory-constrained deployments running many concurrent sockets. Applies to both the application and forwarder netstacks.

persistent_keepalive_interval: Option<Duration>

WireGuard persistent-keepalive interval applied to every peer, or None to disable (PersistentKeepalive; this is the equivalent of Tailscale setting PersistentKeepalive=25 on a peer when control marks it KeepAlive=true).

When Some(interval) (the default, Some(25s)), each peer emits an empty authenticated keepalive after interval of outbound silence, holding the path/NAT mapping warm. This is the load-bearing fix for idle DERP-relayed sessions wedging: on a userspace-netstack node whose only path to a peer is the relay, an idle session otherwise ages past expiry with no traffic to keep it warm and no timer to refresh it, so the next dial rehandshakes over a cold path and loops forever. The persistent keepalive re-arms unconditionally (unlike the reactive WireGuard §6.5 keepalive, which is armed only by inbound traffic and dies ~10s after the last inbound packet) and the empty packet deliberately does not advance the session’s rotation/expiry timers, so a genuinely dead peer is still detected and rekey still fires on schedule.

Set to None to opt out (e.g. an embedder that has its own keepalive strategy or only ever runs over a direct, always-warm path). The default is on because this fork’s primary deployment is the relayed case the wedge bites.

enable_ipv6: bool

Whether to enable IPv6 on the tailnet overlay (peer-to-peer reachability over the node’s Tailscale IPv6 address). Defaults to false: the node is IPv4-only on the overlay.

This is an opt-in for general embedders that want Go tsnet-style dual-stack overlay reachability. It is deliberately off by default to preserve this fork’s sacred anti-leak posture: its primary deployment is a privacy proxy / cloud exit node where IPv6 is disabled everywhere to prevent tunnel-bypass IP leakage. When false, behavior is byte-for-byte the historical IPv4-only path: the underlay binds 0.0.0.0:0, IPv6 candidates/STUN are refused, the netstack is handed no IPv6 overlay address, and MagicDNS answers AAAA as NODATA.

This flag governs only the overlay. It has NO effect on the exit-node / forwarder egress path: exit and subnet egress to the public internet stays hardcoded IPv4 in ts_forwarder regardless of this flag, so the residential-proxy / real-origin-IP isolation invariant can never be weakened by enabling overlay IPv6. On a host with IPv6 disabled at the kernel, the dual-stack overlay bind simply fails and the node stays inert on IPv6 rather than panicking.

network_monitor: bool

Whether to run an internal OS network-link monitor that automatically re-binds the underlay socket and re-probes connectivity (re-ping, re-STUN, re-netcheck) on a link change — a Wi-Fi switch, sleep/wake, or default-route change. Defaults to false.

Off by default to preserve this fork’s pure-engine posture (per AGENTS.md this is a pure engine, not a daemon): the embedder normally owns OS network-monitoring and calls Device::rebind itself. When false, the runtime starts zero extra monitor threads or sockets and behaves byte-for-byte as before; the manual Device::rebind path is always available regardless of this flag.

Enabling it requires the crate to be built with the network-monitor feature; setting this true without that feature is a hard error at device startup (never a silent no-op). In this slice the monitor has no OS backend wired yet, so enabling it spawns the supervisor against a no-op event source (the Linux/macOS backends land in later slices).

wireguard_listen_port: Option<u16>

The fixed UDP port magicsock binds for WireGuard + disco, or None for an OS-chosen ephemeral port (Go tailscaled --port; Go’s ListenPort). Defaults to None.

None (the default) preserves the historical behavior: the underlay socket binds 0.0.0.0:0 and the OS picks an ephemeral port (Go’s port 0). Some(p) pins the bind to port p so the node’s UDP endpoint is stable across restarts — what an operator behind a fixed-pinhole firewall needs (Go’s daemon defaults this to 41641, but the engine default stays None to keep today’s behavior). If p is already taken at startup the bind falls back to an ephemeral port rather than failing bring-up (mirroring magicsock’s rebind fallback): a port collision must not take the node down. A later Device::rebind re-prefers whatever port is currently bound, so a successful pin carries across rebinds.

Governs only the bound port — never the bind family: the IPv4-only-by-default, fail-closed underlay posture (enable_ipv6 alone widens the family) is unchanged.

transport_mode: TransportMode

How this node’s application overlay data path is realized.

Defaults to TransportMode::Netstack, the userspace smoltcp netstack used by the fork’s primary unprivileged proxy / exit-node deployment. TransportMode::Tun instead routes the node’s overlay packets through a real kernel TUN interface (for embedders that want the host OS networking stack to see the tailnet directly); it requires privileges (root / CAP_NET_ADMIN) and a platform with TUN support. This governs only the application data path — never the exit-node / forwarder egress path, which keeps its own IPv4-only userspace netstack.

wire_ingress: bool

Whether to ask control to wire this node up server-side for Tailscale Funnel, even when no Funnel endpoint is currently active (Go tsnet’s “would like to be wired up for Funnel” signal, HostInfo.WireIngress, capver 113).

When true, registration and map requests set HostInfo.WireIngress so control provisions the DNS / ingress records a Funnel node needs, making a later Device::listen_funnel (or serve) session work immediately. Defaults to false (fail-closed): a node requests Funnel wiring only when explicitly opted in.

Note this fork cannot yet terminate public Funnel ingress — Device::listen_funnel is fail-closed (no client-side ACME engine, and a self-hosted control plane provides no public ingress relay). Setting this flag only requests server-side wiring; it does not by itself make Funnel live.

advertise_services: Vec<String>

VIP services this node advertises that it hosts (svc:<dns-label> names), the advertise side of Tailscale VIP services (Go tsnet’s Hostinfo.ServicesHash + c2n GET /vip-services).

Each entry is a full svc:-prefixed name. The valid names (each validated as a well-formed svc:<dns-label>; malformed names are dropped and logged) are hashed into HostInfo.ServicesHash on registration and every map request, and reported when control fetches the hosted-service list via the c2n /vip-services endpoint. Defaults to empty: advertise nothing (the hash is "", behavior unchanged). Actually hosting a service still requires control to assign it a VIP and the node to be tagged.

advertise_app_connector: bool

Whether to advertise this node as an app connector (tailscale set --advertise-connector, Go Prefs.AppConnector.Advertise). Defaults to false.

When true, registration and every map request set HostInfo.AppConnector = Some(true), mirroring Go’s applyPrefsToHostinfoLocked (hi.AppConnector.Set(prefs.AppConnector().Advertise)). This advertises only the capability to control — the faithful engine minimum, exactly the boundary Go draws between advertising and the data path. The app-connector data path itself (control-pushed connector domain routes, the 4via6 domain→route mapping, the per-domain DNS observation that learns target IPs) is a separate subsystem this fork does not implement, so a node advertising this serves no connector traffic until that layer exists — identical in effect to Go advertising the bool before control has assigned any domains.

auto_update_apply: Option<bool>

Whether this node opts in to admin-console-triggered auto-updates (tailscale set --auto-update, Go Prefs.AutoUpdate.Apply). Defaults to None.

When Some(true), registration and every map request set HostInfo.AllowsUpdate = true, mirroring Go’s applyPrefsToHostinfoLocked (hi.AllowsUpdate = … || prefs.AutoUpdate().Apply.EqualBool(true)), so the admin console knows the node accepts remote update triggers. This advertises the bool only: this fork runs no updater (it is an embeddable engine, not a packaged daemon), so it never applies an update — the self-update machinery is a daemon / OS-package concern. Some(false) and None both leave AllowsUpdate unset (advertise that the node does not accept remote updates); the tri-state mirrors Go’s opt.Bool (unset vs explicitly-off vs on).

auto_update_check: bool

Whether a background updater should check for available updates (Go Prefs.AutoUpdate.Check). Defaults to false.

Carried pref only — the engine never acts on it and it is never sent to control. In Go this gates a purely local background update-check loop in the daemon; it is not part of Hostinfo and never crosses the control wire. This fork has no updater (engine, not daemon), so the value is stored and threaded through to ts_control::Config solely so a downstream daemon can carry the pref. Storing it (rather than dropping it) is the faithful mirror of tsnet’s pref state.

operator_user: Option<String>

The OS username permitted to operate this node over a local management API (tailscale set --operator, Go Prefs.OperatorUser). Defaults to None.

Carried pref only — the engine never acts on it and it is never sent to control. In Go this is purely a daemon-side LocalAPI authorization check (which Unix uid may drive the daemon without root); it never touches the control protocol. This fork is a pure engine with no local API to gate, so the value is stored and threaded through to ts_control::Config solely for a downstream daemon that exposes a local API to consult. Faithful mirror of tsnet pref state.

node_nickname: Option<String>

A local display label for this node’s login profile (Go Prefs.ProfileName, set via tailscale switch / profile management). Defaults to None.

Carried pref only — the engine never acts on it and it is never sent to control. In Go this is a client-local cosmetic name for the login profile; it is never advertised in Hostinfo (distinct from the requested_hostname the node requests). The value is stored and threaded through to ts_control::Config solely for a downstream daemon’s profile UI. Faithful mirror of tsnet pref state.

posture_checking: bool

Whether device-posture identity collection is enabled (tailscale set --posture-checking, Go Prefs.PostureChecking). Defaults to false.

Carried pref only — the engine never acts on it and it is never sent to control. There is deliberately no Hostinfo.PostureChecking field to wire it to: posture is a control-to-node (c2n) pull mechanism — control requests posture attributes (serial numbers, etc.) from the node on demand — which this fork does not implement. With no c2n posture responder, control simply never pulls posture identity, byte-for-byte identical to the posture-disabled case, so storing the pref is the faithful mirror. The value is threaded through to ts_control::Config for a downstream daemon that implements the c2n posture endpoint.

run_web_client: bool

Whether this node runs a local web client (tailscale set --webclient, Go Prefs.RunWebClient). Defaults to false.

Carried pref only — the engine never acts on it and it is never sent to control. In Go this gates a daemon-hosted local web-client HTTP server (the device-management web UI on 100.x:5252); it is a separate subsystem, not advertised in Hostinfo. This fork has no web-client server, so the value is stored and threaded through to ts_control::Config solely for a downstream daemon that does. Faithful mirror of tsnet pref state.

exit_node_allow_lan_access: bool

Whether a peer using this node as an exit node may also reach this node’s local LAN (tailscale set --exit-node-allow-lan-access, Go Prefs.ExitNodeAllowLANAccess). Defaults to false.

Carried pref only for now — the engine does not yet act on it and it is never sent to control. In Go this is an OS-router route-shaping flag: when acting as an exit node it controls whether the host router excludes the local LAN ranges from the routes pulled through the tunnel. On a platform with no host router it has “no effect” — and this fork’s default data path is the userspace netstack, which has no host-route layer to shape. The value is stored and threaded through to ts_control::Config so a downstream daemon (or a future host-route layer in this engine) can consume it; until such a layer exists it is inert. Never advertised.

taildrop_dir: Option<PathBuf>

Filesystem directory that received Taildrop files land in, or None to disable Taildrop (the default, fail-closed).

When Some(dir) and a peerAPI port is configured (Taildrop is served on the shared peerAPI listener, so it needs the same bind), the runtime serves the Taildrop peerAPI route PUT /v0/put/<name> and writes incoming files under dir (created if absent). When None, no Taildrop server is run and a peer’s PUT is refused (403). The embedder consumes received files via the Device::taildrop_waiting_files / taildrop_open_file / taildrop_delete_file methods.

auth_key: Option<String>

Pre-auth key for non-interactive registration (Go tsnet.Server.AuthKey). When set, used as the registration auth key. If it is an OAuth client secret (prefix tskey-client-) and the identity-federation feature is enabled, it is exchanged for an auth key before registration. Falls back to the TS_AUTH_KEY env var (see auth_key_from_env). Defaults to None.

client_id: Option<String>

OAuth client ID for workload-identity federation (Go tsnet.Server.ClientID). SaaS-only; requires the identity-federation feature. With id_token or audience, the node exchanges an IdP-issued OIDC token for a Tailscale auth key. Defaults to None (TS_CLIENT_ID env fallback).

client_secret: Option<String>

OAuth client secret used to mint auth keys via OAuth (Go tsnet.Server.ClientSecret). SaaS-only; requires the identity-federation feature. Defaults to None (TS_CLIENT_SECRET).

Treat as fully operator-trusted input: a tskey-client-…?baseURL=… secret redirects the credential exchange to that host, so a hostile value would exfiltrate the secret and the minted auth key. Never source it from a less-trusted origin.

id_token: Option<String>

IdP-issued OIDC ID token to exchange with control for an auth key via workload-identity federation (Go tsnet.Server.IDToken). SaaS-only; requires the identity-federation feature and client_id. Mutually exclusive with audience. Defaults to None (TS_ID_TOKEN).

audience: Option<String>

Audience for requesting an OIDC ID token from the ambient workload identity (GitHub Actions / GCP / AWS), to exchange for an auth key via workload-identity federation (Go tsnet.Server.Audience). SaaS-only; requires the identity-federation feature + client_id. Mutually exclusive with id_token. Defaults to None (TS_AUDIENCE).

Implementations

impl Config

pub async fn default_with_key_file(p: impl AsRef<Path>) -> Result<Self, Error>

Create a new config with its key_state populated from the specified key file and using default options for other configuration.

See load_key_file for more details and an alternative with more options for reading the key file.

pub fn use_tun(self, name: Option<String>, mtu: Option<u16>) -> Self

Run the application overlay over a real kernel TUN interface instead of the default userspace netstack — a builder shortcut for setting transport_mode to TransportMode::Tun.

name is the desired interface name (None lets the OS pick, e.g. utunN on macOS); mtu is the interface MTU (None uses the transport default; Tailscale’s overlay MTU is 1280). TUN mode requires root / CAP_NET_ADMIN and the engine’s tun feature to be enabled. Chainable: Config::default().use_tun(Some("tailscale0".into()), None).

pub fn default_from_env() -> Config

Construct a default config, setting certain fields from environment variables.

The fields are only set if the corresponding environment variable is present, using the default value otherwise.

Loads:

• control_server_url from TS_CONTROL_URL
• requested_hostname from TS_HOSTNAME
• auth_key from TS_AUTH_KEY
• client_id from TS_CLIENT_ID
• client_secret from TS_CLIENT_SECRET
• id_token from TS_ID_TOKEN
• audience from TS_AUDIENCE

pub fn rotate_node_key(&mut self)

Rotate this config’s node key in place for an embedder-driven re-registration, mirroring Go’s regen flow: the current node key is recorded as the old key and a fresh node key is generated. Re-create the Device from this config to perform the rotation; the next registration sends the prior key as OldNodeKey for key continuity.

Reactive and embedder-driven by design (you decide when to rotate, e.g. after observing Device::self_key_expired flip, or on a policy of your own). This fork does not auto-rotate before expiry — neither does Go, which treats key expiry as a deliberate periodic re-authentication checkpoint. Rotation still requires a valid auth key, exactly like a fresh registration.

Trait Implementations

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.

impl From<&Config> for Config

fn from(value: &Config) -> Config

Converts to this type from the input type.