headscale

package module
v0.22.0-alpha2 Latest Latest
Warning

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

 Go to latest Published: Apr 8, 2023 License: BSD-3-Clause Imports: 84 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 Yes docs

Running headscale

Please have a look at the documentation under docs/.

Graphical Control Panels

Headscale provides an API for complete management of your Tailnet. These are community projects not directly affiliated with the Headscale project.

Name Repository Link Description Status
headscale-webui Github A simple Headscale web UI for small-scale deployments. Alpha

Talks

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 		Ward
Ward Vandewege 		Jiang
Jiang Zhu 		Benjamin
Benjamin Roberts 		Nico/
Nico
Even
Even Holthe 		e-zk/
e-zk 		Justin
Justin Angel 		Alessandro
Alessandro (Ale) Segala 		unreality/
unreality 		Moritz
Moritz Poldrack
ohdearaugustin/
ohdearaugustin 		Adrien
Adrien Raffin-Caboisse 		GrigoriyMikhalkin/
GrigoriyMikhalkin 		Christian
Christian Heusel 		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
Stefan
Stefan Majer 		Fernando
Fernando De Lucchi 		Orville
Orville Q. Song 		hdhoang/
hdhoang 		bravechamp/
bravechamp 		bravechamp/
bravechamp
Deon
Deon Thomas 		Jamie
Jamie Greeff 		ChibangLW/
ChibangLW 		Mevan
Mevan Samaratunga 		Michael
Michael G. 		Paul
Paul Tötterman
Samuel
Samuel Lock 		kevinlin/
kevinlin 		Snack/
Snack 		Artem
Artem Klevtsov 		Casey
Casey Marshall 		dbevacqua/
dbevacqua
Josh
Josh Taylor 		LiuHanCheng/
LiuHanCheng 		Motiejus
Motiejus Jakštys 		Pavlos
Pavlos Vinieratos 		Silver
Silver Bullet 		Steven
Steven Honson
Victor
Victor Freire 		thomas/
thomas 		Sean
Sean Reifschneider 		Abraham
Abraham Ingersoll 		Albert
Albert Copeland 		Andrei
Andrei Pechkurov
Anoop
Anoop Sundaresh 		Antoine
Antoine POPINEAU 		Antonio
Antonio Fernandez 		Aofei
Aofei Sheng 		Arnar/
Arnar 		Avirut
Avirut Mehta
Bryan
Bryan Stenson 		Carson
Carson Yang 		kundel/
kundel 		fatih-acar/
fatih-acar 		Felix
Felix Kronlage-Dammers 		Felix
Felix Yan
Gabe
Gabe Cook 		JJGadgets/
JJGadgets 		hrtkpf/
hrtkpf 		Jim
Jim Tittsler 		Johan
Johan Siebens 		John
John Axel Eriksson
Jonathan
Jonathan de Jong 		Julien
Julien Zweverink 		Kurnia
Kurnia D Win 		Marc/
Marc 		Maxim
Maxim Gajdaj 		Michael
Michael Savage
Pierre
Pierre Carru 		Pontus
Pontus N 		Rasmus
Rasmus Moorats 		rcursaru/
rcursaru 		Mend
Mend Renovate 		Ryan
Ryan Fowler
Shaanan
Shaanan Cohney 		Stefan
Stefan VanBuren 		sophware/
sophware 		Tanner/
Tanner 		Teteros/
Teteros 		Teteros/
Teteros
The
The Gitter Badger 		Tianon
Tianon Gravi 		Till
Till Hoffmann 		Tjerk
Tjerk Woudsma 		Yang
Yang Bin 		Yujie
Yujie Xia
Zachary
Zachary Newell 		Zakhar
Zakhar Bessarab 		Zhiyuan
Zhiyuan Zheng 		Ziyuan
Ziyuan Han 		caelansar/
caelansar 		derelm/
derelm
dnaq/
dnaq 		henning
henning mueller 		ignoramous/
ignoramous 		jimyag/
jimyag 		suhelen/
suhelen 		sharkonet/
sharkonet
ma6174/
ma6174 		manju-rn/
manju-rn 		nicholas-yap/
nicholas-yap 		Tommi
Tommi Pernila 		phpmalik/
phpmalik 		Wakeful-Cloud/
Wakeful-Cloud
zy/
zy 		Àlex
Àlex Torregrosa

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")
	ErrDifferentRegisteredUser         = Error(
		"machine was previously registered with a different user",
	)
	MachineGivenNameHashLength = 8
	MachineGivenNameTrimSize   = 2
)
View Source 
const (
	ErrPreAuthKeyNotFound          = Error("AuthKey not found")
	ErrPreAuthKeyExpired           = Error("AuthKey expired")
	ErrSingleUseAuthKeyHasBeenUsed = Error("AuthKey has already been used")
	ErrUserMismatch                = Error("user mismatch")
	ErrPreAuthKeyACLTagInvalid     = Error("AuthKey tag is invalid")
)
View Source 
const (
	ErrUserExists        = Error("User already exists")
	ErrUserNotFound      = Error("User not found")
	ErrUserStillHasNodes = Error("User not empty: node(s) found")
	ErrInvalidUserName   = Error("Invalid user name")
)
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 (
	ErrCannotParsePrefix = Error("cannot parse prefix")
)
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 user it can also return an error if the user 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"`
	SSHs          []SSH         `json:"ssh"           yaml:"ssh"`
}

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 (users?), 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 users, 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 user, and returns it.

func (*Headscale) CreatePreAuthKey 

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

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

func (*Headscale) CreateUser added in v0.19.0 

func (h *Headscale) CreateUser(name string) (*User, error)

CreateUser creates a new User. Returns error if could not be created or another user already exists.

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) DeleteMachineRoutes added in v0.21.0 

func (h *Headscale) DeleteMachineRoutes(m *Machine) error

func (*Headscale) DeleteRoute added in v0.21.0 

func (h *Headscale) DeleteRoute(id uint64) error

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) 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) DestroyUser added in v0.19.0 

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

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

func (*Headscale) DisableRoute added in v0.18.0 

func (h *Headscale) DisableRoute(id uint64) error

func (*Headscale) EnableAutoApprovedRoutes added in v0.17.0 

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

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

func (*Headscale) EnableRoute added in v0.18.0 

func (h *Headscale) EnableRoute(id uint64) error

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) GetAdvertisedRoutes added in v0.18.0 

func (h *Headscale) GetAdvertisedRoutes(machine *Machine) ([]netip.Prefix, error)

GetAdvertisedRoutes returns the routes that are be advertised by the given machine.

func (*Headscale) GetEnabledRoutes added in v0.18.0 

func (h *Headscale) GetEnabledRoutes(machine *Machine) ([]netip.Prefix, error)

GetEnabledRoutes returns the routes that are enabled for the machine.

func (*Headscale) GetMachine 

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

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

func (*Headscale) GetMachineByAnyKey added in v0.18.0 

func (h *Headscale) GetMachineByAnyKey(
	machineKey key.MachinePublic, nodeKey key.NodePublic, oldNodeKey key.NodePublic,
) (*Machine, error)

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

func (*Headscale) GetMachineByGivenName added in v0.17.0 

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

GetMachineByGivenName finds a Machine by given name and user 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) GetMachineRoutes added in v0.18.0 

func (h *Headscale) GetMachineRoutes(m *Machine) ([]Route, error)

func (*Headscale) GetPreAuthKey added in v0.6.1 

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

GetPreAuthKey returns a PreAuthKey for a given key.

func (*Headscale) GetRoute added in v0.18.0 

func (h *Headscale) GetRoute(id uint64) (*Route, error)

func (*Headscale) GetRoutes added in v0.18.0 

func (h *Headscale) GetRoutes() ([]Route, error)

func (*Headscale) GetUser added in v0.19.0 

func (h *Headscale) GetUser(name string) (*User, error)

GetUser fetches a user by name.

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) IsRoutesEnabled added in v0.18.0 

func (h *Headscale) IsRoutesEnabled(machine *Machine, routeStr string) bool

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 user.

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) ListMachinesByUser added in v0.19.0 

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

ListMachinesByUser gets all the nodes in a given user.

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(userName string) ([]PreAuthKey, error)

ListPreAuthKeys returns the list of PreAuthKeys for a user.

func (*Headscale) ListUsers added in v0.19.0 

func (h *Headscale) ListUsers() ([]User, error)

ListUsers gets all the existing users.

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) 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 user 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,
	userName string,
	machineExpiry *time.Time,
	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) RenameUser added in v0.19.0 

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

RenameUser renames a User. Returns error if the User does not exist or if another User 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) SetMachineUser added in v0.19.0 

func (h *Headscale) SetMachineUser(machine *Machine, username string) error

SetMachineUser assigns a Machine to a user.

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

type IPPrefix netip.Prefix

func (*IPPrefix) Scan added in v0.18.0 

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

func (IPPrefix) Value added in v0.18.0 

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

Value return json value, implement driver.Valuer interface.

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"`
	UserID    uint
	User      User `gorm:"foreignKey:UserID"`

	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

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

Machine is a Headscale client.

func (*Machine) GetHostInfo 

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

GetHostInfo returns a Hostinfo struct for the machine.

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 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
	AllowedGroups              []string
	StripEmaildomain           bool
	Expiry                     time.Duration
	UseExpiryFromToken         bool
}

type PreAuthKey 

type PreAuthKey struct {
	ID        uint64 `gorm:"primary_key"`
	Key       string
	UserID    uint
	User      User
	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 user.

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

type Route struct {
	gorm.Model

	MachineID uint64
	Machine   Machine
	Prefix    IPPrefix

	Advertised bool
	Enabled    bool
	IsPrimary  bool
}

func (*Route) String added in v0.18.0 

func (r *Route) String() string

type Routes added in v0.18.0 

type Routes []Route

type SSH added in v0.17.0 

type SSH struct {
	Action       string   `json:"action"                yaml:"action"`
	Sources      []string `json:"src"                   yaml:"src"`
	Destinations []string `json:"dst"                   yaml:"dst"`
	Users        []string `json:"users"                 yaml:"users"`
	CheckPeriod  string   `json:"checkPeriod,omitempty" yaml:"checkPeriod,omitempty"`
}

SSH controls who can ssh into which machines.

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 (users?) are allow to use certain tags.

type User added in v0.19.0 

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

User 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 users that contain our machines.

type WindowsRegistryConfig added in v0.15.0 

type WindowsRegistryConfig struct {
	URL string
}

Source Files

View all Source files

Directories

Path Synopsis
cmd
gh-action-integration-generator
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.