KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agents #developer-tools #typescript #codex #cli #claude-code #mcp #rust #deepseek-harness #ai-agent

caddy-netbird

★ 30 Open GitHub ↗

Caddy plugin that embeds a NetBird client for proxying HTTP and TCP/UDP traffic through NetBird networks

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# caddy-netbird

A [Caddy](https://caddyserver.com) plugin that embeds a [NetBird](https://netbird.io) client, allowing Caddy to proxy traffic through a NetBird network. Supports HTTP reverse proxying (Layer 7) and raw TCP/UDP proxying (Layer 4) via [caddy-l4](https://github.com/mholt/caddy-l4).

## Prerequisites

This plugin only handles the Caddy side. It joins the NetBird network as a peer using the provided setup key and dials upstream addresses through the tunnel. **All NetBird management configuration must be done beforehand:**

- The **setup key** must be created in the NetBird management dashboard.
- **Access control policies** must allow traffic from the Caddy peer to the upstream peers/services.
- **Networks (routes)** must be configured if the upstream is behind a routed network (e.g. `192.168.1.0/24`).
- The upstream peers must be online and reachable within the NetBird network.

This plugin does not create, modify, or manage any NetBird resources. It is a consumer of the network, not an administrator.

## Build

Build from source (includes L4 support):

```bash
go build -o caddy ./cmd/caddy
```

### xcaddy

NetBird uses forked dependencies that require `replace` directives. Since xcaddy does not propagate replace directives from plugin modules, you must pass them explicitly:

```bash
xcaddy build \
    --with github.com/lixmal/caddy-netbird \
    --replace github.com/cloudflare/circl=codeberg.org/cunicu/circl@v0.0.0-20230801113412-fec58fc7b5f6 \
    --replace github.com/dexidp/dex=github.com/netbirdio/dex@v0.244.1-0.20260512110716-8d70ad8647c1 \
    --replace github.com/dexidp/dex/api/v2=github.com/netbirdio/dex/api/v2@v2.0.0-20260512110716-8d70ad8647c1 \
    --replace github.com/getlantern/systray=github.com/netbirdio/systray@v0.0.0-20231030152038-ef1ed2a27949 \
    --replace github.com/kardianos/service=github.com/netbirdio/service@v0.0.0-20240911161631-f62744f42502 \
    --replace github.com/mailru/easyjson=github.com/netbirdio/easyjson@v0.9.0 \
    --replace github.com/pion/ice/v4=github.com/netbirdio/ice/v4@v4.0.0-20250908184934-6202be846b51 \
    --replace golang.zx2c4.com/wireguard=github.com/netbirdio/wireguard-go@v0.0.0-20260523085312-4b4a4e36017f
```

The list must match the `replace` block in this repo's `go.mod`, which in turn mirrors the replaces in NetBird's own `go.mod` for the pinned NetBird version.

## Container

```bash
podman run -d \
  --cap-add NET_BIND_SERVICE \
  -v /path/to/Caddyfile:/config/Caddyfile:ro \
  -p 80:80 -p 443:443 \
  ghcr.io/lixmal/caddy-netbird:latest
```

The image runs as a non-root user. `NET_BIND_SERVICE` is required to bind ports 80 and 443.

## Caddyfile

See [examples/](examples/) for complete Caddyfile configurations. Below is a quick overview.

### Ingress (internet to NetBird)

Expose a NetBird peer to the public internet:

```caddyfile
{
    netbird {
        management_url https://api.netbird.io:443
        setup_key {$NB_SETUP_KEY}

node ingress {
            hostname caddy-ingress
        }
    }
}

app.example.com {
    reverse_proxy backend.netbird.cloud:8080 {
        transport netbird ingress
    }
}
```

### Egress (NetBird to external)

Make external services available to NetBird peers. Uses `netbird/<node>:<port>` (TCP) or `netbird-udp/<node>:<port>` (UDP) listener address formats to bind on the NetBird virtual interface:

```caddyfile
{
    netbird {
        management_url https://api.netbird.io:443
        setup_key {$NB_SETUP_KEY}

node egress {
            hostname caddy-egress
            wireguard_port 0
            block_inbound false
        }
    }

layer4 {
        # Forward TCP port to an external service
        netbird/egress:9080 {
            route {
                proxy external-host:8080
            }
        }
        # SOCKS5 proxy for dynamic destinations
        netbird/egress:1080 {
            route {
                socks5
            }
        }
        # Forward UDP to an internal DNS server
        netbird-udp/egress:5353 {
            route {
                proxy udp/dns-server.internal:53
            }
        }
    }
}
```

NetBird peers can then connect to `<caddy-egress-ip>:9080` for the forwarded service, or use `<caddy-egress-ip>:1080` as a SOCKS5 proxy.

The `block_inbound false` option is required for egress nodes: it allows incoming connections from NetBird peers to reach the listener.

### Internal (NetBird to NetBird)

Reverse proxy between peers, without leaving the NetBird network. Caddy binds its listener on the NetBird interface (like egress) and dials the upstream through the tunnel (like ingress), so both the client and the backend are peers. Combine the `netbird/<node>` bind address with the `netbird` transport:

```caddyfile
{
    netbird {
        management_url https://api.netbird.io:443
        setup_key {$NB_SETUP_KEY}

node internal {
            hostname caddy-internal
            wireguard_port 0
            block_inbound false
        }
    }
}

# HTTP: peers reach caddy-internal's NetBird IP on :8080
:8080 {
    bind netbird/internal
    reverse_proxy backend.netbird.cloud:8000 {
        transport netbird internal
    }
}
```

Peers connect to `<caddy-internal-ip>:8080`; Caddy proxies to `backend.netbird.cloud:8000` over the tunnel. As with egress, `block_inbound false` is required so peers can reach the listener. For raw TCP/UDP between peers, bind a `layer4` listener on `netbird/<node>` and route with the `netbird` handler. See [examples/internal.caddyfile](examples/internal.caddyfile).

For serving HTTPS on internal-only sites, the default ACME challenges cannot reach a NetBird-only listener. See [examples/internal-tls.caddyfile](examples/internal-tls.caddyfile) for certificate provisioning options: ACME DNS-01 (requires a DNS provider module in the build), Caddy's internal CA, or an existing internal PKI.

### Layer 4 (TCP/UDP)

Requires [caddy-l4](https://github.com/mholt/caddy-l4). The `layer4` block goes inside the global options.

```caddyfile
{
    layer4 {
        :2222 {
            route {
                netbird backend.netbird.cloud:22 ingress
            }
        }
    }
}
```

See [examples/](examples/) for more L4 configurations (UDP, SNI routing, mixed HTTP+L4).

## Admin API

The plugin registers endpoints on Caddy's [admin API](https://caddyserver.com/docs/api) (default: `localhost:2019`) for debugging and runtime control.

### Status

```bash
# Human-readable output (default)
curl localhost:2019/netbird/status

# JSON output
curl 'localhost:2019/netbird/status?format=json'
```

Example text output:

```
Node: ingress
  NetBird IP:  100.0.50.187/16
  FQDN:        caddy-ingress.netbird.cloud
  Management:  https://api.netbird.io:443  Connected
  Signal:      https://signal.netbird.io   Connected
  Relay:       rel://relay.netbird.io      Available

Peers (3):
  FQDN                       IP          Status      Latency  Transfer       Conn     Handshake  Routes
  ----                       --          ------      -------  --------       ----     ---------  ------
  backend.netbird.cloud      100.0.1.10  Connected   1.2ms    1.5 KiB/2 KiB  P2P      13s ago    192.168.1.0/24
  api-backend.netbird.cloud  100.0.1.20  Connected   3.4ms    800 B/1.2 KiB  Relayed  45s ago    -
  web-backend.netbird.cloud  100.0.1.30  Connecting  -        -              -        -          -
```

### Ping

Test connectivity to a host through the NetBird network:

```bash
# TCP ping (default)
curl -X POST localhost:2019/netbird/ping \
  -d '{"node": "ingress", "address": "backend.netbird.cloud:8080"}'

# ICMP ping
curl -X POST localhost:2019/netbird/ping \
  -d '{"node": "ingress", "address": "backend.netbird.cloud", "network": "ping"}'

# UDP ping
curl -X POST localhost:2019/netbird/ping \
  -d '{"node": "ingress", "address": "dns-server.netbird.cloud:53", "network": "udp"}'
```

Response:

```json
{"reachable": true, "latency": 1234567}
```

The `node` field defaults to `"default"` if omitted. Latency is in nanoseconds.

### Log level

Change the NetBird client log level at runtime:

```bash
curl -X PUT localhost:2019/netbird/log-level -d '{"level": "debug"}'
```

Valid levels: `panic`, `fatal`, `error`, `warn`, `info`, `debug`, `trace`.

## Architecture

The plugin registers five Caddy modules:

| Module | Caddy ID | Purpose |
|--------|----------|---------|
| `App` | `netbird` | Manages NetBird client lifecycle, config, and usage pool |
| `Transport` | `http.reverse_proxy.transport.netbird` | Dials HTTP upstreams through the NetBird network |
| `Handler` | `layer4.handlers.netbird` | Proxies raw TCP/UDP through the NetBird network (requires caddy-l4) |
| `Listener` | `netbird` (network) | Binds listeners on the NetBird virtual interface for egress |
| `Admin API` | `admin.api.netbird` | Exposes status, ping, and log level endpoints on the admin API |

The embedded NetBird client (`embed.Client`) runs entirely in userspace without requiring a TUN device or root privileges. Upstream traffic is dialed through the tunnel while Caddy handles TLS termination, load balancing, health checks, retries, and all other reverse proxy features.

### Client sharing

Multiple sites can share the same NetBird client by referencing the same node name. Clients are ref-counted via `caddy.UsagePool` and survive config reloads without reconnecting.

### Global options

| Option | Description |
|--------|-------------|
| `management_url` | Default management server URL |
| `setup_key` | Default setup key for authentication |
| `log_level` | NetBird client log level (default: `info`) |

### Node options

| Option | Description |
|--------|-------------|
| `management_url` | Override app-level management URL |
| `setup_key` | Override app-level setup key |
| `jwt_token` | JWT-based authentication instead of a setup key |
| `private_key` | Direct private key authentication instead of a setup key |
| `hostname` | Device name in the NetBird network (default: `caddy-<node>`) |
| `pre_shared_key` | Pre-shared key for the network interface |
| `log_level` | Log level for this client (e.g. `debug`, `info`, `warn`) |
| `config_path` | Path to the NetBird config file (in-memory if unset) |
| `state_path` | Path to the NetBird state file |
| `wireguard_port` | Port for the network interface (default: 51820 via NetBird) |
| `mtu` | MTU for the network interface (valid range 576..8192) |
| `no_userspace` | Disable userspace networking mode (`true`/`false`, needs root) |
| `disable_client_routes` | Disable client routes (`true`/`false`) |
| `disable_ipv6` | Disable IPv6 overlay addressing (`true`/`false`) |
| `block_inbound` | Block inbound connections from peers (default: `true`). Set to `false` for egress nodes |
| `block_lan_access` | Block the peer from reaching the host's LAN when used as a routing peer (`true`/`false`) |
| `dns_labels` | Additional DNS labels for the peer (space-separated list) |
| `preallocated_buffers_per_pool` | Cap the per-tunnel buffer pool (process-global tuning) |
| `max_batch_size` | Packets read/written per syscall (process-global tuning) |

> **Authentication:** one of `setup_key` (node or app level), `jwt_token`, or `private_key` is required per node.

> **Note on `wireguard_port`:** For reliable peer-to-peer connectivity, the configured port (or the default random port) should be exposed via port forwarding on the host's firewall/NAT. Without it, connections may fall back to relayed traffic which adds latency.

### Multiple nodes

Each node creates a separate NetBird peer identity. This is useful when connecting to different networks or management servers from a single Caddy instance.

**Different management servers.** No shared defaults needed, each node specifies its own management URL and setup key:

```caddyfile
{
    netbird {
        node corp {
            management_url https://netbird.corp.example.com:443
            setup_key {$NB_CORP_KEY}
            hostname caddy-corp
            wireguard_port 0
        }

node staging {
            management_url https://netbird.staging.example.com:443
            setup_key {$NB_STAGING_KEY}
            hostname caddy-staging
            wireguard_port 0
        }
    }
}

corp-app.example.com {
    reverse_proxy backend.corp.internal:8080 {
        transport netbird corp
    }
}

staging-app.example.com {
    reverse_proxy backend.staging.internal:8080 {
        transport netbird staging
    }
}
```

**Same management, different setup keys.** Useful for separate peer identities with different access policies on the same network:

```caddyfile
{
    netbird {
        management_url https://api.netbird.io:443

node web {
            setup_key {$NB_WEB_KEY}
            hostname caddy-web
            wireguard_port 0
        }

node api {
            setup_key {$NB_API_KEY}
            hostname caddy-api
            wireguard_port 0
        }
    }
}

web.example.com {
    reverse_proxy web-backend.netbird.cloud:8080 {
        transport netbird web
    }
}

api.example.com {
    reverse_proxy api-backend.netbird.cloud:3000 {
        transport netbird api
    }
}
```

> **Note:** Each node binds its own network interface port. When running multiple nodes, set distinct `wireguard_port` values to avoid conflicts.

### Upstream TLS

The NetBird network encryption and upstream TLS are independent concerns. The upstream behind the tunnel may be a plain HTTP service on a peer, or it could be an HTTPS endpoint reached via a NetBird route to an external network.

TLS to the upstream is automatically enabled when using `https://` upstream addresses. You can also configure it explicitly in the transport block:

| Option | Description |
|--------|-------------|
| `tls` | Enable TLS to upstream with default settings |
| `tls_insecure_skip_verify` | Skip TLS certificate verification (testing only) |
| `tls_server_name` | Override the server name for TLS verification |

caddy-netbird

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README