controlclient

package
v1.92.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2025 License: BSD-3-Clause Imports: 69 Imported by: 29

Documentation

Overview

Package controlclient implements the client for the Tailscale control plane.

It handles authentication, port picking, and collects the local network configuration.

Index

Constants

View Source 
const (
	LoginDefault     = LoginFlags(0)
	LoginInteractive = LoginFlags(1 << iota) // force user login and key refresh
	LoginEphemeral                           // set RegisterRequest.Ephemeral

	// LocalBackendStartKeyOSNeutral instructs NewLocalBackend to start the
	// LocalBackend without any OS-dependent StateStore StartKey behavior.
	//
	// See https://github.com/tailscale/tailscale/issues/6973.
	LocalBackendStartKeyOSNeutral
)

Variables

View Source 
var DevKnob = initDevKnob()

DevKnob contains temporary internal-only debug knobs. They're unexported to not draw attention to them.

View Source 
var ErrClientClosed = errors.New("client closed")
View Source 
var HookAnswerC2NPing feature.Hook[func(logger.Logf, http.Handler, *http.Client, *tailcfg.PingRequest)]

HookAnswerC2NPing is where feature/c2n conditionally registers support for handling C2N (control-to-node) HTTP requests.

Functions

func HashRegisterRequest added in v1.8.0 

func HashRegisterRequest(
	version tailcfg.SignatureType, ts time.Time, serverURL string, deviceCert []byte,
	serverPubKey, machinePubKey key.MachinePublic) ([]byte, error)

HashRegisterRequest generates the hash required sign or verify a tailcfg.RegisterRequest.

func NetmapFromMapResponseForDebug added in v1.90.0 

func NetmapFromMapResponseForDebug(ctx context.Context, pr persist.PersistView, resp *tailcfg.MapResponse) (*netmap.NetworkMap, error)

NetmapFromMapResponseForDebug returns a NetworkMap from the given MapResponse. It is intended for debugging only.

Types

type Auto added in v1.8.0 

type Auto struct {
	// contains filtered or unexported fields
}

Auto connects to a tailcontrol server for a node. It's a concrete implementation of the Client interface.

func New 

func New(opts Options) (*Auto, error)

New creates and starts a new Auto.

func (*Auto) AuthCantContinue added in v1.8.0 

func (c *Auto) AuthCantContinue() bool

func (*Auto) ClientID added in v1.90.0 

func (c *Auto) ClientID() int64

ClientID returns the ClientID of the direct controlClient

func (*Auto) DirectForTest added in v1.50.0 

func (c *Auto) DirectForTest() *Direct

DirectForTest returns the underlying direct client object. It's used in tests only.

func (*Auto) DoNoiseRequest added in v1.24.0 

func (c *Auto) DoNoiseRequest(req *http.Request) (*http.Response, error)

func (*Auto) ExpiryForTests added in v1.50.0 

func (c *Auto) ExpiryForTests() time.Time

ExpiryForTests returns the credential expiration time, or the zero value if the expiration time isn't known. It's used in tests only.

func (*Auto) Login added in v1.8.0 

func (c *Auto) Login(flags LoginFlags)

func (*Auto) Logout added in v1.8.0 

func (c *Auto) Logout(ctx context.Context) error

func (*Auto) SendAuditLog added in v1.82.0 

func (c *Auto) SendAuditLog(ctx context.Context, auditLog tailcfg.AuditLogRequest) (err error)

SendAuditLog implements [auditlog.Transport] by sending an audit log synchronously to the control plane.

See docs on tailcfg.AuditLogRequest and [auditlog.Logger] for background.

func (*Auto) SetDNS added in v1.10.0 

func (c *Auto) SetDNS(ctx context.Context, req *tailcfg.SetDNSRequest) error

SetDNS sends the SetDNSRequest request to the control plane server, requesting a DNS record be created or updated.

func (*Auto) SetDeviceAttrs added in v1.80.0 

func (c *Auto) SetDeviceAttrs(ctx context.Context, attrs tailcfg.AttrUpdate) error

SetDeviceAttrs does a synchronous call to the control plane to update the node's attributes.

See docs on tailcfg.SetDeviceAttributesRequest for background.

func (*Auto) SetDiscoPublicKey added in v1.92.0 

func (c *Auto) SetDiscoPublicKey(key key.DiscoPublic)

SetDiscoPublicKey sets the client's Disco public to key and sends the change to the control server.

func (*Auto) SetExpirySooner added in v1.24.0 

func (c *Auto) SetExpirySooner(ctx context.Context, expiry time.Time) error

func (*Auto) SetHostinfo added in v1.8.0 

func (c *Auto) SetHostinfo(hi *tailcfg.Hostinfo)

func (*Auto) SetNetInfo added in v1.8.0 

func (c *Auto) SetNetInfo(ni *tailcfg.NetInfo)

func (*Auto) SetPaused added in v1.8.0 

func (c *Auto) SetPaused(paused bool)

SetPaused controls whether HTTP activity should be paused.

The client can be paused and unpaused repeatedly, unlike Start and Shutdown, which can only be used once.

func (*Auto) SetTKAHead added in v1.34.0 

func (c *Auto) SetTKAHead(headHash string)

SetTKAHead updates the TKA head hash that map-request infrastructure sends.

func (*Auto) Shutdown added in v1.8.0 

func (c *Auto) Shutdown()

func (*Auto) StartForTest added in v1.92.0 

func (c *Auto) StartForTest()

StartForTest starts the client's goroutines.

It should only be called for clients created with [Options.SkipStartForTests].

func (*Auto) TestOnlyNodePublicKey added in v1.8.0 

func (c *Auto) TestOnlyNodePublicKey() key.NodePublic

NodePublicKey returns the node public key currently in use. This is used exclusively in tests.

func (*Auto) TestOnlySetAuthKey added in v1.8.0 

func (c *Auto) TestOnlySetAuthKey(authkey string)

func (*Auto) TestOnlyTimeNow added in v1.8.0 

func (c *Auto) TestOnlyTimeNow() time.Time

func (*Auto) UpdateEndpoints added in v1.8.0 

func (c *Auto) UpdateEndpoints(endpoints []tailcfg.Endpoint)

UpdateEndpoints sets the client's discovered endpoints and sends them to the control server if they've changed.

It does not retain the provided slice.

type AutoUpdate added in v1.90.0 

type AutoUpdate struct {
	ClientID int64 // The ID field is used for consumers to differentiate instances of Direct.
	Value    bool  // The Value represents DefaultAutoUpdate from [tailcfg.MapResponse].
}

AutoUpdate is an eventbus value, reporting the value of tailcfg.MapResponse.DefaultAutoUpdate.

type Client 

type Client interface {
	// Shutdown closes this session, which should not be used any further
	// afterwards.
	Shutdown()
	// Login begins an interactive or non-interactive login process.
	// Client will eventually call the Status callback with either a
	// LoginFinished flag (on success) or an auth URL (if further
	// interaction is needed). It merely sets the process in motion,
	// and doesn't wait for it to complete.
	Login(LoginFlags)
	// Logout starts a synchronous logout process. It doesn't return
	// until the logout operation has been completed.
	Logout(context.Context) error
	// SetPaused pauses or unpauses the controlclient activity as much
	// as possible, without losing its internal state, to minimize
	// unnecessary network activity.
	// TODO: It might be better to simply shutdown the controlclient and
	// make a new one when it's time to unpause.
	SetPaused(bool)
	// AuthCantContinue returns whether authentication is blocked. If it
	// is, you either need to visit the auth URL (previously sent in a
	// Status callback) or call the Login function appropriately.
	// TODO: this probably belongs in the Status itself instead.
	AuthCantContinue() bool
	// SetHostinfo changes the Hostinfo structure that will be sent in
	// subsequent node registration requests.
	// TODO: a server-side change would let us simply upload this
	// in a separate http request. It has nothing to do with the rest of
	// the state machine.
	SetHostinfo(*tailcfg.Hostinfo)
	// SetNetinfo changes the NetIinfo structure that will be sent in
	// subsequent node registration requests.
	// TODO: a server-side change would let us simply upload this
	// in a separate http request. It has nothing to do with the rest of
	// the state machine.
	SetNetInfo(*tailcfg.NetInfo)
	// SetTKAHead changes the TKA head hash value that will be sent in
	// subsequent netmap requests.
	SetTKAHead(headHash string)
	// UpdateEndpoints changes the Endpoint structure that will be sent
	// in subsequent node registration requests.
	// TODO: a server-side change would let us simply upload this
	// in a separate http request. It has nothing to do with the rest of
	// the state machine.
	// Note: the auto client uploads the new endpoints to control immediately.
	UpdateEndpoints(endpoints []tailcfg.Endpoint)
	// SetDiscoPublicKey updates the disco public key that will be sent in
	// future map requests. This should be called after rotating the discovery key.
	// Note: the auto client uploads the new key to control immediately.
	SetDiscoPublicKey(key.DiscoPublic)
	// ClientID returns the ClientID of a client. This ID is meant to
	// distinguish one client from another.
	ClientID() int64
}

Client represents a client connection to the control server. Currently this is done through a pair of polling https requests in the Auto client, but that might change eventually.

The Client must be comparable as it is used by the Observer to detect stale clients.

type ControlDialPlanner added in v1.32.0 

type ControlDialPlanner interface {
	// Load returns the current plan for how to connect to control.
	//
	// The returned plan can be nil. If so, connections should be made by
	// resolving the control URL using DNS.
	Load() *tailcfg.ControlDialPlan

	// Store updates the dial plan with new directions from the control
	// server.
	//
	// The dial plan can span multiple connections to the control server.
	// That is, a dial plan received when connected over Wi-Fi is still
	// valid for a subsequent connection over LTE after a network switch.
	Store(*tailcfg.ControlDialPlan)
}

ControlDialPlanner is the interface optionally supplied when creating a control client to control exactly how TCP connections to the control plane are dialed.

It is usually implemented by an atomic.Pointer.

type ControlTime added in v1.90.0 

type ControlTime struct {
	ClientID int64     // The ID field is used for consumers to differentiate instances of Direct.
	Value    time.Time // The Value represents ControlTime from [tailcfg.MapResponse].
}

ControlTime is an eventbus value, reporting the value of tailcfg.MapResponse.ControlTime.

type Direct 

type Direct struct {
	// contains filtered or unexported fields
}

Direct is the client that connects to a tailcontrol server for a node.

func NewDirect 

func NewDirect(opts Options) (*Direct, error)

NewDirect returns a new Direct client.

func (*Direct) ClientID added in v1.90.0 

func (c *Direct) ClientID() int64

ClientID returns the controlClientID of the controlClient.

func (*Direct) Close added in v1.24.0 

func (c *Direct) Close() error

Close closes the underlying Noise connection(s).

func (*Direct) DoNoiseRequest added in v1.24.0 

func (c *Direct) DoNoiseRequest(req *http.Request) (*http.Response, error)

func (*Direct) FetchNetMapForTest added in v1.48.0 

func (c *Direct) FetchNetMapForTest(ctx context.Context) (*netmap.NetworkMap, error)

FetchNetMapForTest fetches the netmap once.

func (*Direct) GetPersist 

func (c *Direct) GetPersist() persist.PersistView

func (*Direct) PollNetMap 

func (c *Direct) PollNetMap(ctx context.Context, nu NetmapUpdater) error

PollNetMap makes a /map request to download the network map, calling NetmapUpdater on each update from the control plane.

It always returns a non-nil error describing the reason for the failure or why the request ended.

func (*Direct) SendUpdate added in v1.48.0 

func (c *Direct) SendUpdate(ctx context.Context) error

SendUpdate makes a /map request to update the server of our latest state, but does not fetch anything. It returns an error if the server did not return a successful 200 OK response.

func (*Direct) SetConnectionHandleForTest added in v1.84.0 

func (c *Direct) SetConnectionHandleForTest(handle string)

SetConnectionHandleForTest stores a new MapRequest.ConnectionHandleForTest value for the next update.

func (*Direct) SetDNS added in v1.10.0 

func (c *Direct) SetDNS(ctx context.Context, req *tailcfg.SetDNSRequest) (err error)

SetDNS sends the SetDNSRequest request to the control plane server, requesting a DNS record be created or updated.

func (*Direct) SetDeviceAttrs added in v1.80.0 

func (c *Direct) SetDeviceAttrs(ctx context.Context, attrs tailcfg.AttrUpdate) error

SetDeviceAttrs does a synchronous call to the control plane to update the node's attributes.

See docs on tailcfg.SetDeviceAttributesRequest for background.

func (*Direct) SetDiscoPublicKey added in v1.92.0 

func (c *Direct) SetDiscoPublicKey(key key.DiscoPublic)

SetDiscoPublicKey updates the disco public key in local state. It does not implicitly trigger [SendUpdate]; callers should arrange for that.

func (*Direct) SetEndpoints 

func (c *Direct) SetEndpoints(endpoints []tailcfg.Endpoint) (changed bool)

SetEndpoints updates the list of locally advertised endpoints. It won't be replicated to the server until a *fresh* call to PollNetMap(). You don't need to restart PollNetMap if we return changed==false.

func (*Direct) SetExpirySooner added in v1.24.0 

func (c *Direct) SetExpirySooner(ctx context.Context, expiry time.Time) error

SetExpirySooner attempts to shorten the expiry to the specified time.

func (*Direct) SetHostinfo 

func (c *Direct) SetHostinfo(hi *tailcfg.Hostinfo) bool

SetHostinfo clones the provided Hostinfo and remembers it for the next update. It reports whether the Hostinfo has changed.

func (*Direct) SetNetInfo 

func (c *Direct) SetNetInfo(ni *tailcfg.NetInfo) bool

SetNetInfo clones the provided NetInfo and remembers it for the next update. It reports whether the NetInfo has changed.

func (*Direct) SetTKAHead added in v1.34.0 

func (c *Direct) SetTKAHead(tkaHead string) bool

SetTKAHead stores a new TKA head value for next update. It reports whether the TKA head changed.

func (*Direct) TryLogin 

func (c *Direct) TryLogin(ctx context.Context, flags LoginFlags) (url string, err error)

func (*Direct) TryLogout 

func (c *Direct) TryLogout(ctx context.Context) error

func (*Direct) WaitLoginURL 

func (c *Direct) WaitLoginURL(ctx context.Context, url string) (newURL string, err error)

WaitLoginURL sits in a long poll waiting for the user to authenticate at url.

On success, newURL and err will both be nil.

type LoginFlags 

type LoginFlags int

LoginFlags is a bitmask of options to change the behavior of Client.Login and LocalBackend.

type LoginGoal 

type LoginGoal struct {
	// contains filtered or unexported fields
}

type NetmapDeltaUpdater added in v1.50.0 

type NetmapDeltaUpdater interface {
	// UpdateNetmapDelta is called with discrete changes to the network map.
	//
	// The ok result is whether the implementation was able to apply the
	// mutations. It might return false if its internal state doesn't
	// support applying them or a NetmapUpdater it's wrapping doesn't
	// implement the NetmapDeltaUpdater optional method.
	UpdateNetmapDelta([]netmap.NodeMutation) (ok bool)
}

NetmapDeltaUpdater is an optional interface that can be implemented by NetmapUpdater implementations to receive delta updates from the controlclient rather than just full updates.

type NetmapUpdater added in v1.48.0 

type NetmapUpdater interface {
	UpdateFullNetmap(*netmap.NetworkMap)
}

NetmapUpdater is the interface needed by the controlclient to enact change in the world as a function of updates received from the network.

type Observer added in v1.50.0 

type Observer interface {
	// SetControlClientStatus is called when the client has a new status to
	// report. The Client is provided to allow the Observer to track which
	// Client is reporting the status, allowing it to ignore stale status
	// reports from previous Clients.
	SetControlClientStatus(Client, Status)
}

Observer is implemented by users of the control client (such as LocalBackend) to get notified of changes in the control client's status.

If an implementation of Observer also implements NetmapDeltaUpdater, they get delta updates as well as full netmap updates.

type Options 

type Options struct {
	Persist              persist.Persist                    // initial persistent data
	GetMachinePrivateKey func() (key.MachinePrivate, error) // returns the machine key to use
	ServerURL            string                             // URL of the tailcontrol server
	AuthKey              string                             // optional node auth key for auto registration
	Clock                tstime.Clock
	Hostinfo             *tailcfg.Hostinfo // non-nil passes ownership, nil means to use default using os.Hostname, etc
	DiscoPublicKey       key.DiscoPublic
	PolicyClient         policyclient.Client // or nil for none
	Logf                 logger.Logf
	HTTPTestClient       *http.Client // optional HTTP client to use (for tests only)
	NoiseTestClient      *http.Client // optional HTTP client to use for noise RPCs (tests only)
	DebugFlags           []string     // debug settings to send to control
	HealthTracker        *health.Tracker
	PopBrowserURL        func(url string)    // optional func to open browser
	Dialer               *tsdial.Dialer      // non-nil
	C2NHandler           http.Handler        // or nil
	ControlKnobs         *controlknobs.Knobs // or nil to ignore
	Bus                  *eventbus.Bus       // non-nil, for setting up publishers

	SkipStartForTests bool // if true, don't call [Auto.Start] to avoid any background goroutines (for tests only)

	// StartPaused indicates whether the client should start in a paused state
	// where it doesn't do network requests. This primarily exists for testing
	// but not necessarily "go test" tests, so it isn't restricted to only
	// being used in tests.
	StartPaused bool

	// Observer is called when there's a change in status to report
	// from the control client.
	// If nil, no status updates are reported.
	Observer Observer

	// SkipIPForwardingCheck declares that the host's IP
	// forwarding works and should not be double-checked by the
	// controlclient package.
	SkipIPForwardingCheck bool

	// Pinger optionally specifies the Pinger to use to satisfy
	// MapResponse.PingRequest queries from the control plane.
	// If nil, PingRequest queries are not answered.
	Pinger Pinger

	// DialPlan contains and stores a previous dial plan that we received
	// from the control server; if nil, we fall back to using DNS.
	//
	// If we receive a new DialPlan from the server, this value will be
	// updated.
	DialPlan ControlDialPlanner

	// Shutdown is an optional function that will be called before client shutdown is
	// attempted. It is used to allow the client to clean up any resources or complete any
	// tasks that are dependent on a live client.
	Shutdown func()
}

type Pinger added in v1.10.0 

type Pinger interface {
	// Ping is a request to do a ping with the peer handling the given IP.
	Ping(ctx context.Context, ip netip.Addr, pingType tailcfg.PingType, size int) (*ipnstate.PingResult, error)
}

Pinger is the LocalBackend.Ping method.

type Status 

type Status struct {

	// Err, if non-nil, is an error that occurred while logging in.
	//
	// If it's of type UserVisibleError then it's meant to be shown to users in
	// their Tailscale client. Otherwise it's just logged to tailscaled's logs.
	Err error

	// URL, if non-empty, is the interactive URL to visit to finish logging in.
	URL string

	// LoggedIn, if true, indicates that serveRegister has completed and no
	// other login change is in progress.
	LoggedIn bool

	// InMapPoll, if true, indicates that we've received at least one netmap
	// and are connected to receive updates.
	InMapPoll bool

	// NetMap is the latest server-pushed state of the tailnet network.
	NetMap *netmap.NetworkMap

	// Persist, when Valid, is the locally persisted configuration.
	//
	// TODO(bradfitz,maisem): clarify this.
	Persist persist.PersistView
	// contains filtered or unexported fields
}

func (*Status) Equal 

func (s *Status) Equal(s2 *Status) bool

Equal reports whether s and s2 are equal.

type UserVisibleError added in v1.18.0 

type UserVisibleError string

UserVisibleError is an error that should be shown to users.

func (UserVisibleError) Error added in v1.18.0 

func (e UserVisibleError) Error() string

func (UserVisibleError) UserVisibleError added in v1.18.0 

func (e UserVisibleError) UserVisibleError() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.