Skip to content

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:

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:

  1. 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.
  2. 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

  1. Copy the plugin release directory into your plugins directory, for example ~/.config/dioad/connect/plugins/pluginhello.
  2. Optional: check the release before the agent loads it:

    connect plugin verify --dir PLUGIN_DIRECTORY --public-key PUBLIC_KEY
    

    Replace 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.

  3. Add a plugins section 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_NAME with a name for the key, used in log messages, and PUBLIC_KEY with the publisher's public key. The config keys depend on the plugin.

  4. 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 only http/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 coredns and mailrouter remain 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.mod or later.
  • Write, or reuse, a tunnel server: a constructor that returns a tunnel.Server, built into a tunnel.ServerType with tunnel.NewServerType. A server that implements tunnel.ExtensionProvider, such as *tunnel.ExtensionServer, adds a management extension. Existing in-tree servers need no changes to run as plugins.

Create the plugin binary

  1. In your module, create a main package that calls plugin.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.NewServerType is your tunnel type, built with tunnel.NewServerType from its name, its config struct and its constructor, as described in Authoring a Tunnel Type. The plugin decodes each tunnel's config: 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 of ServerTypes must match the manifest you sign. Names use lowercase letters, digits, and hyphens.

  2. Build one binary per platform, named connect-plugin-NAME_GOOS_GOARCH, with .exe appended 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 VERSION with 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

  1. Generate a signing key once, and keep the private key secret:

    connect plugin keygen --out KEY_PREFIX
    

    Replace KEY_PREFIX with a path prefix. The command writes the private key to KEY_PREFIX.key and the public key to KEY_PREFIX.pub, and prints the trusted-keys entry to give to operators. It never overwrites existing files.

  2. For each release, write and sign the manifest:

    connect plugin sign --dir myplugin --version VERSION --key KEY_PREFIX.key
    

    The command hashes every binary in the directory into manifest.json and writes manifest.json.sig. If you omit --key, it reads the key path from the CONNECT_PLUGIN_SIGNING_KEY environment variable. Use --name and --type when the plugin name or tunnel types differ from the directory name.

  3. 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.ReverseConfig carries the tunnel's name, type, endpoint, tags, extra names, subdomain, custom domains, its config map, and a snapshot of its metadata. TLSServerConfig, TLSClientConfig, and NetworkACL return zero values. If your server needs, for example, an upstream TLS client configuration, take it from the config map.
  • Numbers in config. The config map travels as JSON, so numbers arrive as float64. mapstructure.Decode into typed fields still works.
  • Metadata. Metadata that your type sets, with tunnel.WithTrafficProtocol or tunnel.WithMetadata, or in your constructor with AddExtraMetadata, MergeMetadata, or Update, is merged into the tunnel when the constructor returns. You can set fields but not clear them.
  • Connections. Connections arrive decrypted. RemoteAddr returns the real client address. To read the SNI, negotiated ALPN protocol, and client certificates, call plugin.ConnTLSInfo(conn).
  • Context and logging. The ctx passed to your constructor carries a zerolog logger tagged with the tunnel's ID, name, and type. Log with zerolog.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 Serve returns.

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.