proxy

package
v0.67.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 26, 2026 License: BSD-3-Clause, AGPL-3.0 Imports: 51 Imported by: 0

README

Netbird Reverse Proxy

The NetBird Reverse Proxy is a separate service that can act as a public entrypoint to certain resources within a NetBird network. At a high level, the way that it operates is:

  • Configured routes are communicated from the Management server to the proxy.
  • For each route the proxy creates a NetBird connection to the NetBird Peer that hosts the resource.
  • When traffic hits the proxy at the address and path configured for the proxied resource, the NetBird Proxy brings up a relevant authentication method for that resource.
  • On successful authentication the proxy will forward traffic onwards to the NetBird Peer.

Proxy Authentication methods supported are:

  • No authentication
  • Oauth2/OIDC
  • Emailed Magic Link
  • Simple PIN
  • HTTP Basic Auth Username and Password

Management Connection and Authentication

The Proxy communicates with the Management server over a gRPC connection. Proxies act as clients to the Management server, the following RPCs are used:

  • Server-side streaming for proxied service updates.
  • Client-side streaming for proxy logs.

To authenticate with the Management server, the proxy server uses Machine-to-Machine OAuth2. If you are using the embedded IdP //TODO: explain how to get credentials. Otherwise, create a new machine-to-machine profile in your IdP for proxy servers and set the relevant settings in the proxy's environment or flags (see below).

User Authentication

When a request hits the Proxy, it looks up the permitted authentication methods for the Host domain. If no authentication methods are registered for the Host domain, then no authentication will be applied (for fully public resources). If any authentication methods are registered for the Host domain, then the Proxy will first serve an authentication page allowing the user to select an authentication method (from the permitted methods) and enter the required information for that authentication method. If the user is successfully authenticated, their request will be forwarded through to the Proxy to be proxied to the relevant Peer. Successful authentication does not guarantee a successful forwarding of the request as there may be failures behind the Proxy, such as with Peer connectivity or the underlying resource.

TLS

Due to the authentication provided, the Proxy uses HTTPS for its endpoint, even if the underlying service is HTTP. Certificate generation can either be via ACME (by default, using Let's Encrypt, but alternative ACME providers can be used) or through certificate files. When not using ACME, the proxy server attempts to load a certificate and key from the files tls.crt and tls.key in a specified certificate directory. When using ACME, the proxy server will store generated certificates in the specified certificate directory.

Auth UI

The authentication UI is a Vite + React application located in the web/ directory. It is embedded into the Go binary at build time.

To build the UI:

cd web
npm install
npm run build

For UI development with hot reload (served at http://localhost:3031):

npm run dev

The built assets in web/dist/ are embedded via //go:embed and served by the web.ServeHTTP handler.

Configuration

NetBird Proxy deployment configuration is via flags or environment variables, with flags taking precedence over the environment. The following deployment configuration is available:

Flag Env Purpose Default
-debug NB_PROXY_DEBUG_LOGS Enable debug logging false
-mgmt NB_PROXY_MANAGEMENT_ADDRESS The address of the management server for the proxy to get configuration from. "https://api.netbird.io:443"
-addr NB_PROXY_ADDRESS The address that the reverse proxy will listen on. ":443
-url NB_PROXY_URL The URL that the proxy will be reached at (where endpoints will be CNAMEd to). If unset, this will fall back to the proxy address. "proxy.netbird.io"
-cert-dir NB_PROXY_CERTIFICATE_DIRECTORY The location that certificates are stored in. "./certs"
-acme-certs NB_PROXY_ACME_CERTIFICATES Whether to use ACME to generate certificates. false
-acme-addr NB_PROXY_ACME_ADDRESS The HTTP address the proxy will listen on to respond to HTTP-01 ACME challenges ":80"
-acme-dir NB_PROXY_ACME_DIRECTORY The directory URL of the ACME server to be used "https://acme-v02.api.letsencrypt.org/directory"
-oidc-id NB_PROXY_OIDC_CLIENT_ID The OAuth2 Client ID for OIDC User Authentication "netbird-proxy"
-oidc-secret NB_PROXY_OIDC_CLIENT_SECRET The OAuth2 Client Secret for OIDC User Authentication ""
-oidc-endpoint NB_PROXY_OIDC_ENDPOINT The OAuth2 provider endpoint for OIDC User Authentication "https://api.netbird.io/oauth2"
-oidc-scopes NB_PROXY_OIDC_SCOPES The OAuth2 scopes for OIDC User Authentication, comma separated "openid,profile,email"

Documentation

Overview

Package proxy runs a NetBird proxy server. It attempts to do everything it needs to do within the context of a single request to the server to try to reduce the amount of concurrency coordination that is required. However, it does run two additional routines in an error group for handling updates from the management server and running a separate HTTP server to handle ACME HTTP-01 challenges (if configured).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ParseTrustedProxies

func ParseTrustedProxies(raw string) ([]netip.Prefix, error)

ParseTrustedProxies parses a comma-separated list of CIDR prefixes or bare IPs into a slice of netip.Prefix values suitable for trusted proxy configuration. Bare IPs are converted to single-host prefixes (/32 or /128).

Types

type Server

type Server struct {
	ID                       string
	Logger                   *log.Logger
	Version                  string
	ProxyURL                 string
	ManagementAddress        string
	CertificateDirectory     string
	CertificateFile          string
	CertificateKeyFile       string
	GenerateACMECertificates bool
	ACMEChallengeAddress     string
	ACMEDirectory            string
	// ACMEEABKID is the External Account Binding Key ID for CAs that require EAB (e.g., ZeroSSL).
	ACMEEABKID string
	// ACMEEABHMACKey is the External Account Binding HMAC key (base64 URL-encoded) for CAs that require EAB.
	ACMEEABHMACKey string
	// ACMEChallengeType specifies the ACME challenge type: "http-01" or "tls-alpn-01".
	// Defaults to "tls-alpn-01" if not specified.
	ACMEChallengeType string
	// CertLockMethod controls how ACME certificate locks are coordinated
	// across replicas. Default: CertLockAuto (detect environment).
	CertLockMethod acme.CertLockMethod
	// WildcardCertDir is an optional directory containing wildcard certificate
	// pairs (<name>.crt / <name>.key). Wildcard patterns are extracted from
	// the certificates' SAN lists. Matching domains use these static certs
	// instead of ACME.
	WildcardCertDir string

	// DebugEndpointEnabled enables the debug HTTP endpoint.
	DebugEndpointEnabled bool
	// DebugEndpointAddress is the address for the debug HTTP endpoint (default: ":8444").
	DebugEndpointAddress string
	// HealthAddress is the address for the health probe endpoint.
	HealthAddress string
	// ProxyToken is the access token for authenticating with the management server.
	ProxyToken string
	// ForwardedProto overrides the X-Forwarded-Proto value sent to backends.
	// Valid values: "auto" (detect from TLS), "http", "https".
	ForwardedProto string
	// TrustedProxies is a list of IP prefixes for trusted upstream proxies.
	// When set, forwarding headers from these sources are preserved and
	// appended to instead of being stripped.
	TrustedProxies []netip.Prefix
	// WireguardPort is the port for the NetBird tunnel interface. Use 0
	// for a random OS-assigned port. A fixed port only works with
	// single-account deployments; multiple accounts will fail to bind
	// the same port.
	WireguardPort uint16
	// ProxyProtocol enables PROXY protocol (v1/v2) on TCP listeners.
	// When enabled, the real client IP is extracted from the PROXY header
	// sent by upstream L4 proxies that support PROXY protocol.
	ProxyProtocol bool
	// PreSharedKey used for tunnel between proxy and peers (set globally not per account)
	PreSharedKey string
	// SupportsCustomPorts indicates whether the proxy can bind arbitrary
	// ports for TCP/UDP/TLS services.
	SupportsCustomPorts bool
	// RequireSubdomain indicates whether a subdomain label is required
	// in front of this proxy's cluster domain. When true, accounts cannot
	// create services on the bare cluster domain.
	RequireSubdomain bool
	// MaxDialTimeout caps the per-service backend dial timeout.
	// When the API sends a timeout, it is clamped to this value.
	// When the API sends no timeout, this value is used as the default.
	// Zero means no cap (the proxy honors whatever management sends).
	MaxDialTimeout time.Duration
	// GeoDataDir is the directory containing GeoLite2 MMDB files for
	// country-based access restrictions. Empty disables geo lookups.
	GeoDataDir string
	// MaxSessionIdleTimeout caps the per-service session idle timeout.
	// Zero means no cap (the proxy honors whatever management sends).
	// Set via NB_PROXY_MAX_SESSION_IDLE_TIMEOUT for shared deployments.
	MaxSessionIdleTimeout time.Duration
	// contains filtered or unexported fields
}

func (*Server) ListenAndServe

func (s *Server) ListenAndServe(ctx context.Context, addr string) (err error)

func (*Server) NotifyCertificateIssued

func (s *Server) NotifyCertificateIssued(ctx context.Context, accountID types.AccountID, serviceID types.ServiceID, domain string) error

NotifyCertificateIssued sends a notification to management that a certificate was issued

func (*Server) NotifyStatus

func (s *Server) NotifyStatus(ctx context.Context, accountID types.AccountID, serviceID types.ServiceID, connected bool) error

NotifyStatus sends a status update to management about tunnel connectivity.

Directories

Path Synopsis
Package auth contains exported proxy auth values.
Package auth contains exported proxy auth values.
cmd
proxy command
internal
certwatch
Package certwatch watches TLS certificate files on disk and provides a hot-reloading GetCertificate callback for tls.Config.
Package certwatch watches TLS certificate files on disk and provides a hot-reloading GetCertificate callback for tls.Config.
debug
Package debug provides HTTP debug endpoints and CLI client for the proxy server.
Package debug provides HTTP debug endpoints and CLI client for the proxy server.
flock
Package flock provides best-effort advisory file locking using flock(2).
Package flock provides best-effort advisory file locking using flock(2).
geolocation
Package geolocation provides IP-to-country lookups using MaxMind GeoLite2 databases.
Package geolocation provides IP-to-country lookups using MaxMind GeoLite2 databases.
grpc
Package grpc provides gRPC utilities for the proxy client.
Package grpc provides gRPC utilities for the proxy client.
health
Package health provides health probes for the proxy server.
Package health provides health probes for the proxy server.
k8s
Package k8s provides a lightweight Kubernetes API client for coordination Leases.
Package k8s provides a lightweight Kubernetes API client for coordination Leases.
restrict
Package restrict provides connection-level access control based on IP CIDR ranges and geolocation (country codes).
Package restrict provides connection-level access control based on IP CIDR ranges and geolocation (country codes).
tcp
types
Package types defines common types used across the proxy package.
Package types defines common types used across the proxy package.
udp

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL