README
¶
tsp
tsp is a low-level Tailscale protocol tool for performing composable
building-block operations: generating keys, discovering server public keys,
and registering nodes with a coordination server.
Library
The tsp Go package provides a client for
speaking the Tailscale protocol to a coordination server.
See https://pkg.go.dev/github.com/bradfitz/tsp for that.
CLI
The CLI wraps the library to let you do each operation.
Install
go install github.com/bradfitz/tsp/cmd/tsp@latest
Commands
new-machine-key
Generate a new machine key.
tsp new-machine-key [-o file]
new-node-key
Generate a new node key.
tsp new-node-key [-o file]
discover-server-key
Discover and print the coordination server's public key.
tsp [-s url] discover-server-key [-o file]
new-node
Generate a new node JSON file bundling machine key, node key, server URL,
and server public key. If -n or -m are omitted, new keys are generated.
The server key is discovered automatically unless --control-key is given.
tsp [-s url] [--control-key file] new-node [-n node-key-file] [-m machine-key-file] [-o output]
The resulting JSON file looks like:
{
"node_key": "node-privkey:...",
"machine_key": "machine-privkey:...",
"server_url": "https://controlplane.tailscale.com",
"server_key": "mkey:..."
}
register
Register a node with a coordination server using a node JSON file.
tsp [-s url] [--control-key file] register -n <node-file> [flags]
Flags:
-n <file> Node JSON file (required)
-o <file> Output file (default: stdout)
--hostname <name> Hostname to register
--ephemeral Register as ephemeral node
--auth-key <key> Pre-authorized auth key
--tags <tags> Comma-separated ACL tags
map
Send a map request to the coordination server.
tsp [-s url] [--control-key file] map -n <node-file> [-stream] [-peers=false] [-o file]
Flags:
-n <file> Node JSON file (required)
-o <file> Output file (default: stdout)
-stream Stream map responses
-peers Include peers in response (default: true)
Example workflow
Using a node file (recommended):
# Generate a node file (discovers server key automatically)
tsp new-node -o node.json
# Register
tsp register -n node.json --auth-key tskey-auth-...
# Get inital map response & exit
tsp map -n node.json
# Get map response + stream of updates, forever
tsp map -n node.json -stream
Using pre-existing key files:
# Generate keys separately
tsp new-machine-key -o machine.key
tsp new-node-key -o node.key
# Bundle into a node file
tsp new-node -m machine.key -n node.key -o node.json
# Register and map using the node file
tsp register -n node.json --auth-key tskey-auth-...
tsp map -n node.json
Documentation
¶
Overview ¶
Package tsp provides a client for speaking the Tailscale protocol to a coordination server over Noise.
Index ¶
- Constants
- func DiscoverServerKey(ctx context.Context, serverURL string) (key.MachinePublic, error)
- type Client
- func (c *Client) AnswerC2NPing(ctx context.Context, pr *tailcfg.PingRequest, ...) (handled bool)
- func (c *Client) Close() error
- func (c *Client) DiscoverServerKey(ctx context.Context) (key.MachinePublic, error)
- func (c *Client) Map(ctx context.Context, opts MapOpts) (*MapSession, error)
- func (c *Client) Register(ctx context.Context, opts RegisterOpts) (*tailcfg.RegisterResponse, error)
- func (c *Client) SetControlPublicKey(k key.MachinePublic)
- type ClientOpts
- type MapOpts
- type MapSession
- type RegisterOpts
Constants ¶
const DefaultServerURL = ipn.DefaultControlURL
DefaultServerURL is the default coordination server base URL, used when ClientOpts.ServerURL is empty.
Variables ¶
This section is empty.
Functions ¶
func DiscoverServerKey ¶
DiscoverServerKey fetches the coordination server's public key from the given server URL. It is a standalone function that requires no client state.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a Tailscale protocol client that speaks to a coordination server over Noise.
func NewClient ¶
func NewClient(opts ClientOpts) (*Client, error)
NewClient creates a new Client configured to talk to the coordination server specified in opts. It performs no I/O; the server's public key is discovered lazily on first use or can be set explicitly via SetControlPublicKey.
func (*Client) AnswerC2NPing ¶
func (c *Client) AnswerC2NPing(ctx context.Context, pr *tailcfg.PingRequest, doNoiseRequest func(*http.Request) (*http.Response, error)) (handled bool)
AnswerC2NPing handles a c2n PingRequest from the control plane by parsing the embedded HTTP request in the payload, routing it locally, and POSTing the HTTP response back to pr.URL using doNoiseRequest. The POST is done in a new goroutine so this method does not block.
It reports whether the ping was handled. Unhandled pings (nil pr, non-c2n types, or unrecognized c2n paths) return false.
func (*Client) DiscoverServerKey ¶
DiscoverServerKey fetches the server's public key from the coordination server and stores it for subsequent use. Any existing noise client is invalidated.
func (*Client) Map ¶
Map sends a map request to the coordination server and returns a MapSession for reading the framed, zstd-compressed response(s).
func (*Client) Register ¶
func (c *Client) Register(ctx context.Context, opts RegisterOpts) (*tailcfg.RegisterResponse, error)
Register sends a registration request to the coordination server and returns the response.
func (*Client) SetControlPublicKey ¶
func (c *Client) SetControlPublicKey(k key.MachinePublic)
SetControlPublicKey sets the server's public key, bypassing lazy discovery. Any existing noise client is invalidated and will be re-created on next use.
type ClientOpts ¶
type ClientOpts struct {
// ServerURL is the base URL of the coordination server
// (e.g. "https://controlplane.tailscale.com").
// If empty, DefaultServerURL is used.
ServerURL string
// MachineKey is this node's machine private key. Required.
MachineKey key.MachinePrivate
// Logf is the log function. If nil, logger.Discard is used.
Logf logger.Logf
}
ClientOpts contains options for creating a new Client.
type MapOpts ¶
type MapOpts struct {
// NodeKey is the node's private key. Required.
NodeKey key.NodePrivate
// Hostinfo is the host information to send. Optional;
// if nil, a minimal default is used.
Hostinfo *tailcfg.Hostinfo
// Stream is whether to receive multiple MapResponses over
// the same HTTP connection.
Stream bool
// OmitPeers is whether the client is okay with the Peers list
// being omitted in the response.
OmitPeers bool
}
MapOpts contains options for sending a map request.
type MapSession ¶
type MapSession struct {
// contains filtered or unexported fields
}
MapSession wraps an in-progress map response stream. Call Next to read each framed, zstd-compressed MapResponse. Call Close when done.
func (*MapSession) Close ¶
func (s *MapSession) Close() error
Close closes the underlying HTTP response body.
func (*MapSession) Next ¶
func (s *MapSession) Next() (*tailcfg.MapResponse, error)
Next reads and returns the next MapResponse from the stream. For non-streaming sessions, the first call returns the single response and subsequent calls return io.EOF. For streaming sessions, Next blocks until the next response arrives or the server closes the connection.
func (*MapSession) NoiseRoundTrip ¶
NoiseRoundTrip sends an HTTP request over the Noise channel used by this map session.
type RegisterOpts ¶
type RegisterOpts struct {
// NodeKey is the node's private key. Required.
NodeKey key.NodePrivate
// Hostinfo is the host information to send. Optional;
// if nil, a minimal default is used.
Hostinfo *tailcfg.Hostinfo
// Ephemeral marks the node as ephemeral.
Ephemeral bool
// AuthKey is a pre-authorized auth key.
AuthKey string
// Tags is a list of ACL tags to request.
Tags []string
}
RegisterOpts contains options for registering a node.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
tsp
command
Program tsp is a low-level Tailscale protocol tool for performing composable building block operations like generating keys and registering nodes.
|
Program tsp is a low-level Tailscale protocol tool for performing composable building block operations like generating keys and registering nodes. |