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 ¶
- func IsNotFound(err error) bool
- type ACL
- type ACLAutoApprovers
- type ACLDERPMap
- type ACLDERPNode
- type ACLDERPRegion
- type ACLEntry
- type ACLSSH
- type ACLTest
- type APIError
- type APIErrorData
- type Client
- func (c *Client) ACL(ctx context.Context) (*ACL, error)
- func (c *Client) AuthorizeDevice(ctx context.Context, deviceID string) error
- func (c *Client) CreateKey(ctx context.Context, capabilities KeyCapabilities, opts ...CreateKeyOption) (Key, error)
- func (c *Client) DNSNameservers(ctx context.Context) ([]string, error)
- func (c *Client) DNSPreferences(ctx context.Context) (*DNSPreferences, error)
- func (c *Client) DNSSearchPaths(ctx context.Context) ([]string, error)
- func (c *Client) DeleteDevice(ctx context.Context, deviceID string) error
- func (c *Client) DeleteKey(ctx context.Context, id string) error
- func (c *Client) DeviceSubnetRoutes(ctx context.Context, deviceID string) (*DeviceRoutes, error)
- func (c *Client) Devices(ctx context.Context) ([]Device, error)
- func (c *Client) GetKey(ctx context.Context, id string) (Key, error)
- func (c *Client) Keys(ctx context.Context) ([]Key, error)
- func (c *Client) RawACL(ctx context.Context) (string, error)
- func (c *Client) SetACL(ctx context.Context, acl any, opts ...SetACLOption) error
- func (c *Client) SetDNSNameservers(ctx context.Context, dns []string) error
- func (c *Client) SetDNSPreferences(ctx context.Context, preferences DNSPreferences) error
- func (c *Client) SetDNSSearchPaths(ctx context.Context, searchPaths []string) error
- func (c *Client) SetDeviceAuthorized(ctx context.Context, deviceID string, authorized bool) error
- func (c *Client) SetDeviceKey(ctx context.Context, deviceID string, key DeviceKey) error
- func (c *Client) SetDeviceSubnetRoutes(ctx context.Context, deviceID string, routes []string) error
- func (c *Client) SetDeviceTags(ctx context.Context, deviceID string, tags []string) error
- func (c *Client) SetSplitDNS(ctx context.Context, request SplitDnsRequest) error
- func (c *Client) SplitDNS(ctx context.Context) (SplitDnsResponse, error)
- func (c *Client) UpdateSplitDNS(ctx context.Context, request SplitDnsRequest) (SplitDnsResponse, error)
- func (c *Client) ValidateACL(ctx context.Context, acl any) error
- type ClientOption
- type CreateKeyOption
- type CreateKeyRequest
- type DNSPreferences
- type Device
- type DeviceKey
- type DeviceRoutes
- type Duration
- type Key
- type KeyCapabilities
- type NodeAttrGrant
- type NodeAttrGrantApp
- type SetACLOption
- type SplitDnsRequest
- type SplitDnsResponse
- type Time
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsNotFound ¶
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 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.
type APIErrorData ¶
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) AuthorizeDevice ¶
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 ¶
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 ¶
DNSSearchPaths retrieves the list of search paths that is currently set for the given tailnet.
func (*Client) DeleteDevice ¶
DeleteDevice deletes the device given its deviceID.
func (*Client) DeviceSubnetRoutes ¶
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) GetKey ¶
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
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
RawACL retrieves the ACL that is currently set for the given tailnet as a HuJSON string.
func (*Client) SetACL ¶
SetACL sets the ACL for the given tailnet. `acl` can either be an ACL, or a HuJSON string.
func (*Client) SetDNSNameservers ¶
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 ¶
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
SetDeviceAuthorized marks the specified device as authorized or not.
func (*Client) SetDeviceKey ¶
SetDeviceKey updates the properties of a device's key.
func (*Client) SetDeviceSubnetRoutes ¶
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 ¶
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.
type ClientOption ¶
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 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 (*Duration) UnmarshalText ¶ added in v1.8.0
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 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
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 ¶
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 ¶
MarshalJSON is an implementation of json.Marshal.
func (*Time) UnmarshalJSON ¶
UnmarshalJSON unmarshals the content of data as a time.Time, a blank string will keep the time at its zero value.