headscale

package module
v0.17.0-beta5 Latest Latest
Warning

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

 Go to latest Published: Nov 25, 2022 License: BSD-3-Clause Imports: 80 Imported by: 1

README

headscale logo

ci

An open source, self-hosted implementation of the Tailscale control server.

Join our Discord server for a chat.

Note: Always select the same GitHub tag as the released version you use to ensure you have the correct example configuration and documentation. The main branch might contain unreleased changes.

What is Tailscale

Tailscale is a modern VPN built on top of Wireguard. It works like an overlay network between the computers of your networks - using NAT traversal.

Everything in Tailscale is Open Source, except the GUI clients for proprietary OS (Windows and macOS/iOS), and the control server.

The control server works as an exchange point of Wireguard public keys for the nodes in the Tailscale network. It assigns the IP addresses of the clients, creates the boundaries between each user, enables sharing machines between users, and exposes the advertised routes of your nodes.

A Tailscale network (tailnet) is private network which Tailscale assigns to a user in terms of private users or an organisation.

Design goal

headscale aims to implement a self-hosted, open source alternative to the Tailscale control server. headscale has a narrower scope and an instance of headscale implements a single Tailnet, which is typically what a single organisation, or home/personal setup would use.

headscale uses terms that maps to Tailscale's control server, consult the glossary for explainations.

Support

If you like headscale and find it useful, there is a sponsorship and donation buttons available in the repo.

If you would like to sponsor features, bugs or prioritisation, reach out to one of the maintainers.

Features

  • Full "base" support of Tailscale's features
  • Configurable DNS
  • Node registration
    • Single-Sign-On (via Open ID Connect)
    • Pre authenticated key
  • Taildrop (File Sharing)
  • Access control lists
  • MagicDNS
  • Support for multiple IP ranges in the tailnet
  • Dual stack (IPv4 and IPv6)
  • Routing advertising (including exit nodes)
  • Ephemeral nodes
  • Embedded DERP server

Client OS support

OS Supports headscale
Linux Yes
OpenBSD Yes
FreeBSD Yes
macOS Yes (see /apple on your headscale for more information)
Windows Yes docs
Android Yes docs
iOS Not yet

Running headscale

Please have a look at the documentation under docs/.

Disclaimer

  1. We have nothing to do with Tailscale, or Tailscale Inc.
  2. The purpose of Headscale is maintaining a working, self-hosted Tailscale control panel.

Contributing

To contribute to headscale you would need the lastest version of Go and Buf(Protobuf generator).

We recommend using Nix to setup a development environment. This can be done with nix develop, which will install the tools and give you a shell. This guarantees that you will have the same dev env as headscale maintainers.

PRs and suggestions are welcome.

Code style

To ensure we have some consistency with a growing number of contributions, this project has adopted linting and style/formatting rules:

The Go code is linted with golangci-lint and formatted with golines (width 88) and gofumpt. Please configure your editor to run the tools while developing and make sure to run make lint and make fmt before committing any code.

The Proto code is linted with buf and formatted with clang-format.

The rest (Markdown, YAML, etc) is formatted with prettier.

Check out the .golangci.yaml and Makefile to see the specific configuration.

Install development tools

  • Go
  • Buf
  • Protobuf tools

Install and activate:

nix develop

Testing and building

Some parts of the project require the generation of Go code from Protobuf (if changes are made in proto/) and it must be (re-)generated with:

make generate

Note: Please check in changes from gen/ in a separate commit to make it easier to review.

To run the tests:

make test

To build the program:

nix build

or

make build

Contributors

Kristoffer
Kristoffer Dalby 		Juan
Juan Font 		Adrien
Adrien Raffin-Caboisse 		Ward
Ward Vandewege 		Jiang
Jiang Zhu 		Benjamin
Benjamin Roberts
Nico/
Nico 		e-zk/
e-zk 		Justin
Justin Angel 		Alessandro
Alessandro (Ale) Segala 		unreality/
unreality 		ohdearaugustin/
ohdearaugustin
Moritz
Moritz Poldrack 		GrigoriyMikhalkin/
GrigoriyMikhalkin 		Mike
Mike Lloyd 		Anton
Anton Schubert 		Niek
Niek van der Maas 		Eugen
Eugen Biegler
Azz/
Azz 		Aaron
Aaron Bieber 		Igor
Igor Perepilitsyn 		Laurent
Laurent Marchaud 		Fernando
Fernando De Lucchi 		Orville
Orville Q. Song
hdhoang/
hdhoang 		bravechamp/
bravechamp 		Deon
Deon Thomas 		Jamie
Jamie Greeff 		ChibangLW/
ChibangLW 		Mevan
Mevan Samaratunga
Michael
Michael G. 		Paul
Paul Tötterman 		Samuel
Samuel Lock 		Stefan
Stefan Majer 		kevinlin/
kevinlin 		Artem
Artem Klevtsov
Casey
Casey Marshall 		LiuHanCheng/
LiuHanCheng 		Pavlos
Pavlos Vinieratos 		Silver
Silver Bullet 		Steven
Steven Honson 		Victor
Victor Freire
lachy2849/
lachy2849 		thomas/
thomas 		Abraham
Abraham Ingersoll 		Andrei
Andrei Pechkurov 		Antoine
Antoine POPINEAU 		Aofei
Aofei Sheng
Arnar/
Arnar 		Arthur
Arthur Woimbée 		Bryan
Bryan Stenson 		Carson
Carson Yang 		kundel/
kundel 		Felix
Felix Kronlage-Dammers
Felix
Felix Yan 		JJGadgets/
JJGadgets 		Jim
Jim Tittsler 		Jonathan
Jonathan de Jong 		Pierre
Pierre Carru 		Rasmus
Rasmus Moorats
rcursaru/
rcursaru 		Mend
Mend Renovate 		Ryan
Ryan Fowler 		Shaanan
Shaanan Cohney 		Stefan
Stefan VanBuren 		sophware/
sophware
Tanner/
Tanner 		Teteros/
Teteros 		The
The Gitter Badger 		Tianon
Tianon Gravi 		Till
Till Hoffmann 		Tjerk
Tjerk Woudsma
Yang
Yang Bin 		Yujie
Yujie Xia 		Zakhar
Zakhar Bessarab 		Zhiyuan
Zhiyuan Zheng 		Ziyuan
Ziyuan Han 		derelm/
derelm
henning
henning mueller 		ignoramous/
ignoramous 		suhelen/
suhelen 		sharkonet/
sharkonet 		manju-rn/
manju-rn 		pernila/
pernila
phpmalik/
phpmalik 		Wakeful-Cloud/
Wakeful-Cloud 		zy/
zy

Documentation

Overview

nolint

Index

Constants

View Source 
const (
	Base8     = 8
	Base10    = 10
	BitSize16 = 16
	BitSize32 = 32
	BitSize64 = 64
)
View Source 
const (
	RegisterMethodAuthKey                    = "authkey"
	RegisterMethodOIDC                       = "oidc"
	RegisterMethodCLI                        = "cli"
	ErrRegisterMethodCLIDoesNotSupportExpire = Error(
		"machines registered with CLI does not support expire",
	)
)
View Source 
const (
	AuthPrefix = "Bearer "
	Postgres   = "postgres"
	Sqlite     = "sqlite3"

	HTTPReadTimeout     = 30 * time.Second
	HTTPShutdownTimeout = 3 * time.Second

	DisabledClientAuth = "disabled"
	RelaxedClientAuth  = "relaxed"
	EnforcedClientAuth = "enforced"
)
View Source 
const (
	JSONLogFormat = "json"
	TextLogFormat = "text"
)
View Source 
const (
	ErrMachineNotFound                  = Error("machine not found")
	ErrMachineRouteIsNotAvailable       = Error("route is not available on machine")
	ErrMachineAddressesInvalid          = Error("failed to parse machine addresses")
	ErrMachineNotFoundRegistrationCache = Error(
		"machine not found in registration cache",
	)
	ErrCouldNotConvertMachineInterface = Error("failed to convert machine interface")
	ErrHostnameTooLong                 = Error("Hostname too long")
	ErrDifferentRegisteredNamespace    = Error(
		"machine was previously registered with a different namespace",
	)
	MachineGivenNameHashLength = 8
	MachineGivenNameTrimSize   = 2
)
View Source 
const (
	ErrNamespaceExists          = Error("Namespace already exists")
	ErrNamespaceNotFound        = Error("Namespace not found")
	ErrNamespaceNotEmptyOfNodes = Error("Namespace not empty: node(s) found")
	ErrInvalidNamespaceName     = Error("Invalid namespace name")
)
View Source 
const (
	ErrPreAuthKeyNotFound          = Error("AuthKey not found")
	ErrPreAuthKeyExpired           = Error("AuthKey expired")
	ErrSingleUseAuthKeyHasBeenUsed = Error("AuthKey has already been used")
	ErrNamespaceMismatch           = Error("namespace mismatch")
	ErrPreAuthKeyACLTagInvalid     = Error("AuthKey tag is invalid")
)
View Source 
const (
	ErrCannotDecryptResponse = Error("cannot decrypt response")
	ErrCouldNotAllocateIP    = Error("could not find any suitable IP")

	PermissionFallback = 0o700

	ZstdCompression = "zstd"
)
View Source 
const (
	ByteSize = 8
)
View Source 
const (
	ErrAPIKeyFailedToParse = Error("Failed to parse ApiKey")
)
View Source 
const (
	ErrRouteIsNotAvailable = Error("route is not available")
)
View Source 
const (
	// The CapabilityVersion 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
)
View Source 
const (
	ProtocolFC = 133 // Fibre Channel
)

For some reason golang.org/x/net/internal/iana is an internal package.

Variables

View Source 
var (
	ExitRouteV4 = netip.MustParsePrefix("0.0.0.0/0")
	ExitRouteV6 = netip.MustParsePrefix("::/0")
)
View Source 
var NodePublicKeyRegex = regexp.MustCompile("nodekey:[a-fA-F0-9]+")

Functions

func AbsolutePathFromConfigPath added in v0.16.0 

func AbsolutePathFromConfigPath(path string) string

func CheckForFQDNRules added in v0.15.0 

func CheckForFQDNRules(name string) error

func DiscoPublicKeyEnsurePrefix added in v0.12.1 

func DiscoPublicKeyEnsurePrefix(discoKey string) string

func DiscoPublicKeyStripPrefix added in v0.12.1 

func DiscoPublicKeyStripPrefix(discoKey key.DiscoPublic) string

func GenerateRandomBytes added in v0.13.0 

func GenerateRandomBytes(n int) ([]byte, error)

GenerateRandomBytes returns securely generated random bytes. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func GenerateRandomStringDNSSafe added in v0.16.0 

func GenerateRandomStringDNSSafe(size int) (string, error)

GenerateRandomStringDNSSafe returns a DNS-safe securely generated random string. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func GenerateRandomStringURLSafe added in v0.13.0 

func GenerateRandomStringURLSafe(n int) (string, error)

GenerateRandomStringURLSafe returns a URL-safe, base64 encoded securely generated random string. It will return an error if the system's secure random number generator fails to function correctly, in which case the caller should not continue.

func GetDERPMap added in v0.11.0 

func GetDERPMap(cfg DERPConfig) *tailcfg.DERPMap

func GetDNSConfig added in v0.16.0 

func GetDNSConfig() (*tailcfg.DNSConfig, string)

func GetFileMode added in v0.16.0 

func GetFileMode(key string) fs.FileMode

func GetIPPrefixEndpoints added in v0.13.0 

func GetIPPrefixEndpoints(na netip.Prefix) (netip.Addr, netip.Addr)

func GrpcSocketDialer added in v0.12.1 

func GrpcSocketDialer(ctx context.Context, addr string) (net.Conn, error)

func IsCLIConfigured added in v0.17.0 

func IsCLIConfigured() bool

func IsStringInSlice added in v0.16.0 

func IsStringInSlice(slice []string, str string) bool

func LoadConfig added in v0.16.0 

func LoadConfig(path string, isFile bool) error

func MachinePublicKeyEnsurePrefix added in v0.12.1 

func MachinePublicKeyEnsurePrefix(machineKey string) string

func MachinePublicKeyStripPrefix added in v0.12.1 

func MachinePublicKeyStripPrefix(machineKey key.MachinePublic) string

func NodePublicKeyEnsurePrefix added in v0.12.1 

func NodePublicKeyEnsurePrefix(nodeKey string) string

func NodePublicKeyStripPrefix added in v0.12.1 

func NodePublicKeyStripPrefix(nodeKey key.NodePublic) string

func NormalizeToFQDNRules added in v0.15.0 

func NormalizeToFQDNRules(name string, stripEmailDomain bool) (string, error)

NormalizeToFQDNRules will replace forbidden chars in namespace it can also return an error if the namespace doesn't respect RFC 952 and 1123.

func PrivateKeyEnsurePrefix added in v0.12.1 

func PrivateKeyEnsurePrefix(privateKey string) string

func SwaggerAPIv1 added in v0.12.1 

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

func SwaggerUI added in v0.12.1 

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

Types

type ACL added in v0.3.0 

type ACL struct {
	Action       string   `json:"action" yaml:"action"`
	Protocol     string   `json:"proto"  yaml:"proto"`
	Sources      []string `json:"src"    yaml:"src"`
	Destinations []string `json:"dst"    yaml:"dst"`
}

ACL is a basic rule for the ACL Policy.

type ACLConfig added in v0.16.0 

type ACLConfig struct {
	PolicyPath string
}

func GetACLConfig added in v0.16.0 

func GetACLConfig() ACLConfig

type ACLPolicy added in v0.3.0 

type ACLPolicy struct {
	Groups        Groups        `json:"groups"        yaml:"groups"`
	Hosts         Hosts         `json:"hosts"         yaml:"hosts"`
	TagOwners     TagOwners     `json:"tagOwners"     yaml:"tagOwners"`
	ACLs          []ACL         `json:"acls"          yaml:"acls"`
	Tests         []ACLTest     `json:"tests"         yaml:"tests"`
	AutoApprovers AutoApprovers `json:"autoApprovers" yaml:"autoApprovers"`
}

ACLPolicy represents a Tailscale ACL Policy.

func (ACLPolicy) IsZero added in v0.3.0 

func (policy ACLPolicy) IsZero() bool

IsZero is perhaps a bit naive here.

type ACLTest added in v0.3.0 

type ACLTest struct {
	Source string   `json:"src"            yaml:"src"`
	Accept []string `json:"accept"         yaml:"accept"`
	Deny   []string `json:"deny,omitempty" yaml:"deny,omitempty"`
}

ACLTest is not implemented, but should be use to check if a certain rule is allowed.

type APIKey added in v0.13.0 

type APIKey struct {
	ID     uint64 `gorm:"primary_key"`
	Prefix string `gorm:"uniqueIndex"`
	Hash   []byte

	CreatedAt  *time.Time
	Expiration *time.Time
	LastSeen   *time.Time
}

APIKey describes the datamodel for API keys used to remotely authenticate with headscale.

type AppleMobileConfig added in v0.9.2 

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

type AppleMobilePlatformConfig added in v0.9.2 

type AppleMobilePlatformConfig struct {
	UUID uuid.UUID
	URL  string
}

type AutoApprovers added in v0.17.0 

type AutoApprovers struct {
	Routes   map[string][]string `json:"routes"   yaml:"routes"`
	ExitNode []string            `json:"exitNode" yaml:"exitNode"`
}

AutoApprovers specify which users (namespaces?), groups or tags have their advertised routes or exit node status automatically enabled.

func (*AutoApprovers) GetRouteApprovers added in v0.17.0 

func (autoApprovers *AutoApprovers) GetRouteApprovers(
	prefix netip.Prefix,
) ([]string, error)

Returns the list of autoApproving namespaces, groups or tags for a given IPPrefix.

type CLIConfig added in v0.12.1 

type CLIConfig struct {
	Address  string
	APIKey   string
	Timeout  time.Duration
	Insecure bool
}

type Config 

type Config struct {
	ServerURL                      string
	Addr                           string
	MetricsAddr                    string
	GRPCAddr                       string
	GRPCAllowInsecure              bool
	EphemeralNodeInactivityTimeout time.Duration
	NodeUpdateCheckInterval        time.Duration
	IPPrefixes                     []netip.Prefix
	PrivateKeyPath                 string
	NoisePrivateKeyPath            string
	BaseDomain                     string
	Log                            LogConfig
	DisableUpdateCheck             bool

	DERP DERPConfig

	DBtype string
	DBpath string
	DBhost string
	DBport int
	DBname string
	DBuser string
	DBpass string
	DBssl  string

	TLS TLSConfig

	ACMEURL   string
	ACMEEmail string

	DNSConfig *tailcfg.DNSConfig

	UnixSocket           string
	UnixSocketPermission fs.FileMode

	OIDC OIDCConfig

	LogTail             LogTailConfig
	RandomizeClientPort bool

	CLI CLIConfig

	ACL ACLConfig
}

Config contains the initial Headscale configuration.

func GetHeadscaleConfig added in v0.16.0 

func GetHeadscaleConfig() (*Config, error)

type DERPConfig added in v0.11.0 

type DERPConfig struct {
	ServerEnabled    bool
	ServerRegionID   int
	ServerRegionCode string
	ServerRegionName string
	STUNAddr         string
	URLs             []url.URL
	Paths            []string
	AutoUpdate       bool
	UpdateFrequency  time.Duration
}

func GetDERPConfig added in v0.16.0 

func GetDERPConfig() DERPConfig

type DERPServer added in v0.15.0 

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

type Error 

type Error string

Error is used to compare errors as per https://dave.cheney.net/2016/04/07/constant-errors

func (Error) Error 

func (e Error) Error() string

type Groups added in v0.3.0 

type Groups map[string][]string

Groups references a series of alias in the ACL rules.

type Headscale 

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

Headscale represents the base app of the service.

func NewHeadscale 

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

func (*Headscale) AppleConfigMessage added in v0.15.0 

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 added in v0.9.2 

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

func (*Headscale) CreateAPIKey added in v0.13.0 

func (h *Headscale) CreateAPIKey(
	expiration *time.Time,
) (string, *APIKey, error)

CreateAPIKey creates a new ApiKey in a namespace, and returns it.

func (*Headscale) CreateNamespace 

func (h *Headscale) CreateNamespace(name string) (*Namespace, error)

CreateNamespace creates a new Namespace. Returns error if could not be created or another namespace already exists.

func (*Headscale) CreatePreAuthKey 

func (h *Headscale) CreatePreAuthKey(
	namespaceName string,
	reusable bool,
	ephemeral bool,
	expiration *time.Time,
	aclTags []string,
) (*PreAuthKey, error)

CreatePreAuthKey creates a new PreAuthKey in a namespace, and returns it.

func (*Headscale) DERPBootstrapDNSHandler added in v0.15.0 

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

DERPBootstrapDNSHandler implements the /bootsrap-dns endpoint Described in https://github.com/tailscale/tailscale/issues/1405, this endpoint provides a way to help a client when it fails to start up because its DNS are broken. The initial implementation is here https://github.com/tailscale/tailscale/pull/1406 They have a cache, but not clear if that is really necessary at Headscale, uh, scale. An example implementation is found here https://derp.tailscale.com/bootstrap-dns

func (*Headscale) DERPHandler added in v0.15.0 

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

func (*Headscale) DERPProbeHandler added in v0.15.0 

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

DERPProbeHandler is the endpoint that js/wasm clients hit to measure DERP latency, since they can't do UDP STUN queries.

func (*Headscale) DeleteMachine added in v0.6.1 

func (h *Headscale) DeleteMachine(machine *Machine) error

DeleteMachine softs deletes a Machine from the database.

func (*Headscale) DestroyAPIKey added in v0.13.0 

func (h *Headscale) DestroyAPIKey(key APIKey) error

DestroyAPIKey destroys a ApiKey. Returns error if the ApiKey does not exist.

func (*Headscale) DestroyNamespace 

func (h *Headscale) DestroyNamespace(name string) error

DestroyNamespace destroys a Namespace. Returns error if the Namespace does not exist or if there are machines associated with it.

func (*Headscale) DestroyPreAuthKey added in v0.12.1 

func (h *Headscale) DestroyPreAuthKey(pak PreAuthKey) error

DestroyPreAuthKey destroys a preauthkey. Returns error if the PreAuthKey does not exist.

func (*Headscale) EnableAutoApprovedRoutes added in v0.17.0 

func (h *Headscale) EnableAutoApprovedRoutes(machine *Machine)

Enabled any routes advertised by a machine that match the ACL autoApprovers policy.

func (*Headscale) EnableNodeRoute deprecated 

func (h *Headscale) EnableNodeRoute(
	namespace string,
	nodeName string,
	routeStr string,
) error

Deprecated: use EnableRoute in machine.go EnableNodeRoute enables a subnet route advertised by a node (identified by namespace and node name).

func (*Headscale) EnableRoutes added in v0.12.1 

func (h *Headscale) EnableRoutes(machine *Machine, routeStrs ...string) error

EnableNodeRoute enables new routes based on a list of new routes. It will _replace_ the previous list of routes.

func (*Headscale) ExpireAPIKey added in v0.13.0 

func (h *Headscale) ExpireAPIKey(key *APIKey) error

ExpireAPIKey marks a ApiKey as expired.

func (*Headscale) ExpireMachine added in v0.12.1 

func (h *Headscale) ExpireMachine(machine *Machine) error

ExpireMachine takes a Machine struct and sets the expire field to now.

func (*Headscale) ExpirePreAuthKey added in v0.12.1 

func (h *Headscale) ExpirePreAuthKey(k *PreAuthKey) error

MarkExpirePreAuthKey marks a PreAuthKey as expired.

func (*Headscale) GenerateGivenName added in v0.16.0 

func (h *Headscale) GenerateGivenName(machineKey string, suppliedName string) (string, error)

func (*Headscale) GetAPIKey added in v0.13.0 

func (h *Headscale) GetAPIKey(prefix string) (*APIKey, error)

GetAPIKey returns a ApiKey for a given key.

func (*Headscale) GetAPIKeyByID added in v0.13.0 

func (h *Headscale) GetAPIKeyByID(id uint64) (*APIKey, error)

GetAPIKeyByID returns a ApiKey for a given id.

func (*Headscale) GetAdvertisedNodeRoutes deprecated added in v0.7.0 

func (h *Headscale) GetAdvertisedNodeRoutes(
	namespace string,
	nodeName string,
) (*[]netip.Prefix, error)

Deprecated: use machine function instead GetAdvertisedNodeRoutes returns the subnet routes advertised by a node (identified by namespace and node name).

func (*Headscale) GetEnabledNodeRoutes deprecated added in v0.7.0 

func (h *Headscale) GetEnabledNodeRoutes(
	namespace string,
	nodeName string,
) ([]netip.Prefix, error)

Deprecated: use machine function instead GetEnabledNodeRoutes returns the subnet routes enabled by a node (identified by namespace and node name).

func (*Headscale) GetMachine 

func (h *Headscale) GetMachine(namespace string, name string) (*Machine, error)

GetMachine finds a Machine by name and namespace and returns the Machine struct.

func (*Headscale) GetMachineByAnyNodeKey added in v0.17.0 

func (h *Headscale) GetMachineByAnyNodeKey(
	nodeKey key.NodePublic, oldNodeKey key.NodePublic,
) (*Machine, error)

GetMachineByAnyNodeKey finds a Machine by its current NodeKey or the old one, and returns the Machine struct.

func (*Headscale) GetMachineByGivenName added in v0.17.0 

func (h *Headscale) GetMachineByGivenName(namespace string, givenName string) (*Machine, error)

GetMachineByGivenName finds a Machine by given name and namespace and returns the Machine struct.

func (*Headscale) GetMachineByID added in v0.6.1 

func (h *Headscale) GetMachineByID(id uint64) (*Machine, error)

GetMachineByID finds a Machine by ID and returns the Machine struct.

func (*Headscale) GetMachineByMachineKey added in v0.9.3 

func (h *Headscale) GetMachineByMachineKey(
	machineKey key.MachinePublic,
) (*Machine, error)

GetMachineByMachineKey finds a Machine by its MachineKey and returns the Machine struct.

func (*Headscale) GetMachineByNodeKey added in v0.16.1 

func (h *Headscale) GetMachineByNodeKey(
	nodeKey key.NodePublic,
) (*Machine, error)

GetMachineByNodeKey finds a Machine by its current NodeKey.

func (*Headscale) GetNamespace 

func (h *Headscale) GetNamespace(name string) (*Namespace, error)

GetNamespace fetches a namespace by name.

func (*Headscale) GetPreAuthKey added in v0.6.1 

func (h *Headscale) GetPreAuthKey(namespace string, key string) (*PreAuthKey, error)

GetPreAuthKey returns a PreAuthKey for a given key.

func (*Headscale) HardDeleteMachine added in v0.6.1 

func (h *Headscale) HardDeleteMachine(machine *Machine) error

HardDeleteMachine hard deletes a Machine from the database.

func (*Headscale) HealthHandler added in v0.16.1 

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

func (*Headscale) IsNodeRouteEnabled deprecated added in v0.7.0 

func (h *Headscale) IsNodeRouteEnabled(
	namespace string,
	nodeName string,
	routeStr string,
) bool

Deprecated: use machine function instead IsNodeRouteEnabled checks if a certain route has been enabled.

func (*Headscale) KeyHandler 

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

KeyHandler provides the Headscale pub key Listens in /key.

func (*Headscale) ListAPIKeys added in v0.13.0 

func (h *Headscale) ListAPIKeys() ([]APIKey, error)

ListAPIKeys returns the list of ApiKeys for a namespace.

func (*Headscale) ListMachines added in v0.12.1 

func (h *Headscale) ListMachines() ([]Machine, error)

func (*Headscale) ListMachinesByGivenName added in v0.17.0 

func (h *Headscale) ListMachinesByGivenName(givenName string) ([]Machine, error)

func (*Headscale) ListMachinesInNamespace 

func (h *Headscale) ListMachinesInNamespace(name string) ([]Machine, error)

ListMachinesInNamespace gets all the nodes in a given namespace.

func (*Headscale) ListNamespaces 

func (h *Headscale) ListNamespaces() ([]Namespace, error)

ListNamespaces gets all the existing namespaces.

func (*Headscale) ListPeers added in v0.15.0 

func (h *Headscale) ListPeers(machine *Machine) (Machines, error)

func (*Headscale) ListPreAuthKeys added in v0.12.1 

func (h *Headscale) ListPreAuthKeys(namespaceName string) ([]PreAuthKey, error)

ListPreAuthKeys returns the list of PreAuthKeys for a namespace.

func (*Headscale) LoadACLPolicy added in v0.3.0 

func (h *Headscale) LoadACLPolicy(path string) error

LoadACLPolicy loads the ACL policy from the specify path, and generates the ACL rules.

func (*Headscale) NewDERPServer added in v0.15.0 

func (h *Headscale) NewDERPServer() (*DERPServer, error)

func (*Headscale) NoisePollNetMapHandler added in v0.17.0 

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

NoisePollNetMapHandler takes care of /machine/:id/map using the Noise protocol

This is the busiest endpoint, as it keeps the HTTP long poll that updates the clients when something in the network changes.

The clients POST stuff like HostInfo and their Endpoints here, but only after their first request (marked with the ReadOnly field).

At this moment the updates are sent in a quite horrendous way, but they kinda work.

func (*Headscale) NoiseRegistrationHandler added in v0.17.0 

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

// NoiseRegistrationHandler handles the actual registration process of a machine.

func (*Headscale) NoiseUpgradeHandler added in v0.17.0 

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) OIDCCallback added in v0.12.1 

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

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

func (*Headscale) RefreshMachine added in v0.12.1 

func (h *Headscale) RefreshMachine(machine *Machine, expiry time.Time) error

RefreshMachine takes a Machine struct and sets the expire field to now.

func (*Headscale) RegisterMachine 

func (h *Headscale) RegisterMachine(machine Machine,
) (*Machine, error)

RegisterMachine is executed from the CLI to register a new Machine using its MachineKey.

func (*Headscale) RegisterMachineFromAuthCallback added in v0.15.0 

func (h *Headscale) RegisterMachineFromAuthCallback(
	nodeKeyStr string,
	namespaceName string,
	registrationMethod string,
) (*Machine, error)

func (*Headscale) RegisterOIDC added in v0.12.1 

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

RegisterOIDC redirects to the OIDC provider for authentication Puts NodeKey in cache so the callback can retrieve it using the oidc state param Listens in /oidc/register/:nKey.

func (*Headscale) RegisterWebAPI 

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

RegisterWebAPI shows a simple message in the browser to point to the CLI Listens in /register/:nkey.

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

func (*Headscale) RenameMachine added in v0.16.0 

func (h *Headscale) RenameMachine(machine *Machine, newName string) error

RenameMachine takes a Machine struct and a new GivenName for the machines and renames it.

func (*Headscale) RenameNamespace added in v0.10.4 

func (h *Headscale) RenameNamespace(oldName, newName string) error

RenameNamespace renames a Namespace. Returns error if the Namespace does not exist or if another Namespace exists with the new name.

func (*Headscale) Serve 

func (h *Headscale) Serve() error

Serve launches a GIN server with the Headscale API.

func (*Headscale) ServeSTUN added in v0.15.0 

func (h *Headscale) ServeSTUN()

ServeSTUN starts a STUN server on the configured addr.

func (*Headscale) SetMachineNamespace 

func (h *Headscale) SetMachineNamespace(machine *Machine, namespaceName string) error

SetMachineNamespace assigns a Machine to a namespace.

func (*Headscale) SetTags added in v0.16.0 

func (h *Headscale) SetTags(machine *Machine, tags []string) error

SetTags takes a Machine struct pointer and update the forced tags.

func (*Headscale) TouchMachine added in v0.12.4 

func (h *Headscale) TouchMachine(machine *Machine) error

func (*Headscale) UpdateACLRules added in v0.14.0 

func (h *Headscale) UpdateACLRules() error

func (*Headscale) UpdateMachineFromDatabase added in v0.16.0 

func (h *Headscale) UpdateMachineFromDatabase(machine *Machine) error

UpdateMachineFromDatabase takes a Machine struct pointer (typically already loaded from database and updates it with the latest data from the database.

func (*Headscale) UsePreAuthKey added in v0.15.0 

func (h *Headscale) UsePreAuthKey(k *PreAuthKey) error

UsePreAuthKey marks a PreAuthKey as used.

func (*Headscale) ValidateAPIKey added in v0.13.0 

func (h *Headscale) ValidateAPIKey(keyStr string) (bool, error)

func (*Headscale) WindowsConfigMessage added in v0.15.0 

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.

func (*Headscale) WindowsRegConfig added in v0.15.0 

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

WindowsRegConfig generates and serves a .reg file configured with the Headscale server address.

type HostInfo added in v0.15.0 

type HostInfo tailcfg.Hostinfo

This is a "wrapper" type around tailscales Hostinfo to allow us to add database "serialization" methods. This allows us to use a typed values throughout the code and not have to marshal/unmarshal and error check all over the code.

func (*HostInfo) Scan added in v0.15.0 

func (hi *HostInfo) Scan(destination interface{}) error

func (HostInfo) Value added in v0.15.0 

func (hi HostInfo) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface.

type Hosts added in v0.3.0 

type Hosts map[string]netip.Prefix

Hosts are alias for IP addresses or subnets.

func (*Hosts) UnmarshalJSON added in v0.3.0 

func (hosts *Hosts) UnmarshalJSON(data []byte) error

UnmarshalJSON allows to parse the Hosts directly into netip objects.

func (*Hosts) UnmarshalYAML added in v0.15.0 

func (hosts *Hosts) UnmarshalYAML(data []byte) error

UnmarshalYAML allows to parse the Hosts directly into netip objects.

type IDTokenClaims added in v0.12.1 

type IDTokenClaims struct {
	Name     string   `json:"name,omitempty"`
	Groups   []string `json:"groups,omitempty"`
	Email    string   `json:"email"`
	Username string   `json:"preferred_username,omitempty"`
}

type IPPrefixes added in v0.15.0 

type IPPrefixes []netip.Prefix

func (*IPPrefixes) Scan added in v0.15.0 

func (i *IPPrefixes) Scan(destination interface{}) error

func (IPPrefixes) Value added in v0.15.0 

func (i IPPrefixes) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface.

type KV 

type KV struct {
	Key   string
	Value string
}

KV is a key-value store in a psql table. For future use...

type LetsEncryptConfig added in v0.16.0 

type LetsEncryptConfig struct {
	Listen        string
	Hostname      string
	CacheDir      string
	ChallengeType string
}

type LogConfig added in v0.17.0 

type LogConfig struct {
	Format string
	Level  zerolog.Level
}

func GetLogConfig added in v0.17.0 

func GetLogConfig() LogConfig

type LogTailConfig added in v0.16.0 

type LogTailConfig struct {
	Enabled bool
}

func GetLogTailConfig added in v0.16.0 

func GetLogTailConfig() LogTailConfig

type Machine 

type Machine struct {
	ID          uint64 `gorm:"primary_key"`
	MachineKey  string `gorm:"type:varchar(64);unique_index"`
	NodeKey     string
	DiscoKey    string
	IPAddresses MachineAddresses

	// Hostname represents the name given by the Tailscale
	// client during registration
	Hostname string

	// Givenname represents either:
	// a DNS normalized version of Hostname
	// a valid name set by the User
	//
	// GivenName is the name used in all DNS related
	// parts of headscale.
	GivenName   string `gorm:"type:varchar(63);unique_index"`
	NamespaceID uint
	Namespace   Namespace `gorm:"foreignKey:NamespaceID"`

	RegisterMethod string

	ForcedTags StringList

	// TODO(kradalby): This seems like irrelevant information?
	AuthKeyID uint
	AuthKey   *PreAuthKey

	LastSeen             *time.Time
	LastSuccessfulUpdate *time.Time
	Expiry               *time.Time

	HostInfo      HostInfo
	Endpoints     StringList
	EnabledRoutes IPPrefixes

	CreatedAt time.Time
	UpdatedAt time.Time
	DeletedAt *time.Time
}

Machine is a Headscale client.

func (*Machine) GetAdvertisedRoutes added in v0.12.1 

func (machine *Machine) GetAdvertisedRoutes() []netip.Prefix

func (*Machine) GetEnabledRoutes added in v0.12.1 

func (machine *Machine) GetEnabledRoutes() []netip.Prefix

func (*Machine) GetHostInfo 

func (machine *Machine) GetHostInfo() tailcfg.Hostinfo

GetHostInfo returns a Hostinfo struct for the machine.

func (*Machine) IsRoutesEnabled added in v0.12.1 

func (machine *Machine) IsRoutesEnabled(routeStr string) bool

func (*Machine) RoutesToProto added in v0.12.1 

func (machine *Machine) RoutesToProto() *v1.Routes

func (Machine) String added in v0.9.3 

func (machine Machine) String() string

type MachineAddresses added in v0.13.0 

type MachineAddresses []netip.Addr

func (*MachineAddresses) Scan added in v0.13.0 

func (ma *MachineAddresses) Scan(destination interface{}) error

func (MachineAddresses) ToStringSlice added in v0.13.0 

func (ma MachineAddresses) ToStringSlice() []string

func (MachineAddresses) Value added in v0.13.0 

func (ma MachineAddresses) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface.

type Machines added in v0.9.3 

type Machines []Machine

func (Machines) String added in v0.9.3 

func (machines Machines) String() string

type MachinesP added in v0.9.3 

type MachinesP []*Machine

func (MachinesP) String added in v0.9.3 

func (machines MachinesP) String() string

TODO(kradalby): Remove when we have generics...

type Namespace 

type Namespace struct {
	gorm.Model
	Name string `gorm:"unique"`
}

Namespace is the way Headscale implements the concept of users in Tailscale

At the end of the day, users in Tailscale are some kind of 'bubbles' or namespaces that contain our machines.

type OIDCConfig added in v0.12.1 

type OIDCConfig struct {
	OnlyStartIfOIDCIsAvailable bool
	Issuer                     string
	ClientID                   string
	ClientSecret               string
	Scope                      []string
	ExtraParams                map[string]string
	AllowedDomains             []string
	AllowedUsers               []string
	StripEmaildomain           bool
}

type PreAuthKey 

type PreAuthKey struct {
	ID          uint64 `gorm:"primary_key"`
	Key         string
	NamespaceID uint
	Namespace   Namespace
	Reusable    bool
	Ephemeral   bool `gorm:"default:false"`
	Used        bool `gorm:"default:false"`
	ACLTags     []PreAuthKeyACLTag

	CreatedAt  *time.Time
	Expiration *time.Time
}

PreAuthKey describes a pre-authorization key usable in a particular namespace.

type PreAuthKeyACLTag added in v0.17.0 

type PreAuthKeyACLTag struct {
	ID           uint64 `gorm:"primary_key"`
	PreAuthKeyID uint64
	Tag          string
}

PreAuthKeyACLTag describes an autmatic tag applied to a node when registered with the associated PreAuthKey.

type StringList added in v0.15.0 

type StringList []string

func (*StringList) Scan added in v0.15.0 

func (i *StringList) Scan(destination interface{}) error

func (StringList) Value added in v0.15.0 

func (i StringList) Value() (driver.Value, error)

Value return json value, implement driver.Valuer interface.

type TLSConfig added in v0.16.0 

type TLSConfig struct {
	CertPath string
	KeyPath  string

	LetsEncrypt LetsEncryptConfig
}

func GetTLSConfig added in v0.16.0 

func GetTLSConfig() TLSConfig

type TagOwners added in v0.3.0 

type TagOwners map[string][]string

TagOwners specify what users (namespaces?) are allow to use certain tags.

type WindowsRegistryConfig added in v0.15.0 

type WindowsRegistryConfig struct {
	URL string
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
headscale
headscale/cli
gen
go/headscale/v1
Package v1 is a reverse proxy.
 Package v1 is a reverse proxy.
dockertestutil
hsic
integrationutil
tsic

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.