tunneld

Documentation

Index

• Constants
• Variables
• type API
  • func New(options *Options) (*API, error)
  • func (api *API) Close() error
  • func (api *API) Router() http.Handler
• type LegacyPostTunRequest
• type LegacyPostTunResponse
• type Options
  • func (options *Options) HostnameToWireguardIP(hostname string) (netip.Addr, error)
  • func (options *Options) Validate() error
  • func (options *Options) WireguardPublicKeyToIPAndURLs(publicKey device.NoisePublicKey, version tunnelsdk.TunnelVersion) (netip.Addr, []*url.URL)

Constants

const (
	DefaultWireguardMTU     = 1280
	DefaultPeerDialTimeout  = 10 * time.Second
	DefaultPeerPollDuration = 30 * time.Second
	DefaultPeerTimeout      = 2 * time.Minute
)

Variables

var (
	DefaultWireguardServerIP      = netip.MustParseAddr("fcca::1")
	DefaultWireguardNetworkPrefix = netip.MustParsePrefix("fcca::/16")
)

Types

type API

type API struct {
	*Options
	// contains filtered or unexported fields
}

TODO: add logging to API

func New

func New(options *Options) (*API, error)

func (*API) Close

func (api *API) Close() error

func (*API) Router

func (api *API) Router() http.Handler

type LegacyPostTunRequest

type LegacyPostTunRequest struct {
	PublicKey device.NoisePublicKey `json:"public_key"`
}

type LegacyPostTunResponse

type LegacyPostTunResponse struct {
	Hostname        string     `json:"hostname"`
	ServerEndpoint  string     `json:"server_endpoint"`
	ServerIP        netip.Addr `json:"server_ip"`
	ServerPublicKey string     `json:"server_public_key"` // hex
	ClientIP        netip.Addr `json:"client_ip"`
}

type Options

type Options struct {
	Log slog.Logger

	// BaseURL is the base URL to use for the tunnel, including scheme. All
	// tunnels will be subdomains of this hostname.
	// e.g. "https://tunnel.example.com" will place tunnels at
	//      "https://xyz.tunnel.example.com"
	BaseURL *url.URL

	// WireguardEndpoint is the UDP address advertised to clients that they will
	// connect to for wireguard connections. It should be in the form
	// "$ip:$port" or "$hostname:$port".
	WireguardEndpoint string
	// WireguardPort is the UDP port that the wireguard server will listen on.
	// It should be the same as the port in WireguardEndpoint.
	WireguardPort uint16
	// WireguardKey is the private key for the wireguard server.
	WireguardKey tunnelsdk.Key

	// WireguardMTU is the MTU to use for the wireguard interface. Defaults to
	// 1280.
	WireguardMTU int
	// WireguardServerIP is the virtual IP address of this server in the
	// wireguard network. Must be an IPv6 address contained within
	// WireguardNetworkPrefix. Defaults to fcca::1.
	WireguardServerIP netip.Addr
	// WireguardNetworkPrefix is the CIDR of the wireguard network. All client
	// IPs will be generated within this network. Must be a IPv6 CIDR and have
	// at least 64 bits of space available. Defaults to fcca::/16.
	WireguardNetworkPrefix netip.Prefix

	// RealIPHeader is the header to use for getting a request's IP address. If
	// not set, the request's RemoteAddr will be used.
	//
	// Used for rate limiting.
	RealIPHeader string

	// PeerDialTimeout is the timeout for dialing a peer on a request. Defaults
	// to 10 seconds.
	PeerDialTimeout time.Duration

	// PeerRegisterInterval is how often the clients should re-register.
	PeerRegisterInterval time.Duration

	// PeerTimeout is how long the server will wait before removing the peer.
	PeerTimeout time.Duration
}

func (*Options) HostnameToWireguardIP

func (options *Options) HostnameToWireguardIP(hostname string) (netip.Addr, error)

HostnameToWireguardIP returns the wireguard IP address that corresponds to a given encoded hostname label as returned by WireguardPublicKeyToIPAndURLs.

func (*Options) Validate

func (options *Options) Validate() error

Validate checks that the options are valid and populates default values for missing fields.

func (*Options) WireguardPublicKeyToIPAndURLs

func (options *Options) WireguardPublicKeyToIPAndURLs(publicKey device.NoisePublicKey, version tunnelsdk.TunnelVersion) (netip.Addr, []*url.URL)

WireguardPublicKeyToIPAndURLs returns the IP address that corresponds to the given wireguard public key, as well as all accepted tunnel URLs for the key.

We support an older 32 character format ("old format") and a newer 12 character format ("good format") which is preferred. The first URL returned should be considered "preferred", and all other URLs are provided for compatibility with older deployments only. The "good format" is preferred as it's shorter to avoid issues with hostname length limits when apps prefixes are added to the equation.

"good format":

Take the first 8 bytes of the hash of the public key, and convert to
base32.

"old format":

Take the network prefix, and create a new address filling the last n bytes
with the first n bytes of the hash of the public key. Then convert to hex.