Tailscale (Tailscale v0.3.3)

View Source

Elixir bindings for the Tailscale Rust client.

Nomenclature (devices, peers, nodes, etc.)

In our parlance, anything that shows up on console.tailscale.com and gets a tailnet IP is known canonically as a "device", though these are also variously been referred to as "nodes" or "peers". Conventionally, each of these would be a device running tailscaled, but with the advent of tsnet and now tailscale-rs and its derivative cross-language clients, a single computer can have many Tailscale connections simultaneously, possibly to many different tailnets. As an attempt to capture the whole ontology of "things that have a persistent identity and tailnet IP", we try to refer to them uniformly by the umbrella term "device".

Summary

Types

ip4_addr()

An IPv4 address.

ip6_addr()

An IPv6 address.

ip_addr()

An IP address (v4 or v6).

options()

Options for connecting to Tailscale

t()

Handle to a tailscale "device", i.e. a unique tailnet-connected identity with a network address. See the note in connect/2 about nomenclature for more details.

Functions

connect(options \\ [])

Open a connection to Tailscale, creating a device connected to a tailnet. If the argument is a String, this is equivalent to connect/2 with an empty option list.

connect(key_file_path, options)

Open a connection to tailscale, creating a device connected to a tailnet. Loads key state from the given path, creating it if it doesn't exist.

ipv4_addr(dev)

Get the current IPv4 address of this Tailscale node.

ipv6_addr(dev)

Get the current IPv6 address of this Tailscale node.

peer_by_name(dev, name)

Look up a peer by name.

peer_by_tailnet_ip(dev, ip)

Look up the peer with the given tailnet IP address.

peers_with_route(dev, ip)

Retrieve the most narrow set of peers that accept packets for the specified IP.

self_node(dev)

Get this node's Tailscale.NodeInfo.

Types

ip4_addr()

@type ip4_addr() :: :inet.ip4_address() | String.t()

An IPv4 address.

tailscale is capable of interpreting either the :inet format or a String.

ip6_addr()

@type ip6_addr() :: :inet.ip6_address() | String.t()

An IPv6 address.

tailscale is capable of interpreting either the :inet format or a String.

ip_addr()

@type ip_addr() :: ip4_addr() | ip6_addr()

An IP address (v4 or v6).

tailscale is capable of interpreting either the :inet format or a String.

options()

@type options() :: [
  auth_key: String.t(),
  keys: Tailscale.Keystate.t(),
  control_url: String.t(),
  hostname: String.t(),
  tags: [String.t()]
]

Options for connecting to Tailscale:

  • auth_key: the auth key to use to authorize this device. You only need to supply this if the device's keys aren't authorized.
  • keys: the Tailscale.Keystate to use to connect. This defines the device identity.
  • hostname: the hostname this device will request. If omitted, uses the hostname the OS reports.
  • tags: tags the device will request.
  • control_url: the url of the control server to use.

t()

@opaque t()

Handle to a tailscale "device", i.e. a unique tailnet-connected identity with a network address. See the note in connect/2 about nomenclature for more details.

Functions

connect(options \\ [])

@spec connect(options() | String.t()) :: {:ok, t()} | {:error, any()}

Open a connection to Tailscale, creating a device connected to a tailnet. If the argument is a String, this is equivalent to connect/2 with an empty option list.

See options/0 for details on available options. You may want to call connect/2 for an easier way to load key state from a file.

connect(key_file_path, options)

@spec connect(String.t(), options()) :: {:ok, t()} | {:error, any()}

Open a connection to tailscale, creating a device connected to a tailnet. Loads key state from the given path, creating it if it doesn't exist.

See options/0 for details on available options.

ipv4_addr(dev)

@spec ipv4_addr(t()) :: {:ok, :inet.ip4_address()} | {:error, any()}

Get the current IPv4 address of this Tailscale node.

Blocks until the address is available.

ipv6_addr(dev)

@spec ipv6_addr(t()) :: {:ok, :inet.ip6_address()} | {:error, any()}

Get the current IPv6 address of this Tailscale node.

Blocks until the address is available.

Note that this address is in :inet.ip6_address/0 format (16-bit segments), which may be difficult to read. See :inet.ntoa/1 to format to a string.

peer_by_name(dev, name)

@spec peer_by_name(t(), String.t()) ::
  {:ok, Tailscale.NodeInfo.t() | nil} | {:error, any()}

Look up a peer by name.

Returns {:ok, nil} if there was no such peer, and {:error, reason} if the lookup encountered an error.

peer_by_tailnet_ip(dev, ip)

@spec peer_by_tailnet_ip(t(), ip_addr()) ::
  {:ok, Tailscale.NodeInfo.t() | nil} | {:error, any()}

Look up the peer with the given tailnet IP address.

Returns {:ok, nil} if there was no such peer. :error if the lookup encountered an error.

peers_with_route(dev, ip)

@spec peers_with_route(t(), ip_addr()) ::
  {:ok, [Tailscale.NodeInfo.t()]} | {:error, any()}

Retrieve the most narrow set of peers that accept packets for the specified IP.

self_node(dev)

@spec self_node(t()) :: {:ok, Tailscale.NodeInfo.t()} | {:error, any()}

Get this node's Tailscale.NodeInfo.