Files
tailscale/control/controlknobs/controlknobs.go
Simon Law d843b72e35 control/controlknobs: clean up documentation and updater function (#22349)
In controlknobs.Knobs, each atomic field represents a knob controlled
by the existence of a capability in the node’s CapMap. This patch adds
a doc comment for each field referencing which nodecap.Cap sets it.

This patch also cleans up UpdateFromNodeAttributes to unify the
CapMap lookup with the setting of the appropriate Knobs field.
Previously, it was easier to accidentally mismatch them because they
were split in two places.

Updates #cleanup

Change-Id: I329b0c5732f1c13f2e0d8609c35f42ad645b6bd7

Signed-off-by: Simon Law <[email protected]>
2026-11-19 10:34:29 -08:00

251 lines
10 KiB
Go

// Copyright (c) Tailscale Inc & contributors
// SPDX-License-Identifier: BSD-3-Clause
// Package controlknobs contains client options configurable from control which can be turned on
// or off. The ability to turn options on and off is for incrementally adding features in.
package controlknobs
import (
"fmt"
"reflect"
"sync/atomic"
"tailscale.com/syncs"
"tailscale.com/tailcfg"
"tailscale.com/tailcfg/nodecap"
"tailscale.com/types/opt"
)
// Knobs is the set of knobs that the control plane's coordination server can
// adjust at runtime.
type Knobs struct {
// DisableUPnP indicates whether to attempt UPnP mapping.
// Set by [nodecap.DisableUPnP].
DisableUPnP atomic.Bool
// RandomizeClientPort is whether control says we should randomize
// the client port.
// Set by [nodecap.RandomizeClientPort].
RandomizeClientPort atomic.Bool
// OneCGNAT is whether the node should make one big CGNAT route
// in the OS rather than one /32 per peer.
// Set by [nodecap.OneCGNATEnable] and [nodecap.OneCGNATDisable].
OneCGNAT syncs.AtomicValue[opt.Bool]
// ForceBackgroundSTUN forces netcheck STUN queries to keep
// running in magicsock, even when idle.
// Set by [nodecap.DebugForceBackgroundSTUN].
ForceBackgroundSTUN atomic.Bool
// DisableDeltaUpdates is whether the node should not process
// incremental (delta) netmap updates and should treat all netmap
// changes as "full" ones as tailscaled did in 1.48.x and earlier.
// Set by [nodecap.DisableDeltaUpdates].
DisableDeltaUpdates atomic.Bool
// PeerMTUEnable is whether the node should do peer path MTU discovery.
// Set by [nodecap.PeerMTUEnable].
PeerMTUEnable atomic.Bool
// DisableDNSForwarderTCPRetries is whether the DNS forwarder should
// skip retrying truncated queries over TCP.
// Set by [nodecap.DNSForwarderDisableTCPRetries].
DisableDNSForwarderTCPRetries atomic.Bool
// SilentDisco is whether the node should suppress disco heartbeats to its
// peers.
// Set by [nodecap.SilentDisco].
SilentDisco atomic.Bool
// LinuxForceIPTables is whether the node should use iptables for Linux
// netfiltering, unless overridden by the user.
// Set by [nodecap.LinuxMustUseIPTables].
LinuxForceIPTables atomic.Bool
// LinuxForceNfTables is whether the node should use nftables for Linux
// netfiltering, unless overridden by the user.
// Set by [nodecap.LinuxMustUseNfTables].
LinuxForceNfTables atomic.Bool
// ProbeUDPLifetime is whether the node should probe UDP path lifetime on
// the tail end of an active direct connection in magicsock.
// Set by [nodecap.ProbeUDPLifetime].
ProbeUDPLifetime atomic.Bool
// AppCStoreRoutes is whether the node should store RouteInfo to StateStore
// if it's an app connector.
// Set by [nodecap.StoreAppCRoutes].
AppCStoreRoutes atomic.Bool
// UserDialUseRoutes is whether tsdial.Dialer.UserDial should use routes to determine
// how to dial the destination address. When true, it also makes the DNS forwarder
// use UserDial instead of SystemDial when dialing resolvers.
// Set by [nodecap.UserDialUseRoutes].
UserDialUseRoutes atomic.Bool
// DisableSplitDNSWhenNoCustomResolvers indicates that the node's DNS manager
// should not adopt a split DNS configuration even though the Config of the
// resolver only contains routes that do not specify custom resolver(s), hence
// all DNS queries can be safely sent to the upstream DNS resolver and the
// node's DNS forwarder doesn't need to handle all DNS traffic.
// This is for now (2024-06-06) an iOS-specific battery life optimization,
// and this knob allows us to disable the optimization remotely if needed.
// Set by [nodecap.DisableSplitDNSWhenNoCustomResolvers].
DisableSplitDNSWhenNoCustomResolvers atomic.Bool
// DisableLocalDNSOverrideViaNRPT indicates that the node's DNS manager should not
// create a default (catch-all) Windows NRPT rule when "Override local DNS" is enabled.
// Without this rule, Windows 8.1 and newer devices issue parallel DNS requests to DNS servers
// associated with all network adapters, even when "Override local DNS" is enabled and/or
// a Mullvad exit node is being used, resulting in DNS leaks.
// We began creating this rule on 2024-06-14, and this knob
// allows us to disable the new behavior remotely if needed.
// Set by [nodecap.DisableLocalDNSOverrideViaNRPT].
DisableLocalDNSOverrideViaNRPT atomic.Bool
// DisableCaptivePortalDetection is whether the node should not perform captive portal detection
// automatically when the network state changes.
// Set by [nodecap.DisableCaptivePortalDetection].
DisableCaptivePortalDetection atomic.Bool
// DisableSkipStatusQueue is whether the node should disable skipping
// of queued netmap.NetworkMap between the controlclient and LocalBackend.
// See tailscale/tailscale#14768.
// Set by [nodecap.DisableSkipStatusQueue].
DisableSkipStatusQueue atomic.Bool
// DisableHostsFileUpdates indicates that the node's DNS manager should not create
// hosts file entries when it normally would, such as when we're not the primary
// resolver on Windows or when the host is domain-joined and its primary domain
// takes precedence over MagicDNS. As of 2026-02-13, it is only used on Windows.
// Set by [nodecap.DisableHostsFileUpdates].
DisableHostsFileUpdates atomic.Bool
// ForceRegisterMagicDNSIPv4Only is whether the node should only register
// its IPv4 MagicDNS service IP and not its IPv6 one. The IPv6 one,
// [tailscale.com/net/tsaddr.TailscaleServiceIPv6String], still works in either case.
// This knob controls only whether we tell systemd/etc about the IPv6 one.
// See https://github.com/tailscale/tailscale/issues/15404.
// Set by [nodecap.ForceRegisterMagicDNSIPv4Only]
// TODO(bradfitz): remove this a few releases after 2026-02-16.
ForceRegisterMagicDNSIPv4Only atomic.Bool
// EmitRuntimeMetrics is whether the node should poll and emit [runtime/metrics]
// as [tailscale.com/util/clientmetric]'s.
// Set by [nodecap.EmitRuntimeMetrics]
EmitRuntimeMetrics atomic.Bool
// DisableUDPGRO disables UDP GRO on the magicsock UDP socket.
// Set by [nodecap.DisableUDPGRO].
DisableUDPGRO atomic.Bool
// DisableUDPGSO disables UDP GSO on the magicsock UDP socket.
// Set by [nodecap.DisableUDPGSO].
DisableUDPGSO atomic.Bool
// DisableTUNUDPGRO disables UDP GRO on the Tailscale TUN device.
// Set by [nodecap.DisableTUNUDPGRO].
DisableTUNUDPGRO atomic.Bool
// DisableTUNTCPGRO disables TCP GRO on the Tailscale TUN device.
// Set by [nodecap.DisableTUNTCPGRO].
DisableTUNTCPGRO atomic.Bool
// NeverGSOEqualTail enables a UDP GSO sentinel-tail workaround in the
// underlay UDP packet TX path on Linux. Applies to magicsock and peer relay
// UDP sockets.
// Set by [nodecap.NeverGSOEqualTail].
NeverGSOEqualTail atomic.Bool
// CacheNetworkMaps is whether the node should persistently cache network
// maps and use them to establish peer connectivity on start, if doing so
// is supported by the client and storage is available.
// Set by [nodecap.CacheNetworkMaps].
CacheNetworkMaps atomic.Bool
// ScopeQuad100OnMacOS lets sandboxed macOS scope quad-100 for simple DNS
// configs, so public queries can use the OS resolver (including DoH).
// Custom split resolvers or unrouted forward/PTR records still require
// quad-100 as primary. Off by default; has no effect on other platforms.
// See tailscale/corp#45534 and tailscale/corp#48693.
// Set by [nodecap.ScopeQuad100OnMacOS].
ScopeQuad100OnMacOS atomic.Bool
}
// UpdateFromNodeAttributes updates k (if non-nil) based on the provided self
// node attributes (Node.Capabilities).
func (k *Knobs) UpdateFromNodeAttributes(capMap tailcfg.NodeCapMap) {
if k == nil {
return
}
setBool := func(b *atomic.Bool, cap nodecap.Cap) {
b.Store(capMap.Contains(cap))
}
setOptBool := func(b *syncs.AtomicValue[opt.Bool], enable, disable nodecap.Cap) {
var v opt.Bool
if capMap.Contains(enable) {
v.Set(true)
} else if capMap.Contains(disable) {
v.Set(false)
}
b.Store(v)
}
setBool(&k.DisableUPnP, nodecap.DisableUPnP)
setBool(&k.RandomizeClientPort, nodecap.RandomizeClientPort)
setOptBool(&k.OneCGNAT, nodecap.OneCGNATEnable, nodecap.OneCGNATDisable)
setBool(&k.ForceBackgroundSTUN, nodecap.DebugForceBackgroundSTUN)
setBool(&k.DisableDeltaUpdates, nodecap.DisableDeltaUpdates)
setBool(&k.PeerMTUEnable, nodecap.PeerMTUEnable)
setBool(&k.DisableDNSForwarderTCPRetries, nodecap.DNSForwarderDisableTCPRetries)
setBool(&k.SilentDisco, nodecap.SilentDisco)
setBool(&k.LinuxForceIPTables, nodecap.LinuxMustUseIPTables)
setBool(&k.LinuxForceNfTables, nodecap.LinuxMustUseNfTables)
setBool(&k.ProbeUDPLifetime, nodecap.ProbeUDPLifetime)
setBool(&k.AppCStoreRoutes, nodecap.StoreAppCRoutes)
setBool(&k.UserDialUseRoutes, nodecap.UserDialUseRoutes)
setBool(&k.DisableSplitDNSWhenNoCustomResolvers, nodecap.DisableSplitDNSWhenNoCustomResolvers)
setBool(&k.DisableLocalDNSOverrideViaNRPT, nodecap.DisableLocalDNSOverrideViaNRPT)
setBool(&k.DisableCaptivePortalDetection, nodecap.DisableCaptivePortalDetection)
setBool(&k.DisableSkipStatusQueue, nodecap.DisableSkipStatusQueue)
setBool(&k.DisableHostsFileUpdates, nodecap.DisableHostsFileUpdates)
setBool(&k.ForceRegisterMagicDNSIPv4Only, nodecap.ForceRegisterMagicDNSIPv4Only)
setBool(&k.EmitRuntimeMetrics, nodecap.EmitRuntimeMetrics)
setBool(&k.DisableUDPGRO, nodecap.DisableUDPGRO)
setBool(&k.DisableUDPGSO, nodecap.DisableUDPGSO)
setBool(&k.DisableTUNUDPGRO, nodecap.DisableTUNUDPGRO)
setBool(&k.DisableTUNTCPGRO, nodecap.DisableTUNTCPGRO)
setBool(&k.NeverGSOEqualTail, nodecap.NeverGSOEqualTail)
setBool(&k.CacheNetworkMaps, nodecap.CacheNetworkMaps)
setBool(&k.ScopeQuad100OnMacOS, nodecap.ScopeQuad100OnMacOS)
}
// AsDebugJSON returns k as something that can be marshalled with json.Marshal
// for debug.
func (k *Knobs) AsDebugJSON() map[string]any {
if k == nil {
return nil
}
ret := map[string]any{}
rv := reflect.ValueOf(k).Elem() // of *k
for sf, fv := range rv.Fields() {
switch v := fv.Addr().Interface().(type) {
case *atomic.Bool:
ret[sf.Name] = v.Load()
case *syncs.AtomicValue[opt.Bool]:
ret[sf.Name] = v.Load()
default:
panic(fmt.Sprintf("unknown field type %T for %v", v, sf.Name))
}
}
return ret
}
// ShouldForceRegisterMagicDNSIPv4Only reports the value of
// ForceRegisterMagicDNSIPv4Only, or false if k is nil.
func (k *Knobs) ShouldForceRegisterMagicDNSIPv4Only() bool {
return k != nil && k.ForceRegisterMagicDNSIPv4Only.Load()
}