Documentation
¶
Overview ¶
Package tailscale runs and supervises tailscaled for each endpoint.
Index ¶
- Constants
- func BundledBinaries() (string, string, error)
- func CertNotAfter(path string) (time.Time, error)
- func CheckAuthKeyMatch(stateDir, authKey string) bool
- func ClearEphemeral(stateDir string) error
- func GetHostnameStateDir(dataDir, hostname string) string
- func IsMarkedEphemeral(stateDir string) bool
- func KeyEphemeral(key string) (bool, bool, error)
- func LinkCertsDir(stateDir, shared string) error
- func LogoutState(ctx context.Context, tailscaledBin, stateDir, socket string) error
- func MarkEphemeral(stateDir string) error
- func SaveAuthKeyHash(stateDir, authKey string) error
- func StateExists(stateDir string) bool
- func WipeState(stateDir string) error
- type Daemon
- func (d *Daemon) BackendState() (string, error)
- func (d *Daemon) Drain(service string) error
- func (d *Daemon) HostEndpoints() []netip.AddrPort
- func (d *Daemon) IsRunning() bool
- func (d *Daemon) LoggedOut() bool
- func (d *Daemon) Logout() error
- func (d *Daemon) Reauthenticate() error
- func (d *Daemon) Start() error
- func (d *Daemon) Stop() error
- func (d *Daemon) WaitForIP(ctx context.Context) (*Status, error)
- type DaemonConfig
- type DaemonSupervisor
- func (s *DaemonSupervisor) Drain(service string) error
- func (s *DaemonSupervisor) DrainAndWait(service string)
- func (s *DaemonSupervisor) Drained() bool
- func (s *DaemonSupervisor) GetDaemon() *Daemon
- func (s *DaemonSupervisor) Logout() error
- func (s *DaemonSupervisor) Readiness(ctx context.Context) Readiness
- func (s *DaemonSupervisor) Start() error
- func (s *DaemonSupervisor) StartContext(ctx context.Context) error
- func (s *DaemonSupervisor) Status() (SupervisorStatus, int)
- func (s *DaemonSupervisor) Stop() error
- func (s *DaemonSupervisor) WaitForIP(ctx context.Context) (*Status, error)
- type Readiness
- type ServeEndpoint
- type Status
- type SupervisorStatus
Constants ¶
const BundledVersion = "bundled"
BundledVersion is the only supported TS_VERSION: the Tailscale shipped in the plugin image.
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 ¶
BundledBinaries returns the paths of the tailscale and tailscaled binaries shipped in the plugin image, so every node runs the same version.
func CertNotAfter ¶
CertNotAfter returns the expiry of the first certificate in a PEM file.
func CheckAuthKeyMatch ¶
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 ¶
ClearEphemeral removes the mark MarkEphemeral set, if any, when stateDir is used by a network whose nodes are not ephemeral.
func GetHostnameStateDir ¶
GetHostnameStateDir returns the state directory path for a hostname. The directory structure is: <dataDir>/by-hostname/<hostname>/.
func IsMarkedEphemeral ¶
IsMarkedEphemeral reports whether stateDir was marked by MarkEphemeral.
func KeyEphemeral ¶ added in v0.2.4
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 ¶
LinkCertsDir makes the state directory's certs directory a link to shared, creating shared and an ACME account key in it. 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 ¶
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 ¶
MarkEphemeral marks stateDir as holding an ephemeral node.
func SaveAuthKeyHash ¶
SaveAuthKeyHash stores the SHA256 hash of the auth key in the state directory.
func StateExists ¶
StateExists checks if valid Tailscale state exists in the given directory. Returns true if tailscaled.state file exists and is non-empty.
Types ¶
type Daemon ¶
type Daemon struct {
// contains filtered or unexported fields
}
Daemon manages a tailscaled process.
func NewDaemon ¶
func NewDaemon(cfg DaemonConfig) (*Daemon, error)
NewDaemon creates a new Daemon instance.
func (*Daemon) BackendState ¶
BackendState returns tailscaled's backend state, such as Running or NeedsLogin.
func (*Daemon) Drain ¶
Drain stops new connections to the node's backend for a Tailscale Service; existing connections continue. The backend stays drained: tslink does not advertise it again. Draining again does nothing once a drain took effect, and neither does a drain of a Service the node's prefs no longer advertise, as one drained outside tslink. A serve configuration in progress is cancelled rather than waited for.
func (*Daemon) HostEndpoints ¶ added in v0.2.2
HostEndpoints returns the endpoints on the host this tailscaled advertises.
func (*Daemon) LoggedOut ¶
LoggedOut reports whether the node has lost its login: tailscaled needs a login, or control recently said it does not know the node. Being offline is not enough: the control plane may just be unreachable, and the node key still valid.
func (*Daemon) Reauthenticate ¶
Reauthenticate logs a node in again with the auth key, as a new device, and restores what it serves.
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
TailscaleBin string // Path to tailscale CLI binary
TailscaledBin string // Path to tailscaled daemon binary
Tags []string // ACL tags for --advertise-tags
Service string // Service name for tailscale serve (e.g., "svc:hello-world")
Endpoints []ServeEndpoint // Serve endpoints (L3/L4/L7)
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)
// 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(service string) error
Drain stops new connections to the node's backend for a Tailscale Service. The backend stays drained, even if tailscaled is down and the drain fails: a daemon the supervisor starts later does not advertise it.
func (*DaemonSupervisor) DrainAndWait ¶
func (s *DaemonSupervisor) DrainAndWait(service string)
DrainAndWait drains the node's backend for service, unless that was done, as when the container got its stop signal, and waits for control to learn of it: until control fetched the drained Service list, at least drainAckFloor and at most drainAckTimeout after the drain. A backend never advertised has nothing for control to fetch, and is not waited for.
func (*DaemonSupervisor) Drained ¶
func (s *DaemonSupervisor) Drained() bool
Drained reports whether the node's Service backend has been drained.
func (*DaemonSupervisor) GetDaemon ¶
func (s *DaemonSupervisor) GetDaemon() *Daemon
GetDaemon returns the current daemon (may be nil if not running).
func (*DaemonSupervisor) Logout ¶
func (s *DaemonSupervisor) Logout() error
Logout logs the running daemon's node out.
func (*DaemonSupervisor) Readiness ¶
func (s *DaemonSupervisor) Readiness(ctx context.Context) Readiness
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.
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.
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 ReadyAwaitingApproval Readiness = "awaiting-approval" // control has not approved the backend 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 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 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.