hscontrol

package
v0.29.2 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2026 License: BSD-3-Clause Imports: 95 Imported by: 1

Documentation

Overview

nolint

Index

Constants

View Source 
const (
	AuthPrefix = "Bearer "
)
View Source 
const (
	// NoiseCapabilityVersion is used by Tailscale clients to indicate
	// their codebase version. Tailscale clients can communicate over TS2021
	// from CapabilityVersion 28, but we only have good support for it
	// since https://github.com/tailscale/tailscale/pull/4323 (Noise in any HTTPS port).
	//
	// Related to this change, there is https://github.com/tailscale/tailscale/pull/5379,
	// where CapabilityVersion 39 is introduced to indicate #4323 was merged.
	//
	// See also https://github.com/tailscale/tailscale/blob/main/tailcfg/tailcfg.go
	NoiseCapabilityVersion = 39
)

Variables

View Source 
var ErrMissingURLParameter = errors.New("missing URL parameter")

ErrMissingURLParameter is returned when a required URL parameter is not provided.

View Source 
var ErrNoAuthSession = errors.New("no auth session found")

ErrNoAuthSession is returned when an auth_id does not match any active auth session.

View Source 
var ErrNoCertDomains = errors.New("no cert domains available for HTTPS")

ErrNoCertDomains is returned when no cert domains are available for HTTPS.

View Source 
var ErrRegisterMethodCLIDoesNotSupportExpire = errors.New(
	"machines registered with CLI do not support expiry",
)
View Source 
var ErrSSHAuthSessionNotBound = errors.New(
	"ssh action: cached auth session is not an SSH-check binding",
)

ErrSSHAuthSessionNotBound is returned when an SSH action follow-up references an auth session that is not bound to an SSH check pair.

View Source 
var ErrSSHBindingMismatch = errors.New(
	"ssh action: cached binding does not match request src/dst",
)

ErrSSHBindingMismatch is returned when an SSH action follow-up's (src, dst) pair does not match the cached binding for its auth_id.

View Source 
var ErrSSHDstNodeNotFound = errors.New("ssh action: unknown dst node id")

ErrSSHDstNodeNotFound is returned when the dst node id on a Noise SSH action request does not match any registered node.

View Source 
var ErrSSHMachineKeyMismatch = errors.New(
	"ssh action: noise session machine key does not match dst node",
)

ErrSSHMachineKeyMismatch is returned when the Noise session's machine key does not match the dst node referenced in the SSH action URL.

View Source 
var ErrUnsupportedClientVersion = errors.New("unsupported client version")

ErrUnsupportedClientVersion is returned when a client connects with an unsupported protocol version.

View Source 
var ErrUnsupportedURLParameterType = errors.New("unsupported URL parameter type")

ErrUnsupportedURLParameterType is returned when a URL parameter has an unsupported type.

Functions

func BlankHandler added in v0.28.0 

func BlankHandler(writer http.ResponseWriter, res *http.Request)

BlankHandler returns a blank page with favicon linked.

func FaviconHandler added in v0.28.0 

func FaviconHandler(writer http.ResponseWriter, req *http.Request)

Types

type AppleMobileConfig 

type AppleMobileConfig struct {
	UUID    uuid.UUID
	URL     string
	Payload string
}

type AppleMobilePlatformConfig 

type AppleMobilePlatformConfig struct {
	UUID uuid.UUID
	URL  string
}

type AuthInfo added in v0.29.0 

type AuthInfo struct {
	AuthID       types.AuthID
	Verifier     *string
	Registration bool
}

AuthInfo contains both auth ID and verifier information for OIDC validation.

type AuthProvider added in v0.24.0 

type AuthProvider interface {
	RegisterHandler(w http.ResponseWriter, r *http.Request)
	AuthHandler(w http.ResponseWriter, r *http.Request)
	RegisterURL(authID types.AuthID) string
	AuthURL(authID types.AuthID) string
}

type AuthProviderOIDC added in v0.24.0 

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

func NewAuthProviderOIDC added in v0.24.0 

func NewAuthProviderOIDC(
	ctx context.Context,
	h *Headscale,
	serverURL string,
	cfg *types.OIDCConfig,
) (*AuthProviderOIDC, error)

func (*AuthProviderOIDC) AuthHandler added in v0.29.0 

func (a *AuthProviderOIDC) AuthHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

func (*AuthProviderOIDC) AuthURL added in v0.24.0 

func (a *AuthProviderOIDC) AuthURL(authID types.AuthID) string

func (*AuthProviderOIDC) OIDCCallbackHandler added in v0.24.0 

func (a *AuthProviderOIDC) OIDCCallbackHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

OIDCCallbackHandler handles the callback from the OIDC endpoint Retrieves the nkey from the state cache and adds the node to the users email user TODO: A confirmation page for new nodes should be added to avoid phishing vulnerabilities TODO: Add groups information from OIDC tokens into node HostInfo Listens in /oidc/callback.

func (*AuthProviderOIDC) RegisterConfirmHandler added in v0.29.0 

func (a *AuthProviderOIDC) RegisterConfirmHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

RegisterConfirmHandler is the POST endpoint behind the OIDC registration confirmation interstitial. It validates the CSRF cookie against the form-submitted token, finalises the registration via [AuthProviderOIDC.handleRegistration], and renders the success page.

func (*AuthProviderOIDC) RegisterHandler added in v0.24.0 

func (a *AuthProviderOIDC) RegisterHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

RegisterHandler registers the OIDC callback handler with the given router. It puts NodeKey in cache so the callback can retrieve it using the oidc state param. Listens in /register/:auth_id.

func (*AuthProviderOIDC) RegisterURL added in v0.29.0 

func (a *AuthProviderOIDC) RegisterURL(authID types.AuthID) string

type AuthProviderWeb added in v0.24.0 

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

func NewAuthProviderWeb added in v0.24.0 

func NewAuthProviderWeb(serverURL string) *AuthProviderWeb

func (*AuthProviderWeb) AuthHandler added in v0.29.0 

func (a *AuthProviderWeb) AuthHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

func (*AuthProviderWeb) AuthURL added in v0.24.0 

func (a *AuthProviderWeb) AuthURL(authID types.AuthID) string

func (*AuthProviderWeb) RegisterHandler added in v0.24.0 

func (a *AuthProviderWeb) RegisterHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

RegisterHandler shows a simple message in the browser to point to the CLI Listens in /register/:registration_id.

This is not part of the Tailscale control API, as we could send whatever URL in the tailcfg.RegisterResponse.AuthURL field.

func (*AuthProviderWeb) RegisterURL added in v0.29.0 

func (a *AuthProviderWeb) RegisterURL(authID types.AuthID) string

type DebugBatcherInfo added in v0.27.0 

type DebugBatcherInfo struct {
	ConnectedNodes map[string]DebugBatcherNodeInfo `json:"connected_nodes"` // NodeID -> node connection info
	TotalNodes     int                             `json:"total_nodes"`
}

DebugBatcherInfo represents batcher connection information in a structured format.

type DebugBatcherNodeInfo added in v0.27.0 

type DebugBatcherNodeInfo struct {
	Connected         bool `json:"connected"`
	ActiveConnections int  `json:"active_connections"`
}

DebugBatcherNodeInfo represents connection information for a single node.

type HTTPError added in v0.25.0 

type HTTPError struct {
	Code int    // HTTP response code to send to client; 0 means 500
	Msg  string // Response body to send to client
	Err  error  // Detailed error to log on the server
}

HTTPError represents an error that is surfaced to the user via web.

func NewHTTPError added in v0.25.0 

func NewHTTPError(code int, msg string, err error) HTTPError

NewHTTPError returns an HTTPError containing the given information.

func (HTTPError) Error added in v0.25.0 

func (e HTTPError) Error() string

func (HTTPError) Unwrap added in v0.25.0 

func (e HTTPError) Unwrap() error

type Headscale 

type Headscale struct {
	DERPServer *derpServer.DERPServer
	// contains filtered or unexported fields
}

Headscale represents the base app of the service.

func NewHeadscale 

func NewHeadscale(cfg *types.Config) (*Headscale, error)

func (*Headscale) AppleConfigMessage 

func (h *Headscale) AppleConfigMessage(
	writer http.ResponseWriter,
	req *http.Request,
)

AppleConfigMessage shows a simple message in the browser to point the user to the iOS/MacOS profile and instructions for how to install it.

func (*Headscale) ApplePlatformConfig 

func (h *Headscale) ApplePlatformConfig(
	writer http.ResponseWriter,
	req *http.Request,
)

func (*Headscale) Change added in v0.27.0 

func (h *Headscale) Change(cs ...change.Change)

Change is used to send changes to nodes. All change should be enqueued here and empty will be automatically ignored.

func (*Headscale) GetState added in v0.29.0 

func (h *Headscale) GetState() *state.State

GetState returns the server's state manager for programmatic access to users, nodes, policies, and other server state.

func (*Headscale) HTTPHandler added in v0.29.0 

func (h *Headscale) HTTPHandler() http.Handler

HTTPHandler returns an http.Handler for the Headscale control server. The handler serves the Tailscale control protocol including the /key endpoint and /ts2021 Noise upgrade path.

func (*Headscale) HealthHandler 

func (h *Headscale) HealthHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

func (*Headscale) KeyHandler 

func (h *Headscale) KeyHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

KeyHandler provides the Headscale pub key Listens in /key.

func (*Headscale) MapBatcher added in v0.29.0 

func (h *Headscale) MapBatcher() *mapper.Batcher

MapBatcher returns the map response batcher (for test use).

func (*Headscale) NoisePublicKey added in v0.29.0 

func (h *Headscale) NoisePublicKey() key.MachinePublic

NoisePublicKey returns the server's Noise protocol public key.

func (*Headscale) NoiseUpgradeHandler 

func (h *Headscale) NoiseUpgradeHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

NoiseUpgradeHandler is to upgrade the connection and hijack the net.Conn in order to use the Noise-based TS2021 protocol. Listens in /ts2021.

func (*Headscale) PingResponseHandler added in v0.29.0 

func (h *Headscale) PingResponseHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

PingResponseHandler handles HEAD requests from clients responding to a tailcfg.PingRequest. The client calls this endpoint to prove connectivity. The unguessable ping ID serves as authentication.

func (*Headscale) RobotsHandler added in v0.27.0 

func (h *Headscale) RobotsHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

func (*Headscale) Serve 

func (h *Headscale) Serve() error

Serve launches the HTTP and gRPC server service Headscale and the API.

func (*Headscale) SetServerURLForTest added in v0.29.0 

func (h *Headscale) SetServerURLForTest(tb testing.TB, url string)

SetServerURLForTest updates the server URL in the configuration. This is needed for test servers where the URL is not known until the HTTP test server starts. It panics when called outside of tests.

func (*Headscale) StartBatcherForTest added in v0.29.0 

func (h *Headscale) StartBatcherForTest(tb testing.TB)

StartBatcherForTest initialises and starts the map response batcher. It registers a cleanup function on tb to stop the batcher. It panics when called outside of tests.

func (*Headscale) StartEphemeralGCForTest added in v0.29.0 

func (h *Headscale) StartEphemeralGCForTest(tb testing.TB)

StartEphemeralGCForTest starts the ephemeral node garbage collector. It registers a cleanup function on tb to stop the collector. It panics when called outside of tests.

func (*Headscale) VerifyHandler added in v0.24.0 

func (h *Headscale) VerifyHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

VerifyHandler see https://github.com/tailscale/tailscale/blob/964282d34f06ecc06ce644769c66b0b31d118340/derp/derp_server.go#L1159 DERP use verifyClientsURL to verify whether a client is allowed to connect to the DERP server.

func (*Headscale) VersionHandler added in v0.27.0 

func (h *Headscale) VersionHandler(
	writer http.ResponseWriter,
	req *http.Request,
)

VersionHandler returns version information about the Headscale server Listens in /version.

func (*Headscale) WindowsConfigMessage 

func (h *Headscale) WindowsConfigMessage(
	writer http.ResponseWriter,
	req *http.Request,
)

WindowsConfigMessage shows a simple message in the browser for how to configure the Windows Tailscale client.

Source Files

View all Source files

Directories

Path Synopsis
Package assets provides embedded static assets for Headscale.
 Package assets provides embedded static assets for Headscale.
db
sqliteconfig
Package sqliteconfig provides type-safe configuration for SQLite databases with proper enum validation and URL generation for modernc.org/sqlite driver.
 Package sqliteconfig provides type-safe configuration for SQLite databases with proper enum validation and URL generation for modernc.org/sqlite driver.
server
matcher
policyutil
Package policyutil contains pure functions that transform compiled policy rules for a specific node.
 Package policyutil contains pure functions that transform compiled policy rules for a specific node.
v2
Package servertest provides an in-process test harness for Headscale's control plane.
 Package servertest provides an in-process test harness for Headscale's control plane.
change
Package change declares the Change type: a compact description of what must land in a tailcfg.MapResponse.
 Package change declares the Change type: a compact description of what must land in a tailcfg.MapResponse.
testcapture
Package testcapture defines the on-disk format used by Headscale's policy v2 compatibility tests for golden data captured from a Tailscale-hosted control plane by an external capture tool.
 Package testcapture defines the on-disk format used by Headscale's policy v2 compatibility tests for golden data captured from a Tailscale-hosted control plane by an external capture tool.
zlog
Package zlog provides zerolog utilities for safe and consistent logging.
 Package zlog provides zerolog utilities for safe and consistent logging.
zlog/zf
Package zf provides zerolog field name constants for consistent logging.
 Package zf provides zerolog field name constants for consistent logging.

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.