tailscale

package
v0.3.6 Latest Latest
Warning

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

Go to latest
Published: Oct 29, 2026 License: MIT Imports: 46 Imported by: 0

Documentation

Overview

Package tailscale runs and supervises tailscaled for each endpoint.

Index

Constants

View Source
const BundledVersion = "bundled"

BundledVersion is the only supported TS_VERSION: the Tailscale shipped in the plugin image.

View Source
const WireGuardPort = 41641

WireGuardPort is the UDP port every tslink tailscaled listens on, each in its container's namespace. The host lets only this port through between tslink's veths (netutil.SetupVethIsolation), so colocated nodes keep a direct path while containers cannot reach each other's other ports.

Variables

This section is empty.

Functions

func BundledBinaries

func BundledBinaries() (string, string, error)

BundledBinaries returns the paths of the tailscale and tailscaled binaries shipped in the plugin image, so every node runs the same version.

func CertNotAfter

func CertNotAfter(path string) (time.Time, error)

CertNotAfter returns the expiry of the first certificate in a PEM file.

func CheckAuthKeyMatch

func CheckAuthKeyMatch(stateDir, authKey string) bool

CheckAuthKeyMatch checks if the provided auth key matches the stored hash. Returns true if they match or if no hash is stored (new state). Returns false if they don't match (auth key changed).

func ClearEphemeral

func ClearEphemeral(stateDir string) error

ClearEphemeral removes the mark MarkEphemeral set, if any, when stateDir is used by a network whose nodes are not ephemeral.

func IsMarkedEphemeral

func IsMarkedEphemeral(stateDir string) bool

IsMarkedEphemeral reports whether stateDir was marked by MarkEphemeral.

func KeyEphemeral added in v0.2.4

func KeyEphemeral(key string) (bool, bool, error)

KeyEphemeral reports whether a node registered with key is ephemeral, as far as the key itself says, and whether it says so in an ephemeral attribute. OAuth client secrets register ephemeral nodes unless "?ephemeral=false" is appended; an auth key's ephemerality is set when it is created and cannot be read from it, so it counts as not ephemeral. tailscale up reads attributes only from OAuth client secrets and passes any other key on unchanged, so an attribute appended to an auth key means nothing. The error is that of an OAuth client secret with invalid attributes.

func LinkCertsDir

func LinkCertsDir(stateDir, shared, parent string) error

LinkCertsDir makes the state directory's certs directory a link to shared, creating shared and an ACME account key in it: parent's, if shared is a stack's directory in parent and parent has one. A link elsewhere, as to the shared directory before stacks had their own, is pointed at shared. A certs directory that is not a link, as kept by a non-ephemeral node from before, is left alone. An empty shared leaves tailscaled its own directory.

func LogoutState

func LogoutState(ctx context.Context, tailscaledBin, stateDir, socket string) error

LogoutState logs out the node whose state is in stateDir, which deletes an ephemeral node from the tailnet and frees its name, for a node whose container is gone. tailscaled runs on a copy of the state that logoutState sanitized, with userspace networking and its socket at socket, so the node does not come up: it contacts control only to log out. A state without a registered node is nothing to log out.

func MarkEphemeral

func MarkEphemeral(stateDir string) error

MarkEphemeral marks stateDir as holding an ephemeral node.

func SaveAuthKeyHash

func SaveAuthKeyHash(stateDir, authKey string) error

SaveAuthKeyHash stores the SHA256 hash of the auth key in the state directory.

func ServiceNames added in v0.3.5

func ServiceNames(services []Service) []string

ServiceNames returns the names of services.

func StateExists

func StateExists(stateDir string) bool

StateExists checks if valid Tailscale state exists in the given directory. Returns true if tailscaled.state file exists and is non-empty.

func WipeState

func WipeState(stateDir string) error

WipeState removes all state files from the directory to allow fresh registration. Removes tailscaled.state, tailscaled.sock, debug.log, and authkey hash, and returns the removals that failed.

Types

type DaemonConfig

type DaemonConfig struct {
	EndpointID    string
	StateDir      string
	SocketPath    string // tailscaled socket; defaults to <StateDir>/tailscaled.sock
	Hostname      string
	AuthKey       func() (string, error) // Read at each login, so a replaced credential takes effect
	CertsDir      string                 // Shared certificate directory; empty for tailscaled's own
	NetNSPath     string
	TailscaledBin string          // Path to tailscaled daemon binary
	Tags          []string        // ACL tags for --advertise-tags
	Services      []Service       // Services the node is a backend of, sorted by name
	Endpoints     []ServeEndpoint // What direct serve serves on the node's own name
	Direct        bool            // Enable direct machine serve (HTTPS on machine hostname)
	LoginServer   string          // Control server URL for --login-server; empty for Tailscale's
	ContainerDNS  []netip.Addr    // DNS servers the container was given, as with docker run --dns

	// HostEndpoints returns the endpoints on the host tailscaled advertises
	// besides its own (netutil.HostEndpoints); nil for none. Read when
	// tailscaled starts, as tailscaled reads them only then, and again by the
	// supervisor every hostEndpointsCheckInterval, to detect a change and
	// restart tailscaled with the new value.
	HostEndpoints func() ([]netip.AddrPort, error)

	// Warn records a warning in the endpoint's status under key, or clears it
	// if message is empty; nil ignores warnings
	Warn func(key, message string)

	// ParentCertsDir is the shared certificate directory when CertsDir is a
	// stack's directory in it: its ACME account key and the certificates it
	// held before stacks had directories of their own are adopted. Empty for
	// none.
	ParentCertsDir string
	// contains filtered or unexported fields
}

DaemonConfig holds configuration for a tailscaled instance.

type DaemonSupervisor

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

DaemonSupervisor manages a Daemon with automatic restart on failure.

func NewDaemonSupervisor

func NewDaemonSupervisor(cfg DaemonConfig) *DaemonSupervisor

NewDaemonSupervisor creates a new supervisor for managing a tailscaled daemon.

func (*DaemonSupervisor) Drain

func (s *DaemonSupervisor) Drain() error

Drain stops new connections to the node's Service backends. They stay drained, even if tailscaled is down and the drain fails: a daemon the supervisor starts later does not advertise them.

func (*DaemonSupervisor) DrainAndWait

func (s *DaemonSupervisor) DrainAndWait()

DrainAndWait drains the node's Service backends, unless that was done, as when the container got its stop signal, and waits for control to learn of it: until control fetched the Service list after the last removal of Services tslink made, at least drainAckFloor and at most drainAckTimeout after it. A node that tslink removed nothing from has nothing for control to fetch, and is not waited for. Should tailscaled restart meanwhile, or be restarting, the wait goes on with the daemon the supervisor starts next, which starts drained, until the same deadline.

func (*DaemonSupervisor) Drained

func (s *DaemonSupervisor) Drained() bool

Drained reports whether the node's Service backend has been drained.

func (*DaemonSupervisor) Leaving added in v0.3.6

func (s *DaemonSupervisor) Leaving()

Leaving notes that the endpoint leaves while the supervisor's first start runs, before StartContext's ctx is cancelled: see StartContext. The Service backends are drained from now on.

func (*DaemonSupervisor) Logout

func (s *DaemonSupervisor) Logout() error

Logout logs the running daemon's node out.

func (*DaemonSupervisor) NeedsDrain added in v0.3.5

func (s *DaemonSupervisor) NeedsDrain() bool

NeedsDrain reports whether the node may advertise a Service, or did so recently: its container names one, or Services it does not name were removed at start or could not be. Such a node is drained before it goes.

func (*DaemonSupervisor) Readiness

func (s *DaemonSupervisor) Readiness(ctx context.Context) ReadinessReport

Readiness reports how far the node is from serving what its container asks for. A daemon not started, or restarting, is starting.

func (*DaemonSupervisor) Start

func (s *DaemonSupervisor) Start() error

Start begins the supervision loop and waits for initial daemon startup. Returns error if the initial startup fails.

func (*DaemonSupervisor) StartContext added in v0.2.1

func (s *DaemonSupervisor) StartContext(ctx context.Context) error

StartContext is Start, but cancelling ctx before the initial startup succeeded, as the endpoint leaving does, stops the supervisor and aborts a daemon start in progress, its login included. Once started, the supervisor no longer depends on ctx. The caller still calls Stop after an error.

Once Leaving was called, a start whose tailscaled already runs is not aborted: tailscaled may advertise Services from the node's state, and an aborted start would leave the node with them. The start goes on drained, and StartContext drains and waits for control before it returns.

func (*DaemonSupervisor) Status

func (s *DaemonSupervisor) Status() (SupervisorStatus, int)

Status returns the current supervisor status and restart count.

func (*DaemonSupervisor) Stop

func (s *DaemonSupervisor) Stop() error

Stop gracefully stops the supervisor and daemon.

func (*DaemonSupervisor) WaitForIP

func (s *DaemonSupervisor) WaitForIP(ctx context.Context) (*Status, error)

WaitForIP waits for the daemon to get a Tailscale IP, or ctx to be done. Delegates to the underlying daemon.

type Readiness

type Readiness string

Readiness is how far a node is from serving what its container asks for.

const (
	ReadyStarting           Readiness = "starting"            // tailscaled is not up yet
	ReadyFailed             Readiness = "failed"              // starting failed for good
	ReadyLoggedOut          Readiness = "logged-out"          // the node needs a login
	ReadyServingPending     Readiness = "serving-pending"     // the tslink.serve.* config is not applied
	ReadyCertificatePending Readiness = "certificate-pending" // the Service waits for its certificate
	ReadyPortsUncovered     Readiness = "ports-uncovered"     // the Service defines ports not served
	ReadyAwaitingApproval   Readiness = "awaiting-approval"   // control has not approved the backend
	ReadyAwaitingControl    Readiness = "awaiting-control"    // control has not fetched the Services
	ReadyDrained            Readiness = "drained"             // the backend is drained, or the container leaving
	Ready                   Readiness = "ready"
)

The readiness states, from a node not started to one serving all it should.

type ReadinessReport added in v0.3.5

type ReadinessReport struct {
	State    Readiness
	Services map[string]Readiness // By Service name; nil without Services
}

ReadinessReport is how far a node is from serving what its container asks for, and how far each of its Services is.

type ServeEndpoint

type ServeEndpoint struct {
	Proto  string // http, https, tcp, tls-terminated-tcp, tun
	Port   string // External port Tailscale exposes
	Target string // Container port or address to forward to
	Path   string // L7 only - path prefix (e.g., "/api")

	ProxyProtocol string // L4 only - PROXY protocol version sent to the target ("1", "2" or "")
	AcceptAppCaps string // L7 only - comma-separated app capabilities forwarded to the target
}

ServeEndpoint represents a single Tailscale serve configuration. Configured via labels like: tslink.serve.443=https:8080/api.

type Service added in v0.3.5

type Service struct {
	Name      string          // With the svc: prefix, e.g. "svc:web"
	Endpoints []ServeEndpoint // What the node serves for it
}

Service is a Tailscale Service the container is a backend of, and what it serves on it.

type Status

type Status struct {
	IP       string
	Hostname string
	Online   bool
}

Status represents the status of a Tailscale connection.

type SupervisorStatus

type SupervisorStatus string

SupervisorStatus represents the current state of the supervisor.

const (
	StatusStopped   SupervisorStatus = "stopped"
	StatusStarting  SupervisorStatus = "starting"
	StatusRunning   SupervisorStatus = "running"
	StatusFailed    SupervisorStatus = "failed"
	StatusCrashLoop SupervisorStatus = "crash_loop"
)

Supervisor states.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL