External Plugins
An external plugin adds tunnel types to the connect agent without rebuilding the agent. A plugin is a separate binary that the agent verifies, runs as a child process, and sends tunnel connections to.
This page is for two readers:
- Operators who want to run a plugin: see Install a plugin.
- Go developers who want to write one: see Write a plugin.
This page doesn't cover writing tunnel servers in general. For that, see Extension Authoring and Tunnel Types.
How plugins work
The agent loads plugins in two stages:
- At startup, the agent verifies every plugin without running it. It reads each plugin's manifest, checks the manifest's signature against the keys you trust, and registers the tunnel types the manifest declares.
- When a tunnel first uses a plugin type, the agent starts the plugin. It copies the plugin binary into its cache, checks the copy's SHA-256 digest against the signed manifest, and runs only that copy.
One plugin process serves every tunnel of its types. If the process exits, the agent restarts it and the affected tunnels reconnect.
The agent terminates TLS and applies the tunnel's network ACL before a connection reaches the plugin. A plugin never sees certificates, ACME settings, network ACLs, or the agent's environment secrets.
Trust model
A plugin runs as the same operating-system user as the agent and can do anything that user can. The signature check decides which code runs; it doesn't sandbox that code. Only trust signing keys that belong to people you'd let run code on the agent's machine.
The agent rejects a plugin, and logs why, when any of the following is true:
- The manifest isn't signed by a trusted key, and the plugin isn't listed in
allow-unsigned. - A signature is present but doesn't verify.
- On Linux and macOS, a plugin directory or file is group-writable, world-writable, a symlink, or owned by a user other than the agent's user or root.
- The manifest has no binary for the agent's operating system and architecture.
- The manifest was built for a different plugin protocol version.
- A declared tunnel type is already provided by the agent or by another plugin.
The agent also refuses to run a plugin binary whose digest doesn't match the signed manifest, or whose reported name, version, or tunnel types differ from its manifest. Those failures are permanent for that agent run.
Plugin release layout
A plugin release is a directory named after the plugin:
PLUGINS_DIRECTORY/
pluginhello/
manifest.json
manifest.json.sig
connect-plugin-pluginhello_linux_amd64
connect-plugin-pluginhello_darwin_arm64
connect-plugin-pluginhello_windows_amd64.exe
A release can contain binaries for several platforms. The agent uses the one for its own operating system and architecture.
Install a plugin
Before you begin
- Get the plugin release directory and the publisher's public key, which looks like
ed25519:MCowBQYDK2VwAyEA.... - Make sure the agent's user owns the directory you install plugins into, and that no other user can write to it.
Install and enable the plugin
- Copy the plugin release directory into your plugins directory, for example
~/.config/dioad/connect/plugins/pluginhello. -
Optional: check the release before the agent loads it:
connect plugin verify --dir PLUGIN_DIRECTORY --public-key PUBLIC_KEYReplace the following:
PLUGIN_DIRECTORY: the plugin release directory.PUBLIC_KEY: the publisher's public key.
The command prints
OK:, followed by the plugin name, version, and signing key ID. -
Add a
pluginssection to the agent configuration, and a tunnel that uses the plugin's tunnel type:plugins: directory: ~/.config/dioad/connect/plugins trusted-keys: - name: PUBLISHER_NAME public-key: "PUBLIC_KEY" traffic: tunnels: - name: hello type: pluginhello config: custom-message: "Hello {{ .Principal }} from a plugin"Replace
PUBLISHER_NAMEwith a name for the key, used in log messages, andPUBLIC_KEYwith the publisher's public key. Theconfigkeys depend on the plugin. -
Restart the agent. The agent loads plugins only at startup.
For every plugins option, see plugins in the agent configuration reference.
Confirm that the plugin loaded
The agent logs plugin verified at startup for each plugin it accepts, with the plugin's name, version, and signing key ID. It logs plugin rejected with the reason for each plugin it refuses.
The agent logs plugin started the first time a tunnel uses the plugin. Lines that the plugin itself logs appear in the agent's log, tagged with plugin and plugin_version.
Limitations
- Plugins can't serve HTTP/2. When a plugin tunnel terminates TLS and you don't set
tls-server.next-protos, the agent offers clients onlyhttp/1.1. - Plugins serve reverse tunnels only. They can't provide forward tunnels or exec services.
- Plugins can't use agent services such as tunnel search or the DNS-01 challenge store, so types like
corednsandmailrouterremain built in. - To install or upgrade a plugin, restart the agent.
Write a plugin
A plugin is a Go main package that imports only the connect SDK, github.com/dioad/connect/sdk/.... It serves tunnel types written exactly as built-in ones are: as tunnel.ServerType values. The pluginhello example is a complete plugin.
Before you begin
- Install Go, at the version in the connect module's
go.modor later. - Write, or reuse, a tunnel server: a constructor that returns a
tunnel.Server, built into atunnel.ServerTypewithtunnel.NewServerType. A server that implementstunnel.ExtensionProvider, such as*tunnel.ExtensionServer, adds a management extension. Existing in-tree servers need no changes to run as plugins.
Create the plugin binary
-
In your module, create a
mainpackage that callsplugin.Serve:package main import ( "github.com/dioad/connect/sdk/agent/plugin" "github.com/dioad/connect/sdk/agent/tunnel" "example.com/myplugin/server" ) var version = "dev" // set with -ldflags "-X main.version=..." func main() { plugin.Serve(plugin.Opts{ Name: "myplugin", Version: version, ServerTypes: []tunnel.ServerType{server.NewServerType("myplugin")}, }) }server.NewServerTypeis your tunnel type, built withtunnel.NewServerTypefrom its name, its config struct and its constructor, as described in Authoring a Tunnel Type. The plugin decodes each tunnel'sconfig:block strictly into that struct, so a key that matches no field fails the tunnel with the key's path.Name,Version, and the names ofServerTypesmust match the manifest you sign. Names use lowercase letters, digits, and hyphens. -
Build one binary per platform, named
connect-plugin-NAME_GOOS_GOARCH, with.exeappended on Windows. Put them in a directory named after the plugin:CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -trimpath \ -ldflags "-X main.version=VERSION" \ -o myplugin/connect-plugin-myplugin_linux_amd64 .Replace
VERSIONwith the release version.
Run by hand, a plugin binary prints a notice that it is a plugin and exits. Only the agent can start it.
Sign the release
-
Generate a signing key once, and keep the private key secret:
connect plugin keygen --out KEY_PREFIXReplace
KEY_PREFIXwith a path prefix. The command writes the private key toKEY_PREFIX.keyand the public key toKEY_PREFIX.pub, and prints thetrusted-keysentry to give to operators. It never overwrites existing files. -
For each release, write and sign the manifest:
connect plugin sign --dir myplugin --version VERSION --key KEY_PREFIX.keyThe command hashes every binary in the directory into
manifest.jsonand writesmanifest.json.sig. If you omit--key, it reads the key path from theCONNECT_PLUGIN_SIGNING_KEYenvironment variable. Use--nameand--typewhen the plugin name or tunnel types differ from the directory name. -
Check the result:
connect plugin verify --dir myplugin --public-key "$(cat KEY_PREFIX.pub)"
Publish the whole directory and your public key.
What crosses the process boundary
A plugin's tunnel type runs in the plugin process, so a few things differ from running in-process:
- Configuration. The
tunnel.ReverseConfigcarries the tunnel's name, type, endpoint, tags, extra names, subdomain, custom domains, itsconfigmap, and a snapshot of its metadata.TLSServerConfig,TLSClientConfig, andNetworkACLreturn zero values. If your server needs, for example, an upstream TLS client configuration, take it from theconfigmap. - Numbers in
config. Theconfigmap travels as JSON, so numbers arrive asfloat64.mapstructure.Decodeinto typed fields still works. - Metadata. Metadata that your type sets, with
tunnel.WithTrafficProtocolortunnel.WithMetadata, or in your constructor withAddExtraMetadata,MergeMetadata, orUpdate, is merged into the tunnel when the constructor returns. You can set fields but not clear them. - Connections. Connections arrive decrypted.
RemoteAddrreturns the real client address. To read the SNI, negotiated ALPN protocol, and client certificates, callplugin.ConnTLSInfo(conn). - Context and logging. The
ctxpassed to your constructor carries a zerolog logger tagged with the tunnel's ID, name, and type. Log withzerolog.Ctx(ctx); the agent writes those lines to its own log. - Lifetime. Each tunnel run gets a new server instance, exactly as in-process. When the tunnel stops or reconnects, the instance's listener closes and your
Servereturns.
Management extensions
When the server your constructor returns implements tunnel.ExtensionProvider, as *tunnel.ExtensionServer does, the agent serves its extension at /extensions/TUNNEL_ID/ on the agent's management API, as it does for built-in types.
The agent removes the Cookie, Authorization, and X-Forwarded-* headers from requests it forwards to a plugin extension, so a plugin never receives the operator's management session. Instead, the agent sets two headers:
X-Connect-Principal: the authenticated management principal, if there is one.X-Forwarded-Prefix: the path prefix the agent removed before forwarding.
To authorize by principal, add plugin.PrincipalMiddleware with ExtensionResource.Use. It puts the principal where authctx.AuthenticatedPrincipalFromContext finds it, the same place the agent's own management API uses.
Test a plugin without the agent
To exercise a plugin's servers in a Go test without building a binary, serve them in-process with plugin.NewServer and go-plugin's plugin.TestPluginGRPCConn. The agent's own tests in internal/agent/pluginhost use this approach.