tailscale

package
v1.17.0 Latest Latest
Warning

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

 Go to latest Published: Apr 29, 2024 License: MIT Imports: 11 Imported by: 17

Documentation

Overview

Package tailscale contains a basic implementation of a client for the Tailscale HTTP api. Documentation is here: https://github.com/tailscale/tailscale/blob/main/api.md

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.

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"`
}

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"`
	InsecureForTests bool   `json:"insecureForRests,omitempty" hujson:"InsecureForTests,omitempty"`
	STUNTestIP       string `json:"stunTestIP,omitempty" hujson:"STUNTestIP,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     Duration `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 Client 

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

Client type is used to perform actions against the Tailscale API.

func NewClient 

func NewClient(apiKey, tailnet string, options ...ClientOption) (*Client, error)

NewClient returns a new instance of the Client type that will perform operations against a chosen tailnet and will provide the apiKey for authorization. Additional options can be provided, see ClientOption for more details.

To use OAuth Client credentials pass an empty string as apiKey and use WithOAuthClientCredentials() as below: 

client, err := tailscale.NewClient(
"",
tailnet,
tailscale.WithOAuthClientCredentials(oauthClientID, oauthClientSecret, oauthScopes),
)

func (*Client) ACL 

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

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

func (*Client) AuthorizeDevice 

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

AuthorizeDevice marks the specified device identifier as authorized to join the tailnet.

func (*Client) CreateKey 

func (c *Client) CreateKey(ctx context.Context, capabilities KeyCapabilities, opts ...CreateKeyOption) (Key, error)

CreateKey creates a new authentication key with the capabilities selected via the KeyCapabilities type. Returns the generated key if successful.

func (*Client) DNSNameservers 

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

DNSNameservers lists the DNS nameservers for a tailnet

func (*Client) DNSPreferences 

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

DNSPreferences retrieves the DNS preferences that are currently set for the given tailnet. Supply the tailnet of interest in the path.

func (*Client) DNSSearchPaths 

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

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

func (*Client) DeleteDevice 

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

DeleteDevice deletes the device given its deviceID.

func (*Client) DeleteKey 

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

DeleteKey removes an authentication key from the tailnet.

func (*Client) DeviceSubnetRoutes 

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

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

func (*Client) Devices 

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

Devices lists the devices in a tailnet.

func (*Client) GetKey 

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

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

func (*Client) Keys added in v1.7.0 

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

Keys returns all keys 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.

func (*Client) RawACL added in v1.16.0 

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

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

func (*Client) SetACL 

func (c *Client) SetACL(ctx context.Context, acl any, opts ...SetACLOption) error

SetACL sets the ACL for the given tailnet. `acl` can either be an ACL, or a HuJSON string.

func (*Client) SetDNSNameservers 

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

SetDNSNameservers 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 (*Client) SetDNSPreferences 

func (c *Client) SetDNSPreferences(ctx context.Context, preferences DNSPreferences) error

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

func (*Client) SetDNSSearchPaths 

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

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

func (*Client) SetDeviceAuthorized added in v1.10.0 

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

SetDeviceAuthorized marks the specified device as authorized or not.

func (*Client) SetDeviceKey 

func (c *Client) SetDeviceKey(ctx context.Context, deviceID string, key DeviceKey) error

SetDeviceKey updates the properties of a device's key.

func (*Client) SetDeviceSubnetRoutes 

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

SetDeviceSubnetRoutes 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).

func (*Client) SetDeviceTags 

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

SetDeviceTags updates the tags of a target device.

func (*Client) SetSplitDNS added in v1.17.0 

func (c *Client) SetSplitDNS(ctx context.Context, request SplitDnsRequest) error

SetSplitDNS sets the split DNS settings for a 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 (*Client) SplitDNS added in v1.17.0 

func (c *Client) SplitDNS(ctx context.Context) (SplitDnsResponse, error)

SplitDNS retrieves the split DNS configuration for a tailnet.

func (*Client) UpdateSplitDNS added in v1.17.0 

func (c *Client) UpdateSplitDNS(ctx context.Context, request SplitDnsRequest) (SplitDnsResponse, error)

UpdateSplitDNS updates the split DNS settings for a 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.

func (*Client) ValidateACL added in v1.7.0 

func (c *Client) ValidateACL(ctx context.Context, acl any) error

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

type ClientOption 

type ClientOption func(c *Client) error

ClientOption type is a function that is used to modify a Client.

func WithBaseURL 

func WithBaseURL(baseURL string) ClientOption

WithBaseURL sets a custom baseURL for the Tailscale API, this is primarily used for testing purposes.

func WithOAuthClientCredentials added in v1.9.0 

func WithOAuthClientCredentials(clientID, clientSecret string, scopes []string) ClientOption

WithOAuthClientCredentials sets the OAuth Client Credentials to use for the Tailscale API.

func WithUserAgent added in v1.11.0 

func WithUserAgent(ua string) ClientOption

WithUserAgent sets a custom User-Agent header in HTTP requests. Passing an empty string will make the client use Go's default value.

type CreateKeyOption added in v1.8.0 

type CreateKeyOption func(c *CreateKeyRequest) error

CreateKeyOption type is a function that is used to modify a CreateKeyRequest.

func WithKeyDescription added in v1.10.0 

func WithKeyDescription(desc string) CreateKeyOption

WithKeyDescription sets the description for the key.

func WithKeyExpiry added in v1.8.0 

func WithKeyExpiry(e time.Duration) CreateKeyOption

WithKeyExpiry sets how long the key is valid for.

type CreateKeyRequest added in v1.8.0 

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

CreateKeyRequest type describes the definition of an authentication key to create.

type DNSPreferences 

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

type Device 

type Device struct {
	Addresses                 []string `json:"addresses"`
	Name                      string   `json:"name"`
	ID                        string   `json:"id"`
	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"`
	UpdateAvailable           bool     `json:"updateAvailable"`
}

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 DeviceRoutes 

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

type Duration 

type Duration time.Duration

Duration type wraps a time.Duration, allowing it to be JSON marshalled as a string like "20h" rather than a numeric value.

func (Duration) MarshalText added in v1.8.0 

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

func (Duration) String added in v1.8.0 

func (d Duration) String() string

func (*Duration) UnmarshalText added in v1.8.0 

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

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"`
}

Key type 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 type describes the capabilities of an authentication key.

type NodeAttrGrant added in v1.8.0 

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 added in v1.15.0 

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 SetACLOption added in v1.8.0 

type SetACLOption func(p *setACLParams)

func WithETag added in v1.8.0 

func WithETag(etag string) SetACLOption

WithETag allows passing an ETag value with Set ACL API call that will be used in the `If-Match` HTTP request header.

type SplitDnsRequest added in v1.17.0 

type SplitDnsRequest map[string][]string

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

type SplitDnsResponse added in v1.17.0 

type SplitDnsResponse SplitDnsRequest

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

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.

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.