tailscale

package
v1.76.6 Latest Latest
Warning

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

 Go to latest Published: Nov 4, 2024 License: BSD-3-Clause Imports: 36 Imported by: 170

Documentation

Overview

Package tailscale contains Go clients for the Tailscale LocalAPI and Tailscale control plane API.

Warning: this package is in development and makes no API compatibility promises as of 2022-04-29. It is subject to change at any time.

Index

Constants

This section is empty.

Variables

View Source 
var (
	DeviceAllFields = &DeviceFieldsOpts{}

	// DeviceDefaultFields specifies that the following fields are returned:
	//   Addresses, NodeID, User, Name, Hostname, ClientVersion, UpdateAvailable,
	//   OS, Created, LastSeen, KeyExpiryDisabled, Expires, Authorized, IsExternal
	//   MachineKey, NodeKey, BlocksIncomingConnections.
	DeviceDefaultFields = &DeviceFieldsOpts{}
)
View Source 
var ErrPeerNotFound = errors.New("peer not found")

ErrPeerNotFound is returned by WhoIs and WhoIsNodeKey when a peer is not found.

View Source 
var I_Acknowledge_This_API_Is_Unstable = false

I_Acknowledge_This_API_Is_Unstable must be set true to use this package for now. It was added 2022-04-29 when it was moved to this git repo and will be removed when the public API has settled.

TODO(bradfitz): remove this after the we're happy with the public API.

Functions

func CertPair deprecated added in v1.14.0 

func CertPair(ctx context.Context, domain string) (certPEM, keyPEM []byte, err error)

CertPair returns a cert and private key for the provided DNS domain.

It returns a cached certificate from disk if it's still valid.

Deprecated: use LocalClient.CertPair.

func ExpandSNIName deprecated added in v1.14.0 

func ExpandSNIName(ctx context.Context, name string) (fqdn string, ok bool)

ExpandSNIName expands bare label name into the most likely actual TLS cert name.

Deprecated: use LocalClient.ExpandSNIName.

func GetCertificate deprecated added in v1.14.0 

func GetCertificate(hi *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate fetches a TLS certificate for the TLS ClientHello in hi.

It returns a cached certificate from disk if it's still valid.

It's the right signature to use as the value of tls.Config.GetCertificate.

Deprecated: use LocalClient.GetCertificate.

func IsAccessDeniedError added in v1.14.6 

func IsAccessDeniedError(err error) bool

IsAccessDeniedError reports whether err is or wraps an AccessDeniedError.

func IsPreconditionsFailedError added in v1.50.0 

func IsPreconditionsFailedError(err error) bool

IsPreconditionsFailedError reports whether err is or wraps an PreconditionsFailedError.

func SetVersionMismatchHandler added in v1.16.0 

func SetVersionMismatchHandler(f func(clientVer, serverVer string))

SetVersionMismatchHandler sets f as the version mismatch handler to be called when the client (the current process) has a version number that doesn't match the server's declared version.

func Status added in v1.8.0 

func Status(ctx context.Context) (*ipnstate.Status, error)

Status returns the Tailscale daemon's status.

func StatusWithoutPeers added in v1.8.0 

func StatusWithoutPeers(ctx context.Context) (*ipnstate.Status, error)

StatusWithoutPeers returns the Tailscale daemon's status, without the peer info.

func WhoIs deprecated 

func WhoIs(ctx context.Context, remoteAddr string) (*apitype.WhoIsResponse, error)

WhoIs returns the owner of the remoteAddr, which must be an IP or IP:port.

Deprecated: use LocalClient.WhoIs.

Types

type ACL added in v1.26.0 

type ACL struct {
	ACL  ACLDetails
	ETag string // to check with version on server
}

ACL contains an ACLDetails and metadata.

type ACLDetails added in v1.26.0 

type ACLDetails struct {
	Tests     []ACLTest           `json:"tests,omitempty"`
	ACLs      []ACLRow            `json:"acls,omitempty"`
	Groups    map[string][]string `json:"groups,omitempty"`
	TagOwners map[string][]string `json:"tagowners,omitempty"`
	Hosts     map[string]string   `json:"hosts,omitempty"`
	NodeAttrs []NodeAttrGrant     `json:"nodeAttrs,omitempty"`
}

ACLDetails contains all the details for an ACL.

type ACLHuJSON added in v1.26.0 

type ACLHuJSON struct {
	ACL      string
	Warnings []string
	ETag     string // to check with version on server
}

ACLHuJSON contains the HuJSON string of the ACL and metadata.

type ACLPreview added in v1.26.0 

type ACLPreview struct {
	Matches []UserRuleMatch `json:"matches"`
	User    string          `json:"user,omitempty"`   // Filled if response of PreviewACLForUser or PreviewACLHuJSONForUser
	IPPort  string          `json:"ipport,omitempty"` // Filled if response of PreviewACLForIPPort or PreviewACLHuJSONForIPPort

	// Postures is a map of postures and associated rules that apply
	// to this preview.
	// For more details about the posture mapping, see:
	// https://tailscale.com/kb/1288/device-posture#postures
	Postures map[string][]string `json:"postures,omitempty"`
}

ACLPreview is the response type of PreviewACLForUser, PreviewACLForIPPort, PreviewACLHuJSONForUser, and PreviewACLHuJSONForIPPort

type ACLPreviewResponse added in v1.26.0 

type ACLPreviewResponse struct {
	Matches    []UserRuleMatch `json:"matches"`    // ACL rules that match the specified user or ipport.
	Type       string          `json:"type"`       // The request type: currently only "user" or "ipport".
	PreviewFor string          `json:"previewFor"` // A specific user or ipport.

	// Postures is a map of postures and associated rules that apply
	// to this preview.
	// For more details about the posture mapping, see:
	// https://tailscale.com/kb/1288/device-posture#postures
	Postures map[string][]string `json:"postures,omitempty"`
}

ACLPreviewResponse is the response type of previewACLPostRequest

type ACLRow added in v1.26.0 

type ACLRow struct {
	Action string   `json:"action,omitempty"` // valid values: "accept"
	Proto  string   `json:"proto,omitempty"`  // protocol
	Users  []string `json:"users,omitempty"`  // old name for src
	Ports  []string `json:"ports,omitempty"`  // old name for dst
	Src    []string `json:"src,omitempty"`
	Dst    []string `json:"dst,omitempty"`
}

ACLRow defines a rule that grants access by a set of users or groups to a set of servers and ports. Only one of Src/Dst or Users/Ports may be specified.

type ACLTest added in v1.26.0 

type ACLTest struct {
	Src    string   `json:"src,omitempty"`    // source
	User   string   `json:"user,omitempty"`   // old name for source
	Proto  string   `json:"proto,omitempty"`  // protocol
	Accept []string `json:"accept,omitempty"` // expected destination ip:port that user can access
	Deny   []string `json:"deny,omitempty"`   // expected destination ip:port that user cannot access

	Allow []string `json:"allow,omitempty"` // old name for accept
}

ACLTest defines a test for your ACLs to prevent accidental exposure or revoking of access to key servers and ports. Only one of Src or User may be specified, and only one of Allow/Accept may be specified.

type ACLTestError added in v1.26.0 

type ACLTestError struct {
	ErrResponse
	Data []ACLTestFailureSummary `json:"data"`
}

ACLTestError is ErrResponse but with an extra field to account for ACLTestFailureSummary.

func (ACLTestError) Error added in v1.26.0 

func (e ACLTestError) Error() string

type ACLTestFailureSummary added in v1.26.0 

type ACLTestFailureSummary struct {
	// User is the source ("src") value of the ACL test that failed.
	// The name "user" is a legacy holdover from the original naming and
	// is kept for compatibility but it may also contain any value
	// that's valid in a ACL test "src" field.
	User string `json:"user,omitempty"`

	Errors   []string `json:"errors,omitempty"`
	Warnings []string `json:"warnings,omitempty"`
}

ACLTestFailureSummary specifies a user for which ACL tests failed and the related user-friendly error messages.

ACLTestFailureSummary specifies the JSON format sent to the JavaScript client to be rendered in the HTML.

type APIKey added in v1.26.0 

type APIKey string

APIKey is an AuthMethod for NewClient that authenticates requests using an authkey.

type AccessDeniedError added in v1.14.6 

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

AccessDeniedError is an error due to permissions.

func (*AccessDeniedError) Error added in v1.14.6 

func (e *AccessDeniedError) Error() string

func (*AccessDeniedError) Unwrap added in v1.14.6 

func (e *AccessDeniedError) Unwrap() error

type AuthMethod added in v1.26.0 

type AuthMethod interface {
	// contains filtered or unexported methods
}

AuthMethod is the interface for API authentication methods.

Most users will use AuthKey.

type BugReportOpts added in v1.32.0 

type BugReportOpts struct {
	// Note contains an optional user-provided note to add to the logs.
	Note string

	// Diagnose specifies whether to print additional diagnostic information to
	// the logs when generating this bugreport.
	Diagnose bool

	// Record specifies, if non-nil, whether to perform a bugreport
	// "recording"–generating an initial log marker, then waiting for
	// this channel to be closed before finishing the request, which
	// generates another log marker.
	Record <-chan struct{}
}

BugReportOpts contains options to pass to the Tailscale daemon when generating a bug report.

type Client added in v1.26.0 

type Client struct {

	// BaseURL optionally specifies an alternate API server to use.
	// If empty, "https://api.tailscale.com" is used.
	BaseURL string

	// HTTPClient optionally specifies an alternate HTTP client to use.
	// If nil, http.DefaultClient is used.
	HTTPClient *http.Client
	// contains filtered or unexported fields
}

Client makes API calls to the Tailscale control plane API server.

Use NewClient to instantiate one. Exported fields should be set before the client is used and not changed thereafter.

func NewClient added in v1.26.0 

func NewClient(tailnet string, auth AuthMethod) *Client

NewClient is a convenience method for instantiating a new Client.

tailnet is the globally unique identifier for a Tailscale network, such as "example.com" or "user@gmail.com". If httpClient is nil, then http.DefaultClient is used. "api.tailscale.com" is set as the BaseURL for the returned client and can be changed manually by the user.

func (*Client) ACL added in v1.26.0 

func (c *Client) ACL(ctx context.Context) (acl *ACL, err error)

ACL makes a call to the Tailscale server to get a JSON-parsed version of the ACL. The JSON-parsed version of the ACL contains no comments as proper JSON does not support comments.

func (*Client) ACLHuJSON added in v1.26.0 

func (c *Client) ACLHuJSON(ctx context.Context) (acl *ACLHuJSON, err error)

ACLHuJSON makes a call to the Tailscale server to get the ACL HuJSON and returns it as a string. HuJSON is JSON with a few modifications to make it more human-friendly. The primary changes are allowing comments and trailing comments. See the following links for more info: https://tailscale.com/s/acl-format https://github.com/tailscale/hujson

func (*Client) AuthorizeDevice added in v1.26.0 

func (c *Client) AuthorizeDevice(ctx context.Context, deviceID string) error

AuthorizeDevice marks a device as authorized.

func (*Client) CreateKey added in v1.36.0 

func (c *Client) CreateKey(ctx context.Context, caps KeyCapabilities) (keySecret string, keyMeta *Key, _ error)

CreateKey creates a new key for the current user. Currently, only auth keys can be created. It returns the secret key itself, which cannot be retrieved again later, and the key metadata.

To create a key with a specific expiry, use CreateKeyWithExpiry.

func (*Client) CreateKeyWithExpiry added in v1.42.0 

func (c *Client) CreateKeyWithExpiry(ctx context.Context, caps KeyCapabilities, expiry time.Duration) (keySecret string, keyMeta *Key, _ error)

CreateKeyWithExpiry is like CreateKey, but allows specifying a expiration time.

The time is truncated to a whole number of seconds. If zero, that means no expiration.

func (*Client) DNSConfig added in v1.26.0 

func (c *Client) DNSConfig(ctx context.Context) (cfg *apitype.DNSConfig, err error)

DNSConfig retrieves the DNSConfig settings for a domain.

func (*Client) DNSPreferences added in v1.26.0 

func (c *Client) DNSPreferences(ctx context.Context) (dnsResp *DNSPreferences, err error)

DNSPreferences retrieves the DNS preferences set for a tailnet.

It returns the status of MagicDNS.

func (*Client) DeleteDevice added in v1.26.0 

func (c *Client) DeleteDevice(ctx context.Context, deviceID string) (err error)

DeleteDevice deletes the specified device from the Client's tailnet. NOTE: Only devices that belong to the Client's tailnet can be deleted. Deleting external devices is not supported.

func (*Client) DeleteKey added in v1.36.0 

func (c *Client) DeleteKey(ctx context.Context, id string) error

DeleteKey deletes the key with the given ID.

func (*Client) Device added in v1.26.0 

func (c *Client) Device(ctx context.Context, deviceID string, fields *DeviceFieldsOpts) (device *Device, err error)

Device retrieved the details for a specific device.

See the Device structure for the list of fields hidden for an external device. The optional fields parameter specifies which fields of the devices to return; currently only DeviceDefaultFields (equivalent to nil) and DeviceAllFields are supported. Other values are currently undefined.

func (*Client) Devices added in v1.26.0 

func (c *Client) Devices(ctx context.Context, fields *DeviceFieldsOpts) (deviceList []*Device, err error)

Devices retrieves the list of devices for a tailnet.

See the Device structure for the list of fields hidden for external devices. The optional fields parameter specifies which fields of the devices to return; currently only DeviceDefaultFields (equivalent to nil) and DeviceAllFields are supported. Other values are currently undefined.

func (*Client) Do added in v1.26.0 

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do sends a raw HTTP request, after adding any authentication headers.

func (*Client) Key added in v1.36.0 

func (c *Client) Key(ctx context.Context, id string) (*Key, error)

Key returns the metadata for the given key ID. Currently, capabilities are only returned for auth keys, API keys only return general metadata.

func (*Client) Keys added in v1.36.0 

func (c *Client) Keys(ctx context.Context) ([]string, error)

Keys returns the list of keys for the current user.

func (*Client) NameServers added in v1.26.0 

func (c *Client) NameServers(ctx context.Context) (nameservers []string, err error)

NameServers retrieves the list of nameservers set for a domain.

func (*Client) PreviewACLForIPPort added in v1.26.0 

func (c *Client) PreviewACLForIPPort(ctx context.Context, acl ACL, ipport netip.AddrPort) (res *ACLPreview, err error)

PreviewACLForIPPort determines what rules match a given ACL for a ipport. The ACL can be a locally modified or clean ACL obtained from server.

Returns ACLPreview on success with matches in a slice. If there are no matches, the call is still successful but Matches will be an empty slice. Returns error if the provided ACL is invalid.

func (*Client) PreviewACLForUser added in v1.26.0 

func (c *Client) PreviewACLForUser(ctx context.Context, acl ACL, user string) (res *ACLPreview, err error)

PreviewACLForUser determines what rules match a given ACL for a user. The ACL can be a locally modified or clean ACL obtained from server.

Returns ACLPreview on success with matches in a slice. If there are no matches, the call is still successful but Matches will be an empty slice. Returns error if the provided ACL is invalid.

func (*Client) PreviewACLHuJSONForIPPort added in v1.26.0 

func (c *Client) PreviewACLHuJSONForIPPort(ctx context.Context, acl ACLHuJSON, ipport string) (res *ACLPreview, err error)

PreviewACLHuJSONForIPPort determines what rules match a given ACL for a ipport. The ACL can be a locally modified or clean ACL obtained from server.

Returns ACLPreview on success with matches in a slice. If there are no matches, the call is still successful but Matches will be an empty slice. Returns error if the provided ACL is invalid.

func (*Client) PreviewACLHuJSONForUser added in v1.26.0 

func (c *Client) PreviewACLHuJSONForUser(ctx context.Context, acl ACLHuJSON, user string) (res *ACLPreview, err error)

PreviewACLHuJSONForUser determines what rules match a given ACL for a user. The ACL can be a locally modified or clean ACL obtained from server.

Returns ACLPreview on success with matches in a slice. If there are no matches, the call is still successful but Matches will be an empty slice. Returns error if the provided ACL is invalid.

func (*Client) Routes added in v1.26.0 

func (c *Client) Routes(ctx context.Context, deviceID string) (routes *Routes, err error)

Routes retrieves the list of subnet routes that have been enabled for a device. The routes that are returned are not necessarily advertised by the device, they have only been preapproved.

func (*Client) SearchPaths added in v1.26.0 

func (c *Client) SearchPaths(ctx context.Context) (searchpaths []string, err error)

SearchPaths retrieves the list of searchpaths set for a tailnet.

func (*Client) SetACL added in v1.26.0 

func (c *Client) SetACL(ctx context.Context, acl ACL, avoidCollisions bool) (res *ACL, err error)

SetACL sends a POST request to update the ACL according to the provided ACL object. If `avoidCollisions` is true, it will use the ETag obtained in the GET request in an If-Match header to check if the previously obtained ACL was the latest version and that no updates were missed.

Returns error with status code 412 if mistmached ETag and avoidCollisions is set to true. Returns error if ACL has tests that fail. Returns error if there are other errors with the ACL.

func (*Client) SetACLHuJSON added in v1.26.0 

func (c *Client) SetACLHuJSON(ctx context.Context, acl ACLHuJSON, avoidCollisions bool) (res *ACLHuJSON, err error)

SetACLHuJSON sends a POST request to update the ACL according to the provided ACL object. If `avoidCollisions` is true, it will use the ETag obtained in the GET request in an If-Match header to check if the previously obtained ACL was the latest version and that no updates were missed.

Returns error with status code 412 if mistmached ETag and avoidCollisions is set to true. Returns error if the HuJSON is invalid. Returns error if ACL has tests that fail. Returns error if there are other errors with the ACL.

func (*Client) SetAuthorized added in v1.44.0 

func (c *Client) SetAuthorized(ctx context.Context, deviceID string, authorized bool) error

SetAuthorized marks a device as authorized or not.

func (*Client) SetDNSConfig added in v1.26.0 

func (c *Client) SetDNSConfig(ctx context.Context, cfg apitype.DNSConfig) (resp *apitype.DNSConfig, err error)

func (*Client) SetDNSPreferences added in v1.26.0 

func (c *Client) SetDNSPreferences(ctx context.Context, magicDNS bool) (dnsResp *DNSPreferences, err error)

SetDNSPreferences sets the DNS preferences for a tailnet.

MagicDNS can only be enabled when there is at least one nameserver provided. When all nameservers are removed, MagicDNS is disabled and will stay disabled, unless explicitly enabled by a user again.

func (*Client) SetNameServers added in v1.26.0 

func (c *Client) SetNameServers(ctx context.Context, nameservers []string) (dnsResp *DNSNameServersPostResponse, err error)

SetNameServers sets the list of nameservers for a tailnet to the list provided by the user.

It returns the new list of nameservers and the MagicDNS status in case it was affected by the change. For example, removing all nameservers will turn off MagicDNS.

func (*Client) SetRoutes added in v1.26.0 

func (c *Client) SetRoutes(ctx context.Context, deviceID string, subnets []netip.Prefix) (routes *Routes, err error)

SetRoutes updates the list of subnets that are enabled for a device. Subnets must be parsable by net/netip.ParsePrefix. Subnets do not have to be currently advertised by a device, they may be pre-enabled. Returns the updated list of enabled and advertised subnet routes in a *Routes object.

func (*Client) SetSearchPaths added in v1.26.0 

func (c *Client) SetSearchPaths(ctx context.Context, searchpaths []string) (newSearchPaths []string, err error)

SetSearchPaths sets the list of searchpaths for a tailnet.

func (*Client) SetTags added in v1.26.0 

func (c *Client) SetTags(ctx context.Context, deviceID string, tags []string) error

SetTags updates the ACL tags on a device.

func (*Client) Tailnet added in v1.26.0 

func (c *Client) Tailnet() string

func (*Client) TailnetDeleteRequest added in v1.26.0 

func (c *Client) TailnetDeleteRequest(ctx context.Context, tailnetID string) (err error)

TailnetDeleteRequest handles sending a DELETE request for a tailnet to control.

func (*Client) ValidateACLJSON added in v1.26.0 

func (c *Client) ValidateACLJSON(ctx context.Context, source, dest string) (testErr *ACLTestError, err error)

ValidateACLJSON takes in the given source and destination (in this situation, it is assumed that you are checking whether the source can connect to destination) and creates an ACLTest from that. It then sends the ACLTest to the control api acl validate endpoint, where the test is run. It returns a nil ACLTestError pointer if no test errors occur.

type ClientConnectivity added in v1.26.0 

type ClientConnectivity struct {
	Endpoints             []string `json:"endpoints"`
	DERP                  string   `json:"derp"`
	MappingVariesByDestIP opt.Bool `json:"mappingVariesByDestIP"`
	// DERPLatency is mapped by region name (e.g. "New York City", "Seattle").
	DERPLatency    map[string]DerpRegion `json:"latency"`
	ClientSupports map[string]opt.Bool   `json:"clientSupports"`
}

type DNSNameServers added in v1.26.0 

type DNSNameServers struct {
	DNS []string `json:"dns"` // DNS name servers
}

DNSNameServers is returned when retrieving the list of nameservers. It is also the structure provided when setting nameservers.

type DNSNameServersPostResponse added in v1.26.0 

type DNSNameServersPostResponse struct {
	DNS      []string `json:"dns"`      // DNS name servers
	MagicDNS bool     `json:"magicDNS"` // whether MagicDNS is active for this tailnet (enabled + has fallback nameservers)
}

DNSNameServersPostResponse is returned when setting the list of DNS nameservers.

It includes the MagicDNS status since nameservers changes may affect MagicDNS.

type DNSPreferences added in v1.26.0 

type DNSPreferences struct {
	MagicDNS bool `json:"magicDNS"` // whether MagicDNS is active for this tailnet (enabled + has fallback nameservers)
}

DNSPreferences is the preferences set for a given tailnet.

It includes MagicDNS which can be turned on or off. To enable MagicDNS, there must be at least one nameserver. When all nameservers are removed, MagicDNS is disabled.

type DNSSearchPaths added in v1.26.0 

type DNSSearchPaths struct {
	SearchPaths []string `json:"searchPaths"` // DNS search paths
}

DNSSearchpaths is the list of search paths for a given domain.

type DebugPortmapOpts added in v1.50.0 

type DebugPortmapOpts struct {
	// Duration is how long the mapping should be created for. It defaults
	// to 5 seconds if not set.
	Duration time.Duration

	// Type is the kind of portmap to debug. The empty string instructs the
	// portmap client to perform all known types. Other valid options are
	// "pmp", "pcp", and "upnp".
	Type string

	// GatewayAddr specifies the gateway address used during portmapping.
	// If set, SelfAddr must also be set. If unset, it will be
	// autodetected.
	GatewayAddr netip.Addr

	// SelfAddr specifies the gateway address used during portmapping. If
	// set, GatewayAddr must also be set. If unset, it will be
	// autodetected.
	SelfAddr netip.Addr

	// LogHTTP instructs the debug-portmap endpoint to print all HTTP
	// requests and responses made to the logs.
	LogHTTP bool
}

DebugPortmapOpts contains options for the DebugPortmap command.

type DerpRegion added in v1.26.0 

type DerpRegion struct {
	Preferred           bool    `json:"preferred,omitempty"`
	LatencyMilliseconds float64 `json:"latencyMs"`
}

type Device added in v1.26.0 

type Device struct {
	// Addresses is a list of the devices's Tailscale IP addresses.
	// It's currently just 1 element, the 100.x.y.z Tailscale IP.
	Addresses []string `json:"addresses"`
	DeviceID  string   `json:"id"`
	NodeID    string   `json:"nodeId"`
	User      string   `json:"user"`
	Name      string   `json:"name"`
	Hostname  string   `json:"hostname"`

	ClientVersion     string   `json:"clientVersion"`   // Empty for external devices.
	UpdateAvailable   bool     `json:"updateAvailable"` // Empty for external devices.
	OS                string   `json:"os"`
	Tags              []string `json:"tags"`
	Created           string   `json:"created"` // Empty for external devices.
	LastSeen          string   `json:"lastSeen"`
	KeyExpiryDisabled bool     `json:"keyExpiryDisabled"`
	Expires           string   `json:"expires"`
	Authorized        bool     `json:"authorized"`
	IsExternal        bool     `json:"isExternal"`
	MachineKey        string   `json:"machineKey"` // Empty for external devices.
	NodeKey           string   `json:"nodeKey"`

	// BlocksIncomingConnections is configured via the device's
	// Tailscale client preferences. This field is only reported
	// to the API starting with Tailscale 1.3.x clients.
	BlocksIncomingConnections bool `json:"blocksIncomingConnections"`

	// EnabledRoutes are the previously-approved subnet routes
	// (e.g. "192.168.4.16/24", "10.5.2.4/32").
	EnabledRoutes []string `json:"enabledRoutes"` // Empty for external devices.
	// AdvertisedRoutes are the subnets (both enabled and not enabled)
	// being requested from the node.
	AdvertisedRoutes []string `json:"advertisedRoutes"` // Empty for external devices.

	ClientConnectivity *ClientConnectivity `json:"clientConnectivity"`

	// PostureIdentity contains extra identifiers collected from the device when
	// the tailnet has the device posture identification features enabled. If
	// Tailscale have attempted to collect this from the device but it has not
	// opted in, PostureIdentity will have Disabled=true.
	PostureIdentity *DevicePostureIdentity `json:"postureIdentity"`
}

type DeviceFieldsOpts added in v1.26.0 

type DeviceFieldsOpts Device

DeviceFieldsOpts determines which fields should be returned in the response.

Please only use DeviceAllFields and DeviceDefaultFields. Other DeviceFieldsOpts are not supported.

TODO: Support other DeviceFieldsOpts. In the future, users should be able to create their own DeviceFieldsOpts as valid arguments by setting the fields they want returned to a "non-nil" value. For example, DeviceFieldsOpts{NodeID: "true"} should only return NodeIDs.

type DevicePostureIdentity added in v1.58.0 

type DevicePostureIdentity struct {
	Disabled      bool     `json:"disabled,omitempty"`
	SerialNumbers []string `json:"serialNumbers,omitempty"`
}

type ErrResponse added in v1.26.0 

type ErrResponse struct {
	Status  int
	Message string
}

ErrResponse is the HTTP error returned by the Tailscale server.

func (ErrResponse) Error added in v1.26.0 

func (e ErrResponse) Error() string

type GetDevicesResponse added in v1.26.0 

type GetDevicesResponse struct {
	Devices []*Device `json:"devices"`
}

type IPNBusWatcher added in v1.34.0 

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

IPNBusWatcher is an active subscription (watch) of the local tailscaled IPN bus. It's returned by LocalClient.WatchIPNBus.

It must be closed when done.

func (*IPNBusWatcher) Close added in v1.34.0 

func (w *IPNBusWatcher) Close() error

Close stops the watcher and releases its resources.

func (*IPNBusWatcher) Next added in v1.34.0 

func (w *IPNBusWatcher) Next() (ipn.Notify, error)

Next returns the next ipn.Notify from the stream. If the context from LocalClient.WatchIPNBus is done, that error is returned.

type Key added in v1.36.0 

type Key struct {
	ID           string          `json:"id"`
	Created      time.Time       `json:"created"`
	Expires      time.Time       `json:"expires"`
	Capabilities KeyCapabilities `json:"capabilities"`
}

Key represents a Tailscale API or auth key.

type KeyCapabilities added in v1.36.0 

type KeyCapabilities struct {
	Devices KeyDeviceCapabilities `json:"devices,omitempty"`
}

KeyCapabilities are the capabilities of a Key.

type KeyDeviceCapabilities added in v1.36.0 

type KeyDeviceCapabilities struct {
	Create KeyDeviceCreateCapabilities `json:"create"`
}

KeyDeviceCapabilities are the device-related capabilities of a Key.

type KeyDeviceCreateCapabilities added in v1.36.0 

type KeyDeviceCreateCapabilities struct {
	Reusable      bool     `json:"reusable"`
	Ephemeral     bool     `json:"ephemeral"`
	Preauthorized bool     `json:"preauthorized"`
	Tags          []string `json:"tags,omitempty"`
}

KeyDeviceCreateCapabilities are the device creation capabilities of a Key.

type LocalClient added in v1.26.0 

type LocalClient struct {
	// Dial optionally specifies an alternate func that connects to the local
	// machine's tailscaled or equivalent. If nil, a default is used.
	Dial func(ctx context.Context, network, addr string) (net.Conn, error)

	// Socket specifies an alternate path to the local Tailscale socket.
	// If empty, a platform-specific default is used.
	Socket string

	// UseSocketOnly, if true, tries to only connect to tailscaled via the
	// Unix socket and not via fallback mechanisms as done on macOS when
	// connecting to the GUI client variants.
	UseSocketOnly bool

	// OmitAuth, if true, omits sending the local Tailscale daemon any
	// authentication token that might be required by the platform.
	//
	// As of 2024-08-12, only macOS uses an authentication token. OmitAuth is
	// meant for when Dial is set and the LocalAPI is being proxied to a
	// different operating system, such as in integration tests.
	OmitAuth bool
	// contains filtered or unexported fields
}

LocalClient is a client to Tailscale's "LocalAPI", communicating with the Tailscale daemon on the local machine. Its API is not necessarily stable and subject to changes between releases. Some API calls have stricter compatibility guarantees, once they've been widely adopted. See method docs for details.

Its zero value is valid to use.

Any exported fields should be set before using methods on the type and not changed thereafter.

func (*LocalClient) AwaitWaitingFiles added in v1.34.0 

func (lc *LocalClient) AwaitWaitingFiles(ctx context.Context, d time.Duration) ([]apitype.WaitingFile, error)

AwaitWaitingFiles is like WaitingFiles but takes a duration to await for an answer. If the duration is 0, it will return immediately. The duration is respected at second granularity only. If no files are available, it returns (nil, nil).

func (*LocalClient) BugReport added in v1.26.0 

func (lc *LocalClient) BugReport(ctx context.Context, note string) (string, error)

BugReport logs and returns a log marker that can be shared by the user with support.

This is the same as calling BugReportWithOpts and only specifying the Note field.

func (*LocalClient) BugReportWithOpts added in v1.32.0 

func (lc *LocalClient) BugReportWithOpts(ctx context.Context, opts BugReportOpts) (string, error)

BugReportWithOpts logs and returns a log marker that can be shared by the user with support.

The opts type specifies options to pass to the Tailscale daemon when generating this bug report.

func (*LocalClient) CertPair added in v1.26.0 

func (lc *LocalClient) CertPair(ctx context.Context, domain string) (certPEM, keyPEM []byte, err error)

CertPair returns a cert and private key for the provided DNS domain.

It returns a cached certificate from disk if it's still valid.

API maturity: this is considered a stable API.

func (*LocalClient) CertPairWithValidity added in v1.72.0 

func (lc *LocalClient) CertPairWithValidity(ctx context.Context, domain string, minValidity time.Duration) (certPEM, keyPEM []byte, err error)

CertPairWithValidity returns a cert and private key for the provided DNS domain.

It returns a cached certificate from disk if it's still valid. When minValidity is non-zero, the returned certificate will be valid for at least the given duration, if permitted by the CA. If the certificate is valid, but for less than minValidity, it will be synchronously renewed.

API maturity: this is considered a stable API.

func (*LocalClient) CheckIPForwarding added in v1.26.0 

func (lc *LocalClient) CheckIPForwarding(ctx context.Context) error

CheckIPForwarding asks the local Tailscale daemon whether it looks like the machine is properly configured to forward IP packets as a subnet router or exit node.

func (*LocalClient) CheckPrefs added in v1.26.0 

func (lc *LocalClient) CheckPrefs(ctx context.Context, p *ipn.Prefs) error

CheckPrefs validates the provided preferences, without making any changes.

The CLI uses this before a Start call to fail fast if the preferences won't work. Currently (2022-04-18) this only checks for SSH server compatibility. Note that EditPrefs does the same validation as this, so call CheckPrefs before EditPrefs is not necessary.

func (*LocalClient) CheckUDPGROForwarding added in v1.54.0 

func (lc *LocalClient) CheckUDPGROForwarding(ctx context.Context) error

CheckUDPGROForwarding asks the local Tailscale daemon whether it looks like the machine is optimally configured to forward UDP packets as a subnet router or exit node.

func (*LocalClient) CheckUpdate added in v1.56.0 

func (lc *LocalClient) CheckUpdate(ctx context.Context) (*tailcfg.ClientVersion, error)

CheckUpdate returns a tailcfg.ClientVersion indicating whether or not an update is available to be installed via the LocalAPI. In case the LocalAPI can't install updates, it returns a ClientVersion that says that we are up to date.

func (*LocalClient) CurrentDERPMap added in v1.26.0 

func (lc *LocalClient) CurrentDERPMap(ctx context.Context) (*tailcfg.DERPMap, error)

CurrentDERPMap returns the current DERPMap that is being used by the local tailscaled. It is intended to be used with netcheck to see availability of DERPs.

func (*LocalClient) DaemonMetrics added in v1.26.0 

func (lc *LocalClient) DaemonMetrics(ctx context.Context) ([]byte, error)

DaemonMetrics returns the Tailscale daemon's metrics in the Prometheus text exposition format.

func (*LocalClient) DebugAction added in v1.26.0 

func (lc *LocalClient) DebugAction(ctx context.Context, action string) error

DebugAction invokes a debug action, such as "rebind" or "restun". These are development tools and subject to change or removal over time.

func (*LocalClient) DebugDERPRegion added in v1.34.0 

func (lc *LocalClient) DebugDERPRegion(ctx context.Context, regionIDOrCode string) (*ipnstate.DebugDERPRegionReport, error)

func (*LocalClient) DebugPacketFilterRules added in v1.56.0 

func (lc *LocalClient) DebugPacketFilterRules(ctx context.Context) ([]tailcfg.FilterRule, error)

DebugPacketFilterRules returns the packet filter rules for the current device.

func (*LocalClient) DebugPortmap added in v1.38.0 

func (lc *LocalClient) DebugPortmap(ctx context.Context, opts *DebugPortmapOpts) (io.ReadCloser, error)

DebugPortmap invokes the debug-portmap endpoint, and returns an io.ReadCloser that can be used to read the logs that are printed during this process.

opts can be nil; if so, default values will be used.

func (*LocalClient) DebugResultJSON added in v1.50.0 

func (lc *LocalClient) DebugResultJSON(ctx context.Context, action string) (any, error)

DebugResultJSON invokes a debug action and returns its result as something JSON-able. These are development tools and subject to change or removal over time.

func (*LocalClient) DebugSetExpireIn added in v1.36.0 

func (lc *LocalClient) DebugSetExpireIn(ctx context.Context, d time.Duration) error

DebugSetExpireIn marks the current node key to expire in d.

This is meant primarily for debug and testing.

func (*LocalClient) DeleteProfile added in v1.34.0 

func (lc *LocalClient) DeleteProfile(ctx context.Context, profile ipn.ProfileID) error

DeleteProfile removes the profile with the given ID. If the profile is the current profile, an empty profile will be selected as if SwitchToEmptyProfile was called.

func (*LocalClient) DeleteWaitingFile added in v1.26.0 

func (lc *LocalClient) DeleteWaitingFile(ctx context.Context, baseName string) error

func (*LocalClient) DialTCP added in v1.26.0 

func (lc *LocalClient) DialTCP(ctx context.Context, host string, port uint16) (net.Conn, error)

DialTCP connects to the host's port via Tailscale.

The host may be a base DNS name (resolved from the netmap inside tailscaled), a FQDN, or an IP address.

The ctx is only used for the duration of the call, not the lifetime of the net.Conn.

func (*LocalClient) DoLocalRequest added in v1.26.0 

func (lc *LocalClient) DoLocalRequest(req *http.Request) (*http.Response, error)

DoLocalRequest makes an HTTP request to the local machine's Tailscale daemon.

URLs are of the form http://local-tailscaled.sock/localapi/v0/whois?ip=1.2.3.4.

The hostname must be "local-tailscaled.sock", even though it doesn't actually do any DNS lookup. The actual means of connecting to and authenticating to the local Tailscale daemon vary by platform.

DoLocalRequest may mutate the request to add Authorization headers.

func (*LocalClient) DriveSetServerAddr added in v1.64.0 

func (lc *LocalClient) DriveSetServerAddr(ctx context.Context, addr string) error

DriveSetServerAddr instructs Taildrive to use the server at addr to access the filesystem. This is used on platforms like Windows and MacOS to let Taildrive know to use the file server running in the GUI app.

func (*LocalClient) DriveShareList added in v1.64.0 

func (lc *LocalClient) DriveShareList(ctx context.Context) ([]*drive.Share, error)

DriveShareList returns the list of shares that drive is currently serving to remote nodes.

func (*LocalClient) DriveShareRemove added in v1.64.0 

func (lc *LocalClient) DriveShareRemove(ctx context.Context, name string) error

DriveShareRemove removes the share with the given name from the list of shares that Taildrive will serve to remote nodes.

func (*LocalClient) DriveShareRename added in v1.64.0 

func (lc *LocalClient) DriveShareRename(ctx context.Context, oldName, newName string) error

DriveShareRename renames the share from old to new name.

func (*LocalClient) DriveShareSet added in v1.64.0 

func (lc *LocalClient) DriveShareSet(ctx context.Context, share *drive.Share) error

DriveShareSet adds or updates the given share in the list of shares that Taildrive will serve to remote nodes. If a share with the same name already exists, the existing share is replaced/updated.

func (*LocalClient) EditPrefs added in v1.26.0 

func (lc *LocalClient) EditPrefs(ctx context.Context, mp *ipn.MaskedPrefs) (*ipn.Prefs, error)

func (*LocalClient) ExpandSNIName added in v1.26.0 

func (lc *LocalClient) ExpandSNIName(ctx context.Context, name string) (fqdn string, ok bool)

ExpandSNIName expands bare label name into the most likely actual TLS cert name.

func (*LocalClient) FileTargets added in v1.26.0 

func (lc *LocalClient) FileTargets(ctx context.Context) ([]apitype.FileTarget, error)

func (*LocalClient) GetCertificate added in v1.26.0 

func (lc *LocalClient) GetCertificate(hi *tls.ClientHelloInfo) (*tls.Certificate, error)

GetCertificate fetches a TLS certificate for the TLS ClientHello in hi.

It returns a cached certificate from disk if it's still valid.

It's the right signature to use as the value of tls.Config.GetCertificate.

API maturity: this is considered a stable API.

func (*LocalClient) GetDNSOSConfig added in v1.74.0 

func (lc *LocalClient) GetDNSOSConfig(ctx context.Context) (*apitype.DNSOSConfig, error)

GetDNSOSConfig returns the system DNS configuration for the current device. That is, it returns the DNS configuration that the system would use if Tailscale weren't being used.

func (*LocalClient) GetPrefs added in v1.26.0 

func (lc *LocalClient) GetPrefs(ctx context.Context) (*ipn.Prefs, error)

func (*LocalClient) GetServeConfig added in v1.34.0 

func (lc *LocalClient) GetServeConfig(ctx context.Context) (*ipn.ServeConfig, error)

GetServeConfig return the current serve config.

If the serve config is empty, it returns (nil, nil).

func (*LocalClient) GetWaitingFile added in v1.26.0 

func (lc *LocalClient) GetWaitingFile(ctx context.Context, baseName string) (rc io.ReadCloser, size int64, err error)

func (*LocalClient) Goroutines added in v1.26.0 

func (lc *LocalClient) Goroutines(ctx context.Context) ([]byte, error)

Goroutines returns a dump of the Tailscale daemon's current goroutines.

func (*LocalClient) IDToken added in v1.26.0 

func (lc *LocalClient) IDToken(ctx context.Context, aud string) (*tailcfg.TokenResponse, error)

IDToken is a request to get an OIDC ID token for an audience. The token can be presented to any resource provider which offers OIDC Federation.

func (*LocalClient) IncrementCounter added in v1.48.0 

func (lc *LocalClient) IncrementCounter(ctx context.Context, name string, delta int) error

IncrementCounter increments the value of a Tailscale daemon's counter metric by the given delta. If the metric has yet to exist, a new counter metric is created and initialized to delta.

IncrementCounter does not support gauge metrics or negative delta values.

func (*LocalClient) Logout added in v1.26.0 

func (lc *LocalClient) Logout(ctx context.Context) error

Logout logs out the current node.

func (*LocalClient) NetworkLockAffectedSigs added in v1.38.0 

func (lc *LocalClient) NetworkLockAffectedSigs(ctx context.Context, keyID tkatype.KeyID) ([]tkatype.MarshaledSignature, error)

NetworkLockAffectedSigs returns all signatures signed by the specified keyID.

func (*LocalClient) NetworkLockCosignRecoveryAUM added in v1.48.0 

func (lc *LocalClient) NetworkLockCosignRecoveryAUM(ctx context.Context, aum tka.AUM) ([]byte, error)

NetworkLockCosignRecoveryAUM co-signs a recovery AUM using the node's tailnet lock key.

func (*LocalClient) NetworkLockDisable added in v1.34.0 

func (lc *LocalClient) NetworkLockDisable(ctx context.Context, secret []byte) error

NetworkLockDisable shuts down network-lock across the tailnet.

func (*LocalClient) NetworkLockForceLocalDisable added in v1.34.0 

func (lc *LocalClient) NetworkLockForceLocalDisable(ctx context.Context) error

NetworkLockForceLocalDisable forcibly shuts down network lock on this node.

func (*LocalClient) NetworkLockGenRecoveryAUM added in v1.48.0 

func (lc *LocalClient) NetworkLockGenRecoveryAUM(ctx context.Context, removeKeys []tkatype.KeyID, forkFrom tka.AUMHash) ([]byte, error)

NetworkLockGenRecoveryAUM generates an AUM for recovering from a tailnet-lock key compromise.

func (*LocalClient) NetworkLockInit added in v1.30.0 

func (lc *LocalClient) NetworkLockInit(ctx context.Context, keys []tka.Key, disablementValues [][]byte, supportDisablement []byte) (*ipnstate.NetworkLockStatus, error)

NetworkLockInit initializes the tailnet key authority.

TODO(tom): Plumb through disablement secrets.

func (*LocalClient) NetworkLockLog added in v1.34.0 

func (lc *LocalClient) NetworkLockLog(ctx context.Context, maxEntries int) ([]ipnstate.NetworkLockUpdate, error)

NetworkLockLog returns up to maxEntries number of changes to network-lock state.

func (*LocalClient) NetworkLockModify added in v1.32.0 

func (lc *LocalClient) NetworkLockModify(ctx context.Context, addKeys, removeKeys []tka.Key) error

NetworkLockModify adds and/or removes key(s) to the tailnet key authority.

func (*LocalClient) NetworkLockSign added in v1.34.0 

func (lc *LocalClient) NetworkLockSign(ctx context.Context, nodeKey key.NodePublic, rotationPublic []byte) error

NetworkLockSign signs the specified node-key and transmits that signature to the control plane. rotationPublic, if specified, must be an ed25519 public key.

func (*LocalClient) NetworkLockStatus added in v1.30.0 

func (lc *LocalClient) NetworkLockStatus(ctx context.Context) (*ipnstate.NetworkLockStatus, error)

NetworkLockStatus fetches information about the tailnet key authority, if one is configured.

func (*LocalClient) NetworkLockSubmitRecoveryAUM added in v1.48.0 

func (lc *LocalClient) NetworkLockSubmitRecoveryAUM(ctx context.Context, aum tka.AUM) error

NetworkLockSubmitRecoveryAUM submits a recovery AUM to the control plane. 

func (lc *LocalClient) NetworkLockVerifySigningDeeplink(ctx context.Context, url string) (*tka.DeeplinkValidationResult, error)

NetworkLockVerifySigningDeeplink verifies the network lock deeplink contained in url and returns information extracted from it.

func (*LocalClient) NetworkLockWrapPreauthKey added in v1.38.0 

func (lc *LocalClient) NetworkLockWrapPreauthKey(ctx context.Context, preauthKey string, tkaKey key.NLPrivate) (string, error)

NetworkLockWrapPreauthKey wraps a pre-auth key with information to enable unattended bringup in the locked tailnet.

func (*LocalClient) Ping added in v1.26.0 

func (lc *LocalClient) Ping(ctx context.Context, ip netip.Addr, pingtype tailcfg.PingType) (*ipnstate.PingResult, error)

Ping sends a ping of the provided type to the provided IP and waits for its response.

func (*LocalClient) PingWithOpts added in v1.48.0 

func (lc *LocalClient) PingWithOpts(ctx context.Context, ip netip.Addr, pingtype tailcfg.PingType, opts PingOpts) (*ipnstate.PingResult, error)

Ping sends a ping of the provided type to the provided IP and waits for its response. The opts type specifies additional options.

func (*LocalClient) Pprof added in v1.34.0 

func (lc *LocalClient) Pprof(ctx context.Context, pprofType string, sec int) ([]byte, error)

Pprof returns a pprof profile of the Tailscale daemon.

func (*LocalClient) ProfileStatus added in v1.34.0 

func (lc *LocalClient) ProfileStatus(ctx context.Context) (current ipn.LoginProfile, all []ipn.LoginProfile, err error)

ProfileStatus returns the current profile and the list of all profiles.

func (*LocalClient) PushFile added in v1.26.0 

func (lc *LocalClient) PushFile(ctx context.Context, target tailcfg.StableNodeID, size int64, name string, r io.Reader) error

PushFile sends Taildrop file r to target.

A size of -1 means unknown. The name parameter is the original filename, not escaped.

func (*LocalClient) QueryDNS added in v1.76.0 

func (lc *LocalClient) QueryDNS(ctx context.Context, name string, queryType string) (bytes []byte, resolvers []*dnstype.Resolver, err error)

QueryDNS executes a DNS query for a name (`google.com.`) and query type (`CNAME`). It returns the raw DNS response bytes and the resolvers that were used to answer the query (often just one, but can be more if we raced multiple resolvers).

func (*LocalClient) QueryFeature added in v1.48.0 

func (lc *LocalClient) QueryFeature(ctx context.Context, feature string) (*tailcfg.QueryFeatureResponse, error)

QueryFeature makes a request for instructions on how to enable a feature, such as Funnel, for the node's tailnet. If relevant, this includes a control server URL the user can visit to enable the feature.

If you are looking to use QueryFeature, you'll likely want to use cli.enableFeatureInteractive instead, which handles the logic of wraping QueryFeature and translating its response into an interactive flow for the user, including using the IPN notify bus to block until the feature has been enabled.

2023-08-09: Valid feature values are "serve" and "funnel".

func (*LocalClient) ReloadConfig added in v1.52.0 

func (lc *LocalClient) ReloadConfig(ctx context.Context) (ok bool, err error)

ReloadConfig reloads the config file, if possible.

func (*LocalClient) SetComponentDebugLogging added in v1.32.0 

func (lc *LocalClient) SetComponentDebugLogging(ctx context.Context, component string, d time.Duration) error

SetComponentDebugLogging sets component's debug logging enabled for the provided duration. If the duration is in the past, the debug logging is disabled.

func (*LocalClient) SetDNS added in v1.26.0 

func (lc *LocalClient) SetDNS(ctx context.Context, name, value string) error

SetDNS adds a DNS TXT record for the given domain name, containing the provided TXT value. The intended use case is answering LetsEncrypt/ACME dns-01 challenges.

The control plane will only permit SetDNS requests with very specific names and values. The name should be "_acme-challenge." + your node's MagicDNS name. It's expected that clients cache the certs from LetsEncrypt (or whichever CA is providing them) and only request new ones as needed; the control plane rate limits SetDNS requests.

This is a low-level interface; it's expected that most Tailscale users use a higher level interface to getting/using TLS certificates.

func (*LocalClient) SetDevStoreKeyValue added in v1.34.0 

func (lc *LocalClient) SetDevStoreKeyValue(ctx context.Context, key, value string) error

SetDevStoreKeyValue set a statestore key/value. It's only meant for development. The schema (including when keys are re-read) is not a stable interface.

func (*LocalClient) SetServeConfig added in v1.34.0 

func (lc *LocalClient) SetServeConfig(ctx context.Context, config *ipn.ServeConfig) error

SetServeConfig sets or replaces the serving settings. If config is nil, settings are cleared and serving is disabled.

func (*LocalClient) SetUDPGROForwarding added in v1.68.0 

func (lc *LocalClient) SetUDPGROForwarding(ctx context.Context) error

SetUDPGROForwarding enables UDP GRO forwarding for the main interface of this node. This can be done to improve performance of tailnet nodes acting as exit nodes or subnet routers. See https://tailscale.com/kb/1320/performance-best-practices#linux-optimizations-for-subnet-routers-and-exit-nodes

func (*LocalClient) SetUseExitNode added in v1.64.0 

func (lc *LocalClient) SetUseExitNode(ctx context.Context, on bool) error

SetUseExitNode toggles the use of an exit node on or off. To turn it on, there must have been a previously used exit node. The most previously used one is reused. This is a convenience method for GUIs. To select an actual one, update the prefs.

func (*LocalClient) Start added in v1.34.0 

func (lc *LocalClient) Start(ctx context.Context, opts ipn.Options) error

Start applies the configuration specified in opts, and starts the state machine.

func (*LocalClient) StartLoginInteractive added in v1.34.0 

func (lc *LocalClient) StartLoginInteractive(ctx context.Context) error

StartLoginInteractive starts an interactive login.

func (*LocalClient) Status added in v1.26.0 

func (lc *LocalClient) Status(ctx context.Context) (*ipnstate.Status, error)

Status returns the Tailscale daemon's status.

func (*LocalClient) StatusWithoutPeers added in v1.26.0 

func (lc *LocalClient) StatusWithoutPeers(ctx context.Context) (*ipnstate.Status, error)

StatusWithoutPeers returns the Tailscale daemon's status, without the peer info.

func (*LocalClient) StreamDebugCapture added in v1.38.0 

func (lc *LocalClient) StreamDebugCapture(ctx context.Context) (io.ReadCloser, error)

StreamDebugCapture streams a pcap-formatted packet capture.

The provided context does not determine the lifetime of the returned io.ReadCloser.

func (*LocalClient) SuggestExitNode added in v1.66.0 

func (lc *LocalClient) SuggestExitNode(ctx context.Context) (apitype.ExitNodeSuggestionResponse, error)

SuggestExitNode requests an exit node suggestion and returns the exit node's details.

func (*LocalClient) SwitchProfile added in v1.34.0 

func (lc *LocalClient) SwitchProfile(ctx context.Context, profile ipn.ProfileID) error

SwitchProfile switches to the given profile.

func (*LocalClient) SwitchToEmptyProfile added in v1.34.0 

func (lc *LocalClient) SwitchToEmptyProfile(ctx context.Context) error

SwitchToEmptyProfile creates and switches to a new unnamed profile. The new profile is not assigned an ID until it is persisted after a successful login. In order to login to the new profile, the user must call LoginInteractive.

func (*LocalClient) TailDaemonLogs added in v1.36.0 

func (lc *LocalClient) TailDaemonLogs(ctx context.Context) (io.Reader, error)

TailDaemonLogs returns a stream the Tailscale daemon's logs as they arrive. Close the context to stop the stream.

func (*LocalClient) UserDial added in v1.68.0 

func (lc *LocalClient) UserDial(ctx context.Context, network, host string, port uint16) (net.Conn, error)

UserDial connects to the host's port via Tailscale for the given network.

The host may be a base DNS name (resolved from the netmap inside tailscaled), a FQDN, or an IP address.

The ctx is only used for the duration of the call, not the lifetime of the net.Conn.

func (*LocalClient) UserMetrics added in v1.74.0 

func (lc *LocalClient) UserMetrics(ctx context.Context) ([]byte, error)

UserMetrics returns the user metrics in the Prometheus text exposition format.

func (*LocalClient) WaitingFiles added in v1.26.0 

func (lc *LocalClient) WaitingFiles(ctx context.Context) ([]apitype.WaitingFile, error)

WaitingFiles returns the list of received Taildrop files that have been received by the Tailscale daemon in its staging/cache directory but not yet transferred by the user's CLI or GUI client and written to a user's home directory somewhere.

func (*LocalClient) WatchIPNBus added in v1.34.0 

func (lc *LocalClient) WatchIPNBus(ctx context.Context, mask ipn.NotifyWatchOpt) (*IPNBusWatcher, error)

WatchIPNBus subscribes to the IPN notification bus. It returns a watcher once the bus is connected successfully.

The context is used for the life of the watch, not just the call to WatchIPNBus.

The returned IPNBusWatcher's Close method must be called when done to release resources.

A default set of ipn.Notify messages are returned but the set can be modified by mask.

func (*LocalClient) WhoIs added in v1.26.0 

func (lc *LocalClient) WhoIs(ctx context.Context, remoteAddr string) (*apitype.WhoIsResponse, error)

WhoIs returns the owner of the remoteAddr, which must be an IP or IP:port.

If not found, the error is ErrPeerNotFound.

For connections proxied by tailscaled, this looks up the owner of the given address as TCP first, falling back to UDP; if you want to only check a specific address family, use WhoIsProto.

func (*LocalClient) WhoIsNodeKey added in v1.70.0 

func (lc *LocalClient) WhoIsNodeKey(ctx context.Context, key key.NodePublic) (*apitype.WhoIsResponse, error)

WhoIsNodeKey returns the owner of the given wireguard public key.

If not found, the error is ErrPeerNotFound.

func (*LocalClient) WhoIsProto added in v1.70.0 

func (lc *LocalClient) WhoIsProto(ctx context.Context, proto, remoteAddr string) (*apitype.WhoIsResponse, error)

WhoIsProto returns the owner of the remoteAddr, which must be an IP or IP:port, for the given protocol (tcp or udp).

If not found, the error is ErrPeerNotFound.

type NodeAttrGrant added in v1.70.0 

type NodeAttrGrant struct {
	// Target specifies which nodes the attributes apply to. The nodes can be a
	// tag (tag:server), user (alice@example.com), group (group:kids), or *.
	Target []string `json:"target,omitempty"`

	// Attr are the attributes to set on Target(s).
	Attr []string `json:"attr,omitempty"`
}

NodeAttrGrant defines additional string attributes that apply to specific devices.

type PingOpts added in v1.48.0 

type PingOpts struct {
	// Size is the length of the ping message in bytes. It's ignored if it's
	// smaller than the minimum message size.
	//
	// For disco pings, it specifies the length of the packet's payload. That
	// is, it includes the disco headers and message, but not the IP and UDP
	// headers.
	Size int
}

PingOpts contains options for the ping request.

The zero value is valid, which means to use defaults.

type PreconditionsFailedError added in v1.50.0 

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

PreconditionsFailedError is returned when the server responds with an HTTP 412 status code.

func (*PreconditionsFailedError) Error added in v1.50.0 

func (e *PreconditionsFailedError) Error() string

func (*PreconditionsFailedError) Unwrap added in v1.50.0 

func (e *PreconditionsFailedError) Unwrap() error

type Routes added in v1.26.0 

type Routes struct {
	AdvertisedRoutes []netip.Prefix `json:"advertisedRoutes"`
	EnabledRoutes    []netip.Prefix `json:"enabledRoutes"`
}

Routes contains the lists of subnet routes that are currently advertised by a device, as well as the subnets that are enabled to be routed by the device.

type UserRuleMatch added in v1.26.0 

type UserRuleMatch struct {
	Users      []string `json:"users"`
	Ports      []string `json:"ports"`
	LineNumber int      `json:"lineNumber"`
	// Via is the list of targets through which Users can access Ports.
	// See https://tailscale.com/kb/1378/via for more information.
	Via []string `json:"via,omitempty"`

	// Postures is a list of posture policies that are
	// associated with this match. The rules can be looked
	// up in the ACLPreviewResponse parent struct.
	// The source of the list is from srcPosture on
	// an ACL or Grant rule:
	// https://tailscale.com/kb/1288/device-posture#posture-conditions
	Postures []string `json:"postures"`
}

UserRuleMatch specifies the source users/groups/hosts that a rule targets and the destination ports that they can access. LineNumber is only useful for requests provided in HuJSON form. While JSON requests will have LineNumber, the value is not useful.

Source Files

View all Source files

Directories

Path Synopsis
Package apitype contains types for the Tailscale LocalAPI and control plane API.
 Package apitype contains types for the Tailscale LocalAPI and control plane API.
example
servetls
The servetls program shows how to run an HTTPS server using a Tailscale cert via LetsEncrypt.
 The servetls program shows how to run an HTTPS server using a Tailscale cert via LetsEncrypt.

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.