tailscale

package module
v2.0.0-...-fe1dae8 Latest Latest
Warning

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

 Go to latest Published: Apr 2, 2025 License: MIT Imports: 12 Imported by: 3

README

tailscale.com/client/tailscale/v2

Go Reference Github Actions

The official client implementation for the Tailscale HTTP API. For more details, please see API documentation.

Example (Using API Key)

package main

import (
	"context"
	"os"

	"tailscale.com/client/tailscale/v2"
)

func main() {
	client := &tailscale.Client{
		Tailnet: os.Getenv("TAILSCALE_TAILNET"),
		APIKey:  os.Getenv("TAILSCALE_API_KEY"),
	}

	devices, err := client.Devices().List(context.Background())
}

Example (Using OAuth)

package main

import (
	"context"
	"os"

	"tailscale.com/client/tailscale/v2"
)

func main() {
	client := &tailscale.Client{
		Tailnet: os.Getenv("TAILSCALE_TAILNET"),
		HTTP:    tailscale.OAuthConfig{
			ClientID:     os.Getenv("TAILSCALE_OAUTH_CLIENT_ID"),
			ClientSecret: os.Getenv("TAILSCALE_OAUTH_CLIENT_SECRET"),
			Scopes:       []string{"all:write"},
		}.HTTPClient(),
	}
	
	devices, err := client.Devices().List(context.Background())
}

Documentation

Overview

package tailscale contains a basic implementation of a client for the Tailscale HTTP API.

Documentation is at https://tailscale.com/api

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound returns true if the provided error implementation is an APIError with a status of 404.

func PointerTo 

func PointerTo[T any](value T) *T

PointerTo returns a pointer to the given value. Pointers are used in PATCH requests to distinguish between specified and unspecified values.

Types

type ACL 

type ACL struct {
	ACLs                []ACLEntry          `json:"acls,omitempty" hujson:"ACLs,omitempty"`
	AutoApprovers       *ACLAutoApprovers   `json:"autoApprovers,omitempty" hujson:"AutoApprovers,omitempty"`
	Groups              map[string][]string `json:"groups,omitempty" hujson:"Groups,omitempty"`
	Hosts               map[string]string   `json:"hosts,omitempty" hujson:"Hosts,omitempty"`
	TagOwners           map[string][]string `json:"tagOwners,omitempty" hujson:"TagOwners,omitempty"`
	DERPMap             *ACLDERPMap         `json:"derpMap,omitempty" hujson:"DerpMap,omitempty"`
	Tests               []ACLTest           `json:"tests,omitempty" hujson:"Tests,omitempty"`
	SSH                 []ACLSSH            `json:"ssh,omitempty" hujson:"SSH,omitempty"`
	NodeAttrs           []NodeAttrGrant     `json:"nodeAttrs,omitempty" hujson:"NodeAttrs,omitempty"`
	DisableIPv4         bool                `json:"disableIPv4,omitempty" hujson:"DisableIPv4,omitempty"`
	OneCGNATRoute       string              `json:"oneCGNATRoute,omitempty" hujson:"OneCGNATRoute,omitempty"`
	RandomizeClientPort bool                `json:"randomizeClientPort,omitempty" hujson:"RandomizeClientPort,omitempty"`

	// Postures and DefaultSourcePosture are for an experimental feature and not yet public or documented as of 2023-08-17.
	// This API is subject to change. Internal bug: corp/13986
	Postures             map[string][]string `json:"postures,omitempty" hujson:"Postures,omitempty"`
	DefaultSourcePosture []string            `json:"defaultSrcPosture,omitempty" hujson:"DefaultSrcPosture,omitempty"`

	// ETag is the etag corresponding to this version of the ACL
	ETag string `json:"-"`
}

ACL contains the schema for a tailnet policy file. More details: https://tailscale.com/kb/1018/acls/

type ACLAutoApprovers 

type ACLAutoApprovers struct {
	Routes   map[string][]string `json:"routes,omitempty" hujson:"Routes,omitempty"`
	ExitNode []string            `json:"exitNode,omitempty" hujson:"ExitNode,omitempty"`
}

type ACLDERPMap 

type ACLDERPMap struct {
	Regions            map[int]*ACLDERPRegion `json:"regions" hujson:"Regions"`
	OmitDefaultRegions bool                   `json:"omitDefaultRegions,omitempty" hujson:"OmitDefaultRegions,omitempty"`
}

type ACLDERPNode 

type ACLDERPNode struct {
	Name     string `json:"name" hujson:"Name"`
	RegionID int    `json:"regionID" hujson:"RegionID"`
	HostName string `json:"hostName" hujson:"HostName"`
	CertName string `json:"certName,omitempty" hujson:"CertName,omitempty"`
	IPv4     string `json:"ipv4,omitempty" hujson:"IPv4,omitempty"`
	IPv6     string `json:"ipv6,omitempty" hujson:"IPv6,omitempty"`
	STUNPort int    `json:"stunPort,omitempty" hujson:"STUNPort,omitempty"`
	STUNOnly bool   `json:"stunOnly,omitempty" hujson:"STUNOnly,omitempty"`
	DERPPort int    `json:"derpPort,omitempty" hujson:"DERPPort,omitempty"`
}

type ACLDERPRegion 

type ACLDERPRegion struct {
	RegionID   int            `json:"regionID" hujson:"RegionID"`
	RegionCode string         `json:"regionCode" hujson:"RegionCode"`
	RegionName string         `json:"regionName" hujson:"RegionName"`
	Avoid      bool           `json:"avoid,omitempty" hujson:"Avoid,omitempty"`
	Nodes      []*ACLDERPNode `json:"nodes" hujson:"Nodes"`
}

type ACLEntry 

type ACLEntry struct {
	Action      string   `json:"action,omitempty" hujson:"Action,omitempty"`
	Ports       []string `json:"ports,omitempty" hujson:"Ports,omitempty"`
	Users       []string `json:"users,omitempty" hujson:"Users,omitempty"`
	Source      []string `json:"src,omitempty" hujson:"Src,omitempty"`
	Destination []string `json:"dst,omitempty" hujson:"Dst,omitempty"`
	Protocol    string   `json:"proto,omitempty" hujson:"Proto,omitempty"`

	// SourcePosture is for an experimental feature and not yet public or documented as of 2023-08-17.
	SourcePosture []string `json:"srcPosture,omitempty" hujson:"SrcPosture,omitempty"`
}

type ACLSSH 

type ACLSSH struct {
	Action          string         `json:"action,omitempty" hujson:"Action,omitempty"`
	Users           []string       `json:"users,omitempty" hujson:"Users,omitempty"`
	Source          []string       `json:"src,omitempty" hujson:"Src,omitempty"`
	Destination     []string       `json:"dst,omitempty" hujson:"Dst,omitempty"`
	CheckPeriod     SSHCheckPeriod `json:"checkPeriod,omitempty" hujson:"CheckPeriod,omitempty"`
	Recorder        []string       `json:"recorder,omitempty" hujson:"Recorder,omitempty"`
	EnforceRecorder bool           `json:"enforceRecorder,omitempty" hujson:"EnforceRecorder,omitempty"`
}

type ACLTest 

type ACLTest struct {
	User   string   `json:"user,omitempty" hujson:"User,omitempty"`
	Allow  []string `json:"allow,omitempty" hujson:"Allow,omitempty"`
	Deny   []string `json:"deny,omitempty" hujson:"Deny,omitempty"`
	Source string   `json:"src,omitempty" hujson:"Src,omitempty"`
	Accept []string `json:"accept,omitempty" hujson:"Accept,omitempty"`
}

type APIError 

type APIError struct {
	Message string         `json:"message"`
	Data    []APIErrorData `json:"data"`
	// contains filtered or unexported fields
}

APIError type describes an error as returned by the Tailscale API.

func (APIError) Error 

func (err APIError) Error() string

type APIErrorData 

type APIErrorData struct {
	User   string   `json:"user"`
	Errors []string `json:"errors"`
}

APIErrorData type describes elements of the data field within errors returned by the Tailscale API.

func ErrorData 

func ErrorData(err error) []APIErrorData

ErrorData returns the contents of the APIError.Data field from the provided error if it is of type APIError. Returns a nil slice if the given error is not of type APIError.

type AWSExternalID 

type AWSExternalID struct {
	ExternalID            string `json:"externalId,omitempty"`
	TailscaleAWSAccountID string `json:"tailscaleAwsAccountId,omitempty"`
}

AWSExternalID represents an AWS External ID that Tailscale can use to stream logs from a particular Tailscale AWS account to a LogstreamS3Endpoint that uses S3RoleARNAuthentication.

type Client 

type Client struct {
	// BaseURL is the base URL for accessing the Tailscale API server. Defaults to https://api.tailscale.com.
	BaseURL *url.URL
	// UserAgent configures the User-Agent HTTP header for requests. Defaults to "tailscale-client-go".
	UserAgent string
	// APIKey allows specifying an APIKey to use for authentication.
	// To use OAuth Client credentials, construct an [http.Client] using [OAuthConfig] and specify that below.
	APIKey string
	// Tailnet allows specifying a specific Tailnet by name, to which this Client will connect by default.
	Tailnet string

	// HTTP is the [http.Client] to use for requests to the API server.
	// If not specified, a new [http.Client] with a Timeout of 1 minute will be used.
	HTTP *http.Client
	// contains filtered or unexported fields
}

Client is used to perform actions against the Tailscale API.

func (*Client) Contacts 

func (c *Client) Contacts() *ContactsResource

Contacts() provides access to https://tailscale.com/api#tag/contacts.

func (*Client) DNS 

func (c *Client) DNS() *DNSResource

DNS provides access to https://tailscale.com/api#tag/dns.

func (*Client) DevicePosture 

func (c *Client) DevicePosture() *DevicePostureResource

DevicePosture provides access to https://tailscale.com/api#tag/deviceposture.

func (*Client) Devices 

func (c *Client) Devices() *DevicesResource

Devices provides access to https://tailscale.com/api#tag/devices.

func (*Client) Keys 

func (c *Client) Keys() *KeysResource

Keys provides access to https://tailscale.com/api#tag/keys.

func (*Client) Logging 

func (c *Client) Logging() *LoggingResource

Logging provides access to https://tailscale.com/api#tag/logging.

func (*Client) PolicyFile 

func (c *Client) PolicyFile() *PolicyFileResource

PolicyFile provides access to https://tailscale.com/api#tag/policyfile.

func (*Client) TailnetSettings 

func (c *Client) TailnetSettings() *TailnetSettingsResource

TailnetSettings provides access to https://tailscale.com/api#tag/tailnetsettings.

func (*Client) Users 

func (c *Client) Users() *UsersResource

Users provides access to https://tailscale.com/api#tag/users.

func (*Client) Webhooks 

func (c *Client) Webhooks() *WebhooksResource

Webhooks provides access to https://tailscale.com/api#tag/webhooks.

type ClientConnectivity 

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

type ClientSupports 

type ClientSupports struct {
	HairPinning bool `json:"hairPinning"`
	IPV6        bool `json:"ipv6"`
	PCP         bool `json:"pcp"`
	PMP         bool `json:"pmp"`
	UDP         bool `json:"udp"`
	UPNP        bool `json:"upnp"`
}

type CompressionFormat 

type CompressionFormat string

CompressionFormat specifies what kind of compression to use on logs. 

const (
	CompressionFormatNone CompressionFormat = "none"
	CompressionFormatZstd CompressionFormat = "zstd"
	CompressionFormatGzip CompressionFormat = "gzip"
)

type Contact 

type Contact struct {
	Email string `json:"email"`
	// FallbackEmail is the email used when Email has not been verified.
	FallbackEmail string `json:"fallbackEmail,omitempty"`
	// NeedsVerification is true if Email needs to be verified.
	NeedsVerification bool `json:"needsVerification"`
}

Contact type defines the structure of an individual contact for the tailnet.

type ContactType 

type ContactType string

ContactType defines the type of contact. 

const (
	ContactAccount  ContactType = "account"
	ContactSupport  ContactType = "support"
	ContactSecurity ContactType = "security"
)

type Contacts 

type Contacts struct {
	Account  Contact `json:"account"`
	Support  Contact `json:"support"`
	Security Contact `json:"security"`
}

Contacts type defines the object returned when retrieving contacts.

type ContactsResource 

type ContactsResource struct {
	*Client
}

ContactsResource provides access to https://tailscale.com/api#tag/contacts.

func (*ContactsResource) Get 

func (cr *ContactsResource) Get(ctx context.Context) (*Contacts, error)

Get retieves the Contacts for the tailnet.

func (*ContactsResource) Update 

func (cr *ContactsResource) Update(ctx context.Context, contactType ContactType, contact UpdateContactRequest) error

Update updates the email for the specified ContactType within the tailnet. If the email address changes, the system will send a verification email to confirm the change.

type CreateKeyRequest 

type CreateKeyRequest struct {
	Capabilities  KeyCapabilities `json:"capabilities"`
	ExpirySeconds int64           `json:"expirySeconds"`
	Description   string          `json:"description"`
}

CreateKeyRequest describes the definition of an authentication key to create.

type CreatePostureIntegrationRequest 

type CreatePostureIntegrationRequest struct {
	Provider     PostureIntegrationProvider `json:"provider,omitempty"`
	CloudID      string                     `json:"cloudId,omitempty"`
	ClientID     string                     `json:"clientId,omitempty"`
	TenantID     string                     `json:"tenantId,omitempty"`
	ClientSecret string                     `json:"clientSecret,omitempty"`
}

CreatePostureIntegrationRequest is a request to create a posture integration.

type CreateWebhookRequest 

type CreateWebhookRequest struct {
	EndpointURL   string                    `json:"endpointUrl"`
	ProviderType  WebhookProviderType       `json:"providerType"`
	Subscriptions []WebhookSubscriptionType `json:"subscriptions"`
}

CreateWebhookRequest type describes the configuration for creating a Webhook.

type DERPRegion 

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

type DNSPreferences 

type DNSPreferences struct {
	MagicDNS bool `json:"magicDNS"`
}

type DNSResource 

type DNSResource struct {
	*Client
}

DNSResource provides access to https://tailscale.com/api#tag/dns.

func (*DNSResource) Nameservers 

func (dr *DNSResource) Nameservers(ctx context.Context) ([]string, error)

Nameservers lists the DNS nameservers for the tailnet

func (*DNSResource) Preferences 

func (dr *DNSResource) Preferences(ctx context.Context) (*DNSPreferences, error)

Preferences retrieves the DNS preferences that are currently set for the given tailnet.

func (*DNSResource) SearchPaths 

func (dr *DNSResource) SearchPaths(ctx context.Context) ([]string, error)

SearchPaths retrieves the list of search paths that is currently set for the given tailnet.

func (*DNSResource) SetNameservers 

func (dr *DNSResource) SetNameservers(ctx context.Context, dns []string) error

SetNameservers replaces the list of DNS nameservers for the given tailnet with the list supplied by the user. Note that changing the list of DNS nameservers may also affect the status of MagicDNS (if MagicDNS is on).

func (*DNSResource) SetPreferences 

func (dr *DNSResource) SetPreferences(ctx context.Context, preferences DNSPreferences) error

SetPreferences replaces the DNS preferences for the tailnet, specifically, the MagicDNS setting. Note that MagicDNS is dependent on DNS servers.

func (*DNSResource) SetSearchPaths 

func (dr *DNSResource) SetSearchPaths(ctx context.Context, searchPaths []string) error

SetSearchPaths replaces the list of search paths with the list supplied by the user and returns an error otherwise.

func (*DNSResource) SetSplitDNS 

func (dr *DNSResource) SetSplitDNS(ctx context.Context, request SplitDNSRequest) error

SetSplitDNS sets the split DNS settings for the tailnet using the provided SplitDNSRequest object. This is a PUT operation that fully replaces the underlying data structure.

Passing in an empty SplitDNSRequest will unset all split DNS mappings for the tailnet.

func (*DNSResource) SplitDNS 

func (dr *DNSResource) SplitDNS(ctx context.Context) (SplitDNSResponse, error)

SplitDNS retrieves the split DNS configuration for the tailnet.

func (*DNSResource) UpdateSplitDNS 

func (dr *DNSResource) UpdateSplitDNS(ctx context.Context, request SplitDNSRequest) (SplitDNSResponse, error)

UpdateSplitDNS updates the split DNS settings for the tailnet using the provided SplitDNSRequest object. This is a PATCH operation that performs partial updates of the underlying data structure.

Mapping a domain to a nil slice in the request will unset the nameservers associated with that domain. Values provided for domains will overwrite the current value associated with the domain. Domains not included in the request will remain unchanged.

type Device 

type Device struct {
	Addresses                 []string `json:"addresses"`
	Name                      string   `json:"name"`
	ID                        string   `json:"id"`     // The legacy identifier for a device. Use NodeId instead.
	NodeID                    string   `json:"nodeId"` // The preferred identifier for a device.
	Authorized                bool     `json:"authorized"`
	User                      string   `json:"user"`
	Tags                      []string `json:"tags"`
	KeyExpiryDisabled         bool     `json:"keyExpiryDisabled"`
	BlocksIncomingConnections bool     `json:"blocksIncomingConnections"`
	ClientVersion             string   `json:"clientVersion"`
	Created                   Time     `json:"created"`
	Expires                   Time     `json:"expires"`
	Hostname                  string   `json:"hostname"`
	IsExternal                bool     `json:"isExternal"`
	LastSeen                  Time     `json:"lastSeen"`
	MachineKey                string   `json:"machineKey"`
	NodeKey                   string   `json:"nodeKey"`
	OS                        string   `json:"os"`
	TailnetLockError          string   `json:"tailnetLockError"`
	TailnetLockKey            string   `json:"tailnetLockKey"`
	UpdateAvailable           bool     `json:"updateAvailable"`

	// The below are only included in listings when querying `all` fields.
	AdvertisedRoutes   []string            `json:"AdvertisedRoutes"`
	EnabledRoutes      []string            `json:"enabledRoutes"`
	ClientConnectivity *ClientConnectivity `json:"clientConnectivity"`
}

type DeviceKey 

type DeviceKey struct {
	KeyExpiryDisabled bool `json:"keyExpiryDisabled"` // Whether or not this device's key will ever expire.
}

DeviceKey type represents the properties of the key of an individual device within the tailnet.

type DevicePostureAttributeRequest 

type DevicePostureAttributeRequest struct {
	Value   any    `json:"value"`
	Expiry  Time   `json:"expiry"`
	Comment string `json:"comment"`
}

type DevicePostureAttributes 

type DevicePostureAttributes struct {
	Attributes map[string]any  `json:"attributes"`
	Expiries   map[string]Time `json:"expiries"`
}

type DevicePostureResource 

type DevicePostureResource struct {
	*Client
}

DevicePostureResource provides access to https://tailscale.com/api#tag/deviceposture.

func (*DevicePostureResource) CreateIntegration 

func (pr *DevicePostureResource) CreateIntegration(ctx context.Context, intg CreatePostureIntegrationRequest) (*PostureIntegration, error)

CreateIntegration creates a new posture integration, returning the resulting PostureIntegration.

func (*DevicePostureResource) DeleteIntegration 

func (pr *DevicePostureResource) DeleteIntegration(ctx context.Context, id string) error

DeleteIntegration deletes the posture integration identified by id.

func (*DevicePostureResource) GetIntegration 

func (pr *DevicePostureResource) GetIntegration(ctx context.Context, id string) (*PostureIntegration, error)

GetIntegration gets the posture integration identified by id.

func (*DevicePostureResource) ListIntegrations 

func (pr *DevicePostureResource) ListIntegrations(ctx context.Context) ([]PostureIntegration, error)

List lists every configured PostureIntegration.

func (*DevicePostureResource) UpdateIntegration 

func (pr *DevicePostureResource) UpdateIntegration(ctx context.Context, id string, intg UpdatePostureIntegrationRequest) (*PostureIntegration, error)

UpdateIntegration updates the existing posture integration identified by id, returning the resulting PostureIntegration.

type DeviceRoutes 

type DeviceRoutes struct {
	Advertised []string `json:"advertisedRoutes"`
	Enabled    []string `json:"enabledRoutes"`
}

type DevicesResource 

type DevicesResource struct {
	*Client
}

DevicesResource provides access to https://tailscale.com/api#tag/devices.

func (*DevicesResource) Delete 

func (dr *DevicesResource) Delete(ctx context.Context, deviceID string) error

Delete deletes the device identified by deviceID.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) Get 

func (dr *DevicesResource) Get(ctx context.Context, deviceID string) (*Device, error)

Get gets the Device identified by `deviceID`.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) GetPostureAttributes 

func (dr *DevicesResource) GetPostureAttributes(ctx context.Context, deviceID string) (*DevicePostureAttributes, error)

GetPostureAttributes retrieves the posture attributes of the device identified by deviceID.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) GetWithAllFields 

func (dr *DevicesResource) GetWithAllFields(ctx context.Context, deviceID string) (*Device, error)

GetWithAllFields gets the Device identified by `deviceID`. All fields will be populated.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) List 

func (dr *DevicesResource) List(ctx context.Context) ([]Device, error)

List lists every Device in the tailnet. The fields `EnabledRoutes`, `AdvertisedRoutes` and `ClientConnectivity` will be omitted from the resulting [Devices]. To get these fields, use `ListWithAllFields`.

func (*DevicesResource) ListWithAllFields 

func (dr *DevicesResource) ListWithAllFields(ctx context.Context) ([]Device, error)

ListWithAllFields lists every Device in the tailnet. Each Device in the response will have all fields populated.

func (*DevicesResource) SetAuthorized 

func (dr *DevicesResource) SetAuthorized(ctx context.Context, deviceID string, authorized bool) error

SetAuthorized marks the specified device as authorized or not.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetIPv4Address 

func (dr *DevicesResource) SetIPv4Address(ctx context.Context, deviceID string, ipv4Address string) error

SetDeviceIPv4Address sets the Tailscale IPv4 address of the device.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetKey 

func (dr *DevicesResource) SetKey(ctx context.Context, deviceID string, key DeviceKey) error

SetKey updates the properties of a device's key.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetName 

func (dr *DevicesResource) SetName(ctx context.Context, deviceID, name string) error

SetName updates the name of the device identified by deviceID.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetPostureAttribute 

func (dr *DevicesResource) SetPostureAttribute(ctx context.Context, deviceID, attributeKey string, request DevicePostureAttributeRequest) error

SetPostureAttribute sets the posture attribute of the device identified by deviceID.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetSubnetRoutes 

func (dr *DevicesResource) SetSubnetRoutes(ctx context.Context, deviceID string, routes []string) error

SetSubnetRoutes sets which subnet routes are enabled to be routed by a device by replacing the existing list of subnet routes with the supplied routes. Routes can be enabled without a device advertising them (e.g. for preauth).

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SetTags 

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

SetTags updates the tags of the device identified by deviceID.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

func (*DevicesResource) SubnetRoutes 

func (dr *DevicesResource) SubnetRoutes(ctx context.Context, deviceID string) (*DeviceRoutes, error)

SubnetRoutes Retrieves the list of subnet routes that a device is advertising, as well as those that are enabled for it. Enabled routes are not necessarily advertised (e.g. for pre-enabling), and likewise, advertised routes are not necessarily enabled.

Using the device `NodeID` is preferred, but its numeric `ID` value can also be used.

type Key 

type Key struct {
	ID           string          `json:"id"`
	Key          string          `json:"key"`
	Description  string          `json:"description"`
	Created      time.Time       `json:"created"`
	Expires      time.Time       `json:"expires"`
	Revoked      time.Time       `json:"revoked"`
	Invalid      bool            `json:"invalid"`
	Capabilities KeyCapabilities `json:"capabilities"`
	UserID       string          `json:"userId"`
}

Key describes an authentication key within the tailnet.

type KeyCapabilities 

type KeyCapabilities struct {
	Devices struct {
		Create struct {
			Reusable      bool     `json:"reusable"`
			Ephemeral     bool     `json:"ephemeral"`
			Tags          []string `json:"tags"`
			Preauthorized bool     `json:"preauthorized"`
		} `json:"create"`
	} `json:"devices"`
}

KeyCapabilities describes the capabilities of an authentication key.

type KeysResource 

type KeysResource struct {
	*Client
}

KeysResource provides access to https://tailscale.com/api#tag/keys.

func (*KeysResource) Create 

func (kr *KeysResource) Create(ctx context.Context, ckr CreateKeyRequest) (*Key, error)

Create creates a new authentication key. Returns the generated Key if successful.

func (*KeysResource) Delete 

func (kr *KeysResource) Delete(ctx context.Context, id string) error

Delete removes an authentication key from the tailnet.

func (*KeysResource) Get 

func (kr *KeysResource) Get(ctx context.Context, id string) (*Key, error)

Get returns all information on a Key whose identifier matches the one provided. This will not return the authentication key itself, just the metadata.

func (*KeysResource) List 

func (kr *KeysResource) List(ctx context.Context, all bool) ([]Key, error)

List returns every Key within the tailnet. The only fields set for each Key will be its identifier. The keys returned are relative to the user that owns the API key used to authenticate the client.

Specify all to list both user and tailnet level keys.

type LogType 

type LogType string

LogType describes the type of logging. 

const (
	LogTypeConfig  LogType = "configuration"
	LogTypeNetwork LogType = "network"
)

type LoggingResource 

type LoggingResource struct {
	*Client
}

LoggingResource provides access to https://tailscale.com/api#tag/logging.

func (*LoggingResource) CreateOrGetAwsExternalId 

func (lr *LoggingResource) CreateOrGetAwsExternalId(ctx context.Context, reusable bool) (*AWSExternalID, error)

CreateOrGetAwsExternalId gets an AWS External ID that Tailscale can use to stream logs to a LogstreamS3Endpoint using S3RoleARNAuthentication, creating a new one for this tailnet when necessary.

func (*LoggingResource) DeleteLogstreamConfiguration 

func (lr *LoggingResource) DeleteLogstreamConfiguration(ctx context.Context, logType LogType) error

DeleteLogstreamConfiguration deletes the tailnet's LogstreamConfiguration for the given LogType.

func (*LoggingResource) LogstreamConfiguration 

func (lr *LoggingResource) LogstreamConfiguration(ctx context.Context, logType LogType) (*LogstreamConfiguration, error)

LogstreamConfiguration retrieves the tailnet's LogstreamConfiguration for the given LogType.

func (*LoggingResource) SetLogstreamConfiguration 

func (lr *LoggingResource) SetLogstreamConfiguration(ctx context.Context, logType LogType, request SetLogstreamConfigurationRequest) error

SetLogstreamConfiguration sets the tailnet's LogstreamConfiguration for the given LogType.

func (*LoggingResource) ValidateAWSTrustPolicy 

func (lr *LoggingResource) ValidateAWSTrustPolicy(ctx context.Context, awsExternalID string, roleARN string) error

ValidateAWSTrustPolicy validates that Tailscale can assume your AWS IAM role with (and only with) the given AWS External ID.

type LogstreamConfiguration 

type LogstreamConfiguration struct {
	LogType              LogType               `json:"logType,omitempty"`
	DestinationType      LogstreamEndpointType `json:"destinationType,omitempty"`
	URL                  string                `json:"url,omitempty"`
	User                 string                `json:"user,omitempty"`
	UploadPeriodMinutes  int                   `json:"uploadPeriodMinutes,omitempty"`
	CompressionFormat    CompressionFormat     `json:"compressionFormat,omitempty"`
	S3Bucket             string                `json:"s3Bucket,omitempty"`
	S3Region             string                `json:"s3Region,omitempty"`
	S3KeyPrefix          string                `json:"s3KeyPrefix,omitempty"`
	S3AuthenticationType S3AuthenticationType  `json:"s3AuthenticationType,omitempty"`
	S3AccessKeyID        string                `json:"s3AccessKeyId,omitempty"`
	S3RoleARN            string                `json:"s3RoleArn,omitempty"`
	S3ExternalID         string                `json:"s3ExternalId,omitempty"`
}

LogstreamConfiguration type defines a log stream entity in tailscale.

type LogstreamEndpointType 

type LogstreamEndpointType string

LogstreamEndpointType describes the type of the endpoint. 

const (
	LogstreamSplunkEndpoint  LogstreamEndpointType = "splunk"
	LogstreamElasticEndpoint LogstreamEndpointType = "elastic"
	LogstreamPantherEndpoint LogstreamEndpointType = "panther"
	LogstreamCriblEndpoint   LogstreamEndpointType = "cribl"
	LogstreamDatadogEndpoint LogstreamEndpointType = "datadog"
	LogstreamAxiomEndpoint   LogstreamEndpointType = "axiom"
	LogstreamS3Endpoint      LogstreamEndpointType = "s3"
)

type NodeAttrGrant 

type NodeAttrGrant struct {
	Target []string                       `json:"target,omitempty" hujson:"Target,omitempty"`
	Attr   []string                       `json:"attr,omitempty" hujson:"Attr,omitempty"`
	App    map[string][]*NodeAttrGrantApp `json:"app,omitempty" hujson:"App,omitempty"`
}

type NodeAttrGrantApp 

type NodeAttrGrantApp struct {
	Name       string   `json:"name,omitempty" hujson:"Name,omitempty"`
	Connectors []string `json:"connectors,omitempty" hujson:"Connectors,omitempty"`
	Domains    []string `json:"domains,omitempty" hujson:"Domains,omitempty"`
}

type OAuthConfig 

type OAuthConfig struct {
	// ClientID is the client ID of the OAuth client.
	ClientID string
	// ClientSecret is the client secret of the OAuth client.
	ClientSecret string
	// Scopes are the scopes to request when generating tokens for this OAuth client.
	Scopes []string
	// BaseURL is an optional base URL for the API server to which we'll connect. Defaults to https://api.tailscale.com.
	BaseURL string
}

OAuthConfig provides a mechanism for configuring OAuth authentication.

func (OAuthConfig) HTTPClient 

func (ocfg OAuthConfig) HTTPClient() *http.Client

HTTPClient constructs an HTTP client that authenticates using OAuth.

type PolicyFileResource 

type PolicyFileResource struct {
	*Client
}

PolicyFileResource provides access to https://tailscale.com/api#tag/policyfile.

func (*PolicyFileResource) Get 

func (pr *PolicyFileResource) Get(ctx context.Context) (*ACL, error)

Get retrieves the ACL that is currently set for the tailnet.

func (*PolicyFileResource) Raw 

func (pr *PolicyFileResource) Raw(ctx context.Context) (*RawACL, error)

Raw retrieves the ACL that is currently set for the tailnet as a HuJSON string.

func (*PolicyFileResource) Set 

func (pr *PolicyFileResource) Set(ctx context.Context, acl any, etag string) error

Set sets the ACL for the tailnet. acl can either be an ACL, or a HuJSON string. etag is an optional value that, if supplied, will be used in the "If-Match" HTTP request header.

func (*PolicyFileResource) SetAndGet 

func (pr *PolicyFileResource) SetAndGet(ctx context.Context, acl ACL, etag string) (*ACL, error)

SetAndGet sets the ACL for the tailnet and returns the resulting ACL. etag is an optional value that, if supplied, will be used in the "If-Match" HTTP request header.

func (*PolicyFileResource) Validate 

func (pr *PolicyFileResource) Validate(ctx context.Context, acl any) error

Validate validates the provided ACL via the API. acl can either be an ACL, or a HuJSON string.

type PostureIntegration 

type PostureIntegration struct {
	ID       string                     `json:"id,omitempty"`
	Provider PostureIntegrationProvider `json:"provider,omitempty"`
	CloudID  string                     `json:"cloudId,omitempty"`
	ClientID string                     `json:"clientId,omitempty"`
	TenantID string                     `json:"tenantId,omitempty"`
}

PostureIntegration is a configured posture integration.

type PostureIntegrationProvider 

type PostureIntegrationProvider string

PostureIntegrationProvider identifies a supported posture integration data provider. 

const (
	PostureIntegrationProviderFalcon      PostureIntegrationProvider = "falcon"
	PostureIntegrationProviderIntune      PostureIntegrationProvider = "intune"
	PostureIntegrationProviderJamfPro     PostureIntegrationProvider = "jamfpro"
	PostureIntegrationProviderKandji      PostureIntegrationProvider = "kandji"
	PostureIntegrationProviderKolide      PostureIntegrationProvider = "kolide"
	PostureIntegrationProviderSentinelOne PostureIntegrationProvider = "sentinelone"
)

type RawACL 

type RawACL struct {
	// HuJSON is the raw HuJSON ACL string
	HuJSON string

	// ETag is the etag corresponding to this version of the ACL
	ETag string
}

RawACL contains a raw HuJSON ACL and its associated ETag.

type RoleAllowedToJoinExternalTailnets 

type RoleAllowedToJoinExternalTailnets string

RoleAllowedToJoinExternalTailnets constrains which users are allowed to join external tailnets based on their role. 

const (
	RoleAllowedToJoinExternalTailnetsNone   RoleAllowedToJoinExternalTailnets = "none"
	RoleAllowedToJoinExternalTailnetsAdmin  RoleAllowedToJoinExternalTailnets = "admin"
	RoleAllowedToJoinExternalTailnetsMember RoleAllowedToJoinExternalTailnets = "member"
)

type S3AuthenticationType 

type S3AuthenticationType string

S3AuthenticationType describes the type of authentication used to stream logs to a LogstreamS3Endpoint. 

const (
	S3AccessKeyAuthentication S3AuthenticationType = "accesskey"
	S3RoleARNAuthentication   S3AuthenticationType = "rolearn"
)

type SSHCheckPeriod 

type SSHCheckPeriod time.Duration

SSHCheckPeriod wraps a time.Duration, allowing it to be JSON marshalled as a string like "20h" rather than a numeric value. It also supports the special value "always", which forces a check on every connection. 

const CheckPeriodAlways SSHCheckPeriod = -1

CheckPeriodAlways is a magic value corresponding to the SSHCheckPeriod "always". It indicates that re-authorization is required on every login.

func (SSHCheckPeriod) MarshalText 

func (d SSHCheckPeriod) MarshalText() ([]byte, error)

func (SSHCheckPeriod) String 

func (d SSHCheckPeriod) String() string

func (*SSHCheckPeriod) UnmarshalText 

func (d *SSHCheckPeriod) UnmarshalText(b []byte) error

type SetLogstreamConfigurationRequest 

type SetLogstreamConfigurationRequest struct {
	DestinationType      LogstreamEndpointType `json:"destinationType,omitempty"`
	URL                  string                `json:"url,omitempty"`
	User                 string                `json:"user,omitempty"`
	Token                string                `json:"token,omitempty"`
	UploadPeriodMinutes  int                   `json:"uploadPeriodMinutes,omitempty"`
	CompressionFormat    CompressionFormat     `json:"compressionFormat,omitempty"`
	S3Bucket             string                `json:"s3Bucket,omitempty"`
	S3Region             string                `json:"s3Region,omitempty"`
	S3KeyPrefix          string                `json:"s3KeyPrefix,omitempty"`
	S3AuthenticationType S3AuthenticationType  `json:"s3AuthenticationType,omitempty"`
	S3AccessKeyID        string                `json:"s3AccessKeyId,omitempty"`
	S3SecretAccessKey    string                `json:"s3SecretAccessKey,omitempty"`
	S3RoleARN            string                `json:"s3RoleArn,omitempty"`
	S3ExternalID         string                `json:"s3ExternalId,omitempty"`
}

SetLogstreamConfigurationRequest type defines a request for setting a LogstreamConfiguration.

type SplitDNSRequest 

type SplitDNSRequest map[string][]string

SplitDNSRequest is a map from domain names to a list of nameservers.

type SplitDNSResponse 

type SplitDNSResponse SplitDNSRequest

SplitDNSResponse is a map from domain names to a list of nameservers.

type TailnetSettings 

type TailnetSettings struct {
	DevicesApprovalOn      bool `json:"devicesApprovalOn"`
	DevicesAutoUpdatesOn   bool `json:"devicesAutoUpdatesOn"`
	DevicesKeyDurationDays int  `json:"devicesKeyDurationDays"` // days before device key expiry

	UsersApprovalOn                        bool                              `json:"usersApprovalOn"`
	UsersRoleAllowedToJoinExternalTailnets RoleAllowedToJoinExternalTailnets `json:"usersRoleAllowedToJoinExternalTailnets"`

	NetworkFlowLoggingOn        bool `json:"networkFlowLoggingOn"`
	RegionalRoutingOn           bool `json:"regionalRoutingOn"`
	PostureIdentityCollectionOn bool `json:"postureIdentityCollectionOn"`
}

TailnetSettings represents the current settings of a tailnet. See https://tailscale.com/api#model/tailnetsettings.

type TailnetSettingsResource 

type TailnetSettingsResource struct {
	*Client
}

TailnetSettingsResource provides access to https://tailscale.com/api#tag/tailnetsettings.

func (*TailnetSettingsResource) Get 

func (tsr *TailnetSettingsResource) Get(ctx context.Context) (*TailnetSettings, error)

Get retrieves the current TailnetSettings. See https://tailscale.com/api#tag/tailnetsettings/GET/tailnet/{tailnet}/settings.

func (*TailnetSettingsResource) Update 

func (tsr *TailnetSettingsResource) Update(ctx context.Context, request UpdateTailnetSettingsRequest) error

Update updates the tailnet settings. See https://tailscale.com/api#tag/tailnetsettings/PATCH/tailnet/{tailnet}/settings.

type Time 

type Time struct {
	time.Time
}

Time wraps a time and allows for unmarshalling timestamps that represent an empty time as an empty string (e.g "") this is used by the tailscale API when it returns devices that have no created date, such as its hello service.

func (Time) MarshalJSON 

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON is an implementation of json.Marshal.

func (*Time) UnmarshalJSON 

func (t *Time) UnmarshalJSON(data []byte) error

UnmarshalJSON unmarshals the content of data as a time.Time, a blank string will keep the time at its zero value.

type UpdateContactRequest 

type UpdateContactRequest struct {
	Email *string `json:"email,omitempty"`
}

UpdateContactRequest type defines the structure of a request to update a Contact.

type UpdatePostureIntegrationRequest 

type UpdatePostureIntegrationRequest struct {
	CloudID  string `json:"cloudId,omitempty"`
	ClientID string `json:"clientId,omitempty"`
	TenantID string `json:"tenantId,omitempty"`
	// ClientSecret may be omitted to preserve the existing value
	ClientSecret *string `json:"clientSecret,omitempty"`
}

UpdatePostureIntegrationRequest is a request to update a posture integration.

type UpdateTailnetSettingsRequest 

type UpdateTailnetSettingsRequest struct {
	DevicesApprovalOn      *bool `json:"devicesApprovalOn,omitempty"`
	DevicesAutoUpdatesOn   *bool `json:"devicesAutoUpdatesOn,omitempty"`
	DevicesKeyDurationDays *int  `json:"devicesKeyDurationDays,omitempty"` // days before device key expiry

	UsersApprovalOn                        *bool                              `json:"usersApprovalOn,omitempty"`
	UsersRoleAllowedToJoinExternalTailnets *RoleAllowedToJoinExternalTailnets `json:"usersRoleAllowedToJoinExternalTailnets,omitempty"`

	NetworkFlowLoggingOn        *bool `json:"networkFlowLoggingOn,omitempty"`
	RegionalRoutingOn           *bool `json:"regionalRoutingOn,omitempty"`
	PostureIdentityCollectionOn *bool `json:"postureIdentityCollectionOn,omitempty"`
}

UpdateTailnetSettingsRequest is a request to update the settings of a tailnet. Nil values indicate that the existing setting should be left unchanged.

type User 

type User struct {
	ID                 string     `json:"id"`
	DisplayName        string     `json:"displayName"`
	LoginName          string     `json:"loginName"`
	ProfilePicURL      string     `json:"profilePicUrl"`
	TailnetID          string     `json:"tailnetId"`
	Created            time.Time  `json:"created"`
	Type               UserType   `json:"type"`
	Role               UserRole   `json:"role"`
	Status             UserStatus `json:"status"`
	DeviceCount        int        `json:"deviceCount"`
	LastSeen           time.Time  `json:"lastSeen"`
	CurrentlyConnected bool       `json:"currentlyConnected"`
}

User is a representation of a user within a tailnet.

type UserRole 

type UserRole string

UserRole is the role of the user. 

const (
	UserRoleOwner        UserRole = "owner"
	UserRoleMember       UserRole = "member"
	UserRoleAdmin        UserRole = "admin"
	UserRoleITAdmin      UserRole = "it-admin"
	UserRoleNetworkAdmin UserRole = "network-admin"
	UserRoleBillingAdmin UserRole = "billing-admin"
	UserRoleAuditor      UserRole = "auditor"
)

type UserStatus 

type UserStatus string

UserStatus is the status of the user. 

const (
	UserStatusActive           UserStatus = "active"
	UserStatusIdle             UserStatus = "idle"
	UserStatusSuspended        UserStatus = "suspended"
	UserStatusNeedsApproval    UserStatus = "needs-approval"
	UserStatusOverBillingLimit UserStatus = "over-billing-limit"
)

type UserType 

type UserType string

UserType is the type of relation this user has to the tailnet associated with the request. 

const (
	UserTypeMember UserType = "member"
	UserTypeShared UserType = "shared"
)

type UsersResource 

type UsersResource struct {
	*Client
}

UsersResource provides access to https://tailscale.com/api#tag/users.

func (*UsersResource) Get 

func (ur *UsersResource) Get(ctx context.Context, id string) (*User, error)

Get retrieves the User identified by the given id.

func (*UsersResource) List 

func (ur *UsersResource) List(ctx context.Context, userType *UserType, role *UserRole) ([]User, error)

List lists every User of the tailnet. If userType and/or role are provided, the list of users will be filtered by those.

type Webhook 

type Webhook struct {
	EndpointID       string                    `json:"endpointId"`
	EndpointURL      string                    `json:"endpointUrl"`
	ProviderType     WebhookProviderType       `json:"providerType"`
	CreatorLoginName string                    `json:"creatorLoginName"`
	Created          time.Time                 `json:"created"`
	LastModified     time.Time                 `json:"lastModified"`
	Subscriptions    []WebhookSubscriptionType `json:"subscriptions"`
	// Secret is only populated on Webhook creation and after secret rotation.
	Secret *string `json:"secret,omitempty"`
}

Webhook type defines a webhook endpoint within a tailnet.

type WebhookProviderType 

type WebhookProviderType string

WebhookProviderType defines the provider type for a Webhook destination. 

const (
	WebhookEmptyProviderType      WebhookProviderType = ""
	WebhookSlackProviderType      WebhookProviderType = "slack"
	WebhookMattermostProviderType WebhookProviderType = "mattermost"
	WebhookGoogleChatProviderType WebhookProviderType = "googlechat"
	WebhookDiscordProviderType    WebhookProviderType = "discord"
)

type WebhookSubscriptionType 

type WebhookSubscriptionType string

WebhookSubscriptionType defines events in tailscale to subscribe a Webhook to. 

const (
	// WebhookCategoryTailnetManagement implies the entire group of events below.
	// Note that subscribing to WebhookCategoryTailnetManagement will include any
	// future events added below.
	WebhookCategoryTailnetManagement WebhookSubscriptionType = "categoryTailnetManagement"
	WebhookNodeCreated               WebhookSubscriptionType = "nodeCreated"
	WebhookNodeNeedsApproval         WebhookSubscriptionType = "nodeNeedsApproval"
	WebhookNodeApproved              WebhookSubscriptionType = "nodeApproved"
	WebhookNodeKeyExpiringInOneDay   WebhookSubscriptionType = "nodeKeyExpiringInOneDay"
	WebhookNodeKeyExpired            WebhookSubscriptionType = "nodeKeyExpired"
	WebhookNodeDeleted               WebhookSubscriptionType = "nodeDeleted"
	WebhookPolicyUpdate              WebhookSubscriptionType = "policyUpdate"
	WebhookUserCreated               WebhookSubscriptionType = "userCreated"
	WebhookUserNeedsApproval         WebhookSubscriptionType = "userNeedsApproval"
	WebhookUserSuspended             WebhookSubscriptionType = "userSuspended"
	WebhookUserRestored              WebhookSubscriptionType = "userRestored"
	WebhookUserDeleted               WebhookSubscriptionType = "userDeleted"
	WebhookUserApproved              WebhookSubscriptionType = "userApproved"
	WebhookUserRoleUpdated           WebhookSubscriptionType = "userRoleUpdated"
)
const (
	// WebhookCategoryDeviceMisconfigurations implies the entire group of events below.
	// Note that subscribing to WebhookCategoryDeviceMisconfigurations will include any
	// future events added below.
	WebhookCategoryDeviceMisconfigurations WebhookSubscriptionType = "categoryDeviceMisconfigurations"
	WebhookSubnetIPForwardingNotEnabled    WebhookSubscriptionType = "subnetIPForwardingNotEnabled"
	WebhookExitNodeIPForwardingNotEnabled  WebhookSubscriptionType = "exitNodeIPForwardingNotEnabled"
)

type WebhooksResource 

type WebhooksResource struct {
	*Client
}

WebhooksResource provides access to https://tailscale.com/api#tag/webhooks.

func (*WebhooksResource) Create 

func (wr *WebhooksResource) Create(ctx context.Context, request CreateWebhookRequest) (*Webhook, error)

Create creates a new Webhook with the specifications provided in the CreateWebhookRequest. Returns the created Webhook if successful.

func (*WebhooksResource) Delete 

func (wr *WebhooksResource) Delete(ctx context.Context, endpointID string) error

Delete deletes a specific webhook.

func (*WebhooksResource) Get 

func (wr *WebhooksResource) Get(ctx context.Context, endpointID string) (*Webhook, error)

Get retrieves a specific Webhook.

func (*WebhooksResource) List 

func (wr *WebhooksResource) List(ctx context.Context) ([]Webhook, error)

List lists every Webhook in the tailnet.

func (*WebhooksResource) RotateSecret 

func (wr *WebhooksResource) RotateSecret(ctx context.Context, endpointID string) (*Webhook, error)

RotateSecret rotates the secret associated with a webhook. A new secret will be generated and set on the returned Webhook.

func (*WebhooksResource) Test 

func (wr *WebhooksResource) Test(ctx context.Context, endpointID string) error

Test queues a test event to be sent to a specific webhook. Sending the test event is an asynchronous operation which will typically happen a few seconds after using this method.

func (*WebhooksResource) Update 

func (wr *WebhooksResource) Update(ctx context.Context, endpointID string, subscriptions []WebhookSubscriptionType) (*Webhook, error)

Update updates an existing webhook's subscriptions. Returns the updated Webhook on success.

Source Files

View all Source files

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.