Crate ts_control 

ts_control

Client for the Tailscale control plane.

Modules

tls

Re-exported TLS types from the tokio-rustls/ring stack used by cert/serve, so embedders can name get_certificate/listen_tls return types without taking their own direct tokio-rustls dependency (and risking a second, mismatched crypto provider).

Structs

AsyncControlClient

A client to communicate with control.

Config

Configuration for the control server.

ControlDialer

Manages state for control dial plan and handles selection of successive dial candidates.

DEFAULT_CONTROL_SERVER

The default Url of the control plane server (aka “coordination server”).

DerpRegion

A single derp Region, holding the region info and all the server info.

DialCandidate

A candidate endpoint for a control plane connection.

DnsConfig

Owned DNS configuration distilled from the control MapResponse for the MagicDNS responder.

DnsResolver

An upstream DNS resolver to forward non-overlay queries to (Go tailcfg.DNSResolver).

Endpoint

An endpoint (address + port) on which a peer can be reached.

ExitProxyConfig

Transport-only description of an upstream proxy that exit-node egress is routed through, so a cloud exit node egresses via the proxy’s (e.g. residential) IP rather than its own origin IP.

ExtraRecord

A control-pushed static host record (Go tailcfg.DNSConfig.ExtraRecords). MagicDNS answers these alongside tailnet peer names. Only A/AAAA records are kept; other record types are dropped, since the responder only serves address records.

FunnelOptions

Options for a Funnel listener (mirrors tsnet.FunnelOption).

Node

A node in a tailnet.

PeerChange

An incremental update to a single already-known peer Node, carried in MapResponse::peers_changed_patch.

ServeConfig

Configuration for terminating TLS on one tailnet port for one MagicDNS name.

ServeState

A complete multi-port Serve configuration for one node (mirrors upstream ipn.ServeConfig’s per-port TCP map). Stored on the device and reconciled into one accept loop per port by the Serve runtime; set_serve_config REPLACES the whole config (Go semantics).

SshAccept

Details of an accepted SSH connection.

SshAction

The action taken when a rule matches. Mirrors tailcfg.SSHAction.

SshConnIdentity

The identity of an incoming SSH connection, resolved from the connecting peer.

SshPolicy

An owned Tailscale SSH policy. Mirrors tailcfg.SSHPolicy.

SshPrincipal

A principal an SshRule matches against. Mirrors tailcfg.SSHPrincipal. A principal matches if any is set, or any populated field matches the connection identity.

SshRule

A single SSH policy rule. Mirrors tailcfg.SSHRule.

StableNodeId

The stable ID of a node.

StateUpdate

An update to the netmap state produced from a mapresponse.

TailnetAddress

Addresses for a node within a tailnet.

TkaBootstrapRequest

Request body for GET /machine/tka/bootstrap (Go tailcfg.TKABootstrapRequest): ask control for the genesis AUM needed to initialize TKA.

TkaBootstrapResponse

Response to GET /machine/tka/bootstrap (Go tailcfg.TKABootstrapResponse): the genesis AUM (so the node can build its initial Authority) and the disablement secret.

TkaStatus

The control plane’s view of this tailnet’s Tailnet Lock state (Go tailcfg.TKAInfo).

TkaSyncOfferRequest

Request body for GET /machine/tka/sync/offer (Go tailcfg.TKASyncOfferRequest): the node’s current chain head + a sparse ancestor sample, so control can compute what to send back.

TkaSyncOfferResponse

Response to GET /machine/tka/sync/offer (Go tailcfg.TKASyncOfferResponse): control’s own offer (its head + ancestors) plus the AUMs it computed the node is missing.

TkaSyncSendRequest

Request body for GET /machine/tka/sync/send (Go tailcfg.TKASyncSendRequest): the node’s (post-Inform) head plus the AUMs control is missing.

TkaSyncSendResponse

Response to GET /machine/tka/sync/send (Go tailcfg.TKASyncSendResponse): control’s resulting head after applying the node’s AUMs.

TunConfig

Transport-only parameters for TransportMode::Tun.

UserProfile

Display-friendly identity for the user that owns a Node, resolved from the netmap’s UserProfiles table (Go tailcfg.UserProfile). Owned counterpart of the borrow-bound ts_control_serde::UserProfile. Keyed by UserProfile::id (== Node::user_id).

Enums

CertError

Errors from certificate acquisition / TLS material assembly.

DialMode

The mode with which to connect to the control plane.

DialPlan

A plan to connect to the control plane, supplied as part of a netmap update.

EndpointType

Distinguishes different sources of MapRequest::endpoints values.

Error

An error which occurred while connecting to the control server or control plane.

ExitNodeSelector

How this node selects which peer to use as its exit node (--exit-node in the Go client).

ExitProxyScheme

Upstream-proxy wire protocol for ExitProxyConfig. Mirrors ts_forwarder::ProxyScheme; kept as a separate type here because ts_control must not depend on ts_forwarder (the runtime converts between them at the boundary).

FunnelError

Why a Funnel listen request was denied or could not be served.

IdTokenError

Errors from an ID-token request.

InternalErrorKind

What kind of internal error has occurred.

LogoutError

Errors from a logout request.

LogoutInternalErrorKind

The internal failure kinds a logout request can surface.

Operation

The phase of connecting the control plane to a Tailnet in which an error occurs.

PeerUpdate

An update to the peers recorded in the netmap.

ResolverTransport

The transport of a Resolver. Only plaintext UDP is forwarded today; encrypted transports are dropped at parse time (see Resolver::from_serde).

ServeTarget

What to do with a stream once TLS is terminated (or, for ServeTarget::TcpForward, a raw TCP stream with no TLS).

ServiceError

Why a VIP-service listen request was refused. Fail-closed by construction: there is no variant that yields a usable listen address without a genuine control-assigned VIP on a tagged host.

ServiceMode

How a VIP service terminates incoming connections (a scoped mirror of tsnet’s ServiceMode).

SetDnsError

Errors from a set-dns request.

SetDnsInternalErrorKind

The internal failure kinds a set-dns request can surface.

SshDecision

The outcome of evaluating an SshPolicy against a connection.

SshDenyReason

Why a connection was denied. Mirrors Go’s rejected / rejectedUser results plus an explicit reject action.

TkaSyncError

Errors from a TKA-sync RPC.

TkaSyncInternalErrorKind

The internal failure kinds a TKA-sync request can surface (kept coarse for the public surface).

TransportMode

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

Constants

DEFAULT_PERSISTENT_KEEPALIVE

Default WireGuard persistent-keepalive interval: 25s.

MISSING_CERT_RPC

Names exactly what this fork is missing to issue a real cert, surfaced verbatim in CertError::Unimplemented so the gap is self-documenting at runtime. There is no control cert/<domain> RPC in real Tailscale — the node is the ACME client and only needs control to publish the DNS-01 TXT via POST /machine/set-dns (which a self-hosted control plane typically 501s). See the module docs.

MISSING_FUNNEL_RELAY

Names what is needed to actually receive public Funnel ingress on a node whose client-side listener is up. This is Tailscale infrastructure, not buildable in this fork: the public DNS <node>.<tailnet>.ts.net:443 → relay mapping plus the ingress relay itself (a Tailscale-operated tailnet peer that POSTs the public client’s bytes to this node’s peerAPI /v0/ingress). Against real Tailscale SaaS (with a Funnel-enabled ACL) control stands these up automatically and listen_funnel’s listener serves real public traffic; against a self-hosted control plane no relay exists, so the listener is correct but never fed. Surfaced verbatim in FunnelError::Unsupported for callers that want to flag the relay gap.

Statics

DEFAULT_CONTROL_SERVER

Traits

TcpDialer

Creates a TCP connection on the basis of a specific DialCandidate.

Functions

accept_tls

Terminate TLS on a single already-accepted overlay stream.

certified_key_from_pem

Assemble a CertifiedKey from a PEM chain + PEM private key, using the ring crypto provider’s signing-key loader (matching the rest of the TLS stack — ts_tls_util is tokio-rustls/ring). This is the assembly helper a future real issuance path (or a test) feeds the control-returned chain into.

complete_connection

Complete a connection to control over the supplied I/O stream.

convert_derp_map

Convert a derp map from the ts_control_serde representation to the ts_derp representation.

fetch_id_token

Request an OIDC ID token for this node from control, scoped to audience (the aud claim of the returned JWT). Opens a fresh Noise channel and POSTs to /machine/id-token. Returns the signed JWT string on success.

funnel_access

Check whether node may funnel on port, mirroring Go’s ipn.NodeCanFunnel + ipn.CheckFunnelPort gate. Pure and fail-closed: a missing attribute or out-of-range port denies. This is the access decision; it does not build a listener.

get_certificate

Obtain a CertifiedKey for a node’s MagicDNS name.

is_tailnet_name

Returns true if name looks like a tailnet MagicDNS name we may serve a cert for. We only ever mint/serve certs for tailnet names — never arbitrary public hostnames — to avoid being turned into a cert oracle for off-tailnet origins.

is_tailscale_ip

Whether addr falls in a range Tailscale assigns to nodes: the CGNAT range for IPv4 (100.64.0.0/10, excluding the ChromeOS VM carve-out 100.115.92.0/23) and the Tailscale ULA for IPv6 (fd7a:115c:a1e0::/48).

listen_funnel

Build a TlsAcceptor terminating public Funnel ingress for cfg.name on cfg.port (like tsnet’s ListenFunnel).

listen_tls

Obtain a certificate for cfg.name and build a TlsAcceptor for it.

logout

Log this node out of the tailnet: deregister it by expiring its current node key.

resolve_service_listen

Resolve the overlay core::net::SocketAddr a node should bind to host VIP service name in mode, enforcing the three fail-closed preconditions (valid name, tagged host, control-assigned VIP). See the module docs.

services_hash

Compute the HostInfo.ServicesHash for a node’s advertised VIP services, mirroring Go’s vipServiceHash.

set_dns

Publish a DNS record for this node via control (POST /machine/set-dns).

tka_bootstrap

Fetch the TKA bootstrap (genesis AUM) from control: the entry point that gives a node with no chain yet the initial AUM to build its Authority from, before the offer/send catch-up (Go tkaFetchBootstrap). head is the node’s current known head (empty when it has none). Fresh Noise channel, bounded by [TKA_SYNC_TIMEOUT].

tka_sync_offer

Send a TKA sync/offer to control: our chain offer, returning control’s response (its own offer + the AUMs we are missing). Opens a fresh Noise channel, bounded by [TKA_SYNC_TIMEOUT].

tka_sync_send

Send a TKA sync/send to control: our (post-Inform) send request with the AUMs control is missing, returning control’s resulting head. Fresh Noise channel, bounded by [TKA_SYNC_TIMEOUT].

tls_acceptor

Build a TlsAcceptor for an already-obtained CertifiedKey.

validate_service_name

Validate a Tailscale VIP service name (tailcfg.ServiceName.Validate): it must carry the svc: prefix (ts_control_serde::SERVICE_NAME_PREFIX) followed by a valid DNS label (1–63 chars, ASCII alphanumeric or -, not starting/ending with -). Returns the bare label on success. Fail-closed: anything malformed is rejected so a listener can never bind for a bogus service name.

Type Aliases

DerpMap

The full derp state, a map of ts_derp::RegionIds to Regions.

FilterUpdate

The components of a packet filter update.

NodeCapMap

An owned node-capability map (Node.CapMap in Go: map[NodeCapability][]RawMessage).

NodeId

The unique id of a node.

UserId

A unique integer ID for a User.