Documentation
¶
Overview ¶
Package tsnet provides Tailscale as a library.
Index ¶
- type FallbackTCPHandler
- type FunnelOption
- type Server
- func (s *Server) APIClient() (*tailscale.Client, error)
- func (s *Server) CapturePcap(ctx context.Context, pcapFile string) error
- func (s *Server) CertDomains() []string
- func (s *Server) Close() error
- func (s *Server) Dial(ctx context.Context, network, address string) (net.Conn, error)
- func (s *Server) HTTPClient() *http.Client
- func (s *Server) Listen(network, addr string) (net.Listener, error)
- func (s *Server) ListenFunnel(network, addr string, opts ...FunnelOption) (net.Listener, error)
- func (s *Server) ListenPacket(network, addr string) (net.PacketConn, error)
- func (s *Server) ListenTLS(network, addr string) (net.Listener, error)
- func (s *Server) LocalClient() (*tailscale.LocalClient, error)
- func (s *Server) Loopback() (addr string, proxyCred, localAPICred string, err error)
- func (s *Server) RegisterFallbackTCPHandler(cb FallbackTCPHandler) func()
- func (s *Server) Start() error
- func (s *Server) TailscaleIPs() (ip4, ip6 netip.Addr)
- func (s *Server) Up(ctx context.Context) (*ipnstate.Status, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type FallbackTCPHandler ¶
FallbackTCPHandler describes the callback which conditionally handles an incoming TCP flow for the provided (src/port, dst/port) 4-tuple. These are registered as handlers of last resort, and are called only if no listener could handle the incoming flow.
If the callback returns intercept=false, the flow is rejected.
When intercept=true, the behavior depends on whether the returned handler is non-nil: if nil, the connection is rejected. If non-nil, handler takes over the TCP conn.
type FunnelOption ¶
type FunnelOption interface {
// contains filtered or unexported methods
}
FunnelOption is an option passed to ListenFunnel to configure the listener.
func FunnelOnly ¶
func FunnelOnly() FunnelOption
FunnelOnly configures the listener to only respond to connections from Tailscale Funnel. The local tailnet will not be able to connect to the listener.
type Server ¶
type Server struct {
// Dir specifies the name of the directory to use for
// state. If empty, a directory is selected automatically
// under os.UserConfigDir (https://golang.org/pkg/os/#UserConfigDir).
// based on the name of the binary.
//
// If you want to use multiple tsnet services in the same
// binary, you will need to make sure that Dir is set uniquely
// for each service. A good pattern for this is to have a
// "base" directory (such as your mutable storage folder) and
// then append the hostname on the end of it.
Dir string
// Store specifies the state store to use.
//
// If nil, a new FileStore is initialized at `Dir/tailscaled.state`.
// See tailscale.com/ipn/store for supported stores.
//
// Logs will automatically be uploaded to log.tailscale.io,
// where the configuration file for logging will be saved at
// `Dir/tailscaled.log.conf`.
Store ipn.StateStore
// Hostname is the hostname to present to the control server.
// If empty, the binary name is used.
Hostname string
// UserLogf, if non-nil, specifies the logger to use for logs generated by
// the Server itself intended to be seen by the user such as the AuthURL for
// login and status updates. If unset, log.Printf is used.
UserLogf logger.Logf
// Logf, if set is used for logs generated by the backend such as the
// LocalBackend and MagicSock. It is verbose and intended for debugging.
// If unset, logs are discarded.
Logf logger.Logf
// Ephemeral, if true, specifies that the instance should register
// as an Ephemeral node (https://tailscale.com/s/ephemeral-nodes).
Ephemeral bool
// AuthKey, if non-empty, is the auth key to create the node
// and will be preferred over the TS_AUTHKEY environment
// variable. If the node is already created (from state
// previously stored in Store), then this field is not
// used.
AuthKey string
// AdvertiseTags are the Tailscale tags this node should advertise.
AdvertiseTags []string
// ControlURL optionally specifies the coordination server URL.
// If empty, the Tailscale default is used.
ControlURL string
// RunWebClient, if true, runs a client for managing this node over
// its Tailscale interface on port 5252.
RunWebClient bool
// Port is the UDP port to listen on for WireGuard and peer-to-peer
// traffic. If zero, a port is automatically selected. Leave this
// field at zero unless you know what you are doing.
Port uint16
// contains filtered or unexported fields
}
Server is an embedded Tailscale server.
Its exported fields may be changed until the first method call.
func (*Server) APIClient ¶
APIClient returns a tailscale.Client that can be used to make authenticated requests to the Tailscale control server. It requires the user to set tailscale.I_Acknowledge_This_API_Is_Unstable.
func (*Server) CapturePcap ¶
CapturePcap can be called by the application code compiled with tsnet to save a pcap of packets which the netstack within tsnet sees. This is expected to be useful during debugging, probably not useful for production.
Packets will be written to the pcap until the process exits. The pcap needs a Lua dissector to be installed in WireShark in order to decode properly: wgengine/capture/ts-dissector.lua in this repository. https://tailscale.com/kb/1023/troubleshooting/#can-i-examine-network-traffic-inside-the-encrypted-tunnel
func (*Server) CertDomains ¶
CertDomains returns the list of domains for which the server can provide TLS certificates. These are also the DNS names for the Server. If the server is not running, it returns nil.
func (*Server) Close ¶
Close stops the server.
It must not be called before or concurrently with Start.
func (*Server) Dial ¶
Dial connects to the address on the tailnet. It will start the server if it has not been started yet.
func (*Server) HTTPClient ¶
HTTPClient returns an HTTP client that is configured to connect over Tailscale.
This is useful if you need to have your tsnet services connect to other devices on your tailnet.
func (*Server) Listen ¶
Listen announces only on the Tailscale network. It will start the server if it has not been started yet.
Listeners which do not specify an IP address will match for traffic for the local node (that is, a destination address of the IPv4 or IPv6 address of this node) only. To listen for traffic on other addresses such as those routed inbound via subnet routes, explicitly specify the listening address or use RegisterFallbackTCPHandler.
func (*Server) ListenFunnel ¶
ListenFunnel announces on the public internet using Tailscale Funnel.
It also by default listens on your local tailnet, so connections can come from either inside or outside your network. To restrict connections to be just from the internet, use the FunnelOnly option.
Currently (2023-03-10), Funnel only supports TCP on ports 443, 8443, and 10000. The supported host name is limited to that configured for the tsnet.Server. As such, the standard way to create funnel is:
s.ListenFunnel("tcp", ":443")
and the only other supported addrs currently are ":8443" and ":10000".
It will start the server if it has not been started yet.
func (*Server) ListenPacket ¶
func (s *Server) ListenPacket(network, addr string) (net.PacketConn, error)
ListenPacket announces on the Tailscale network.
The network must be "udp", "udp4" or "udp6". The addr must be of the form "ip:port" (or "[ip]:port") where ip is a valid IPv4 or IPv6 address corresponding to "udp4" or "udp6" respectively. IP must be specified.
If s has not been started yet, it will be started.
func (*Server) ListenTLS ¶
ListenTLS announces only on the Tailscale network. It returns a TLS listener wrapping the tsnet listener. It will start the server if it has not been started yet.
func (*Server) LocalClient ¶
func (s *Server) LocalClient() (*tailscale.LocalClient, error)
LocalClient returns a LocalClient that speaks to s.
It will start the server if it has not been started yet. If the server's already been started successfully, it doesn't return an error.
func (*Server) Loopback ¶
Loopback starts a routing server on a loopback address.
The server has multiple functions.
It can be used as a SOCKS5 proxy onto the tailnet. Authentication is required with the username "tsnet" and the value of proxyCred used as the password.
The HTTP server also serves out the "LocalAPI" on /localapi. As the LocalAPI is powerful, access to endpoints requires BOTH passing a "Sec-Tailscale: localapi" HTTP header and passing localAPICred as basic auth.
If you only need to use the LocalAPI from Go, then prefer LocalClient as it does not require communication via TCP.
func (*Server) RegisterFallbackTCPHandler ¶
func (s *Server) RegisterFallbackTCPHandler(cb FallbackTCPHandler) func()
RegisterFallbackTCPHandler registers a callback which will be called to handle a TCP flow to this tsnet node, for which no listeners will handle.
If multiple fallback handlers are registered, they will be called in an undefined order. See FallbackTCPHandler for details on handling a flow.
The returned function can be used to deregister this callback.
func (*Server) Start ¶
Start connects the server to the tailnet. Optional: any calls to Dial/Listen will also call Start.
func (*Server) TailscaleIPs ¶
TailscaleIPs returns IPv4 and IPv6 addresses for this node. If the node has not yet joined a tailnet or is otherwise unaware of its own IP addresses, the returned ip4, ip6 will be !netip.IsValid().
Source Files