From 2545a3c30bee3976da9d294e35965a8c4e1b0c94 Mon Sep 17 00:00:00 2001
From: jnfrati <nicofrati@gmail.com>
Date: Tue, 25 Aug 2026 11:01:14 +0200
Subject: [PATCH] [signal,proxy,relay] Add service configuration examples

Operators need concrete schemas for the new config-file flags.

Add validated YAML examples for Relay/STUN, Signal, and Proxy.
---
 proxy/cmd/proxy/cmd/config_test.go |  7 +++++
 proxy/config.example.yaml          | 41 ++++++++++++++++++++++++++++++
 relay/cmd/config_test.go           | 14 ++++++++++
 relay/config.example.yaml          | 22 ++++++++++++++++
 signal/cmd/config_test.go          |  7 +++++
 signal/config.example.yaml         | 15 +++++++++++
 6 files changed, 106 insertions(+)
 create mode 100644 proxy/config.example.yaml
 create mode 100644 relay/config.example.yaml
 create mode 100644 signal/config.example.yaml

diff --git a/proxy/cmd/proxy/cmd/config_test.go b/proxy/cmd/proxy/cmd/config_test.go
index 840628f4e..cf4812de5 100644
--- a/proxy/cmd/proxy/cmd/config_test.go
+++ b/proxy/cmd/proxy/cmd/config_test.go
@@ -10,6 +10,13 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func TestExampleConfig(t *testing.T) {
+	require.NoError(t, rootCmd.ParseFlags(nil))
+	cfg, err := loadConfig(rootCmd, filepath.Join("..", "..", "..", "config.example.yaml"))
+	require.NoError(t, err)
+	assert.Equal(t, "proxy.example.com", cfg.ProxyURL, "Example config should load")
+}
+
 func TestLoadConfigPrecedence(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "proxy.yaml")
 	require.NoError(t, os.WriteFile(configPath, []byte(`
diff --git a/proxy/config.example.yaml b/proxy/config.example.yaml
new file mode 100644
index 000000000..f461af56d
--- /dev/null
+++ b/proxy/config.example.yaml
@@ -0,0 +1,41 @@
+# Command-line flags override environment variables, which override this file.
+listenAddress: ":443"
+id: "proxy-1"
+domain: "proxy.example.com"
+managementAddress: "https://api.netbird.io:443"
+proxyToken: "replace-with-a-proxy-token"
+
+certificateDirectory: "/var/lib/netbird/certs"
+certificateFile: "tls.crt"
+certificateKeyFile: "tls.key"
+generateACMECertificates: true
+acmeChallengeAddress: ":80"
+acmeDirectory: "https://acme-v02.api.letsencrypt.org/directory"
+acmeEABKID: ""
+acmeEABHMACKey: ""
+acmeChallengeType: "tls-alpn-01"
+certLockMethod: "auto"
+wildcardCertDir: ""
+
+debugEndpointEnabled: false
+debugEndpointAddress: "localhost:8444"
+healthAddress: "localhost:8080"
+forwardedProto: "auto"
+trustedProxies: ""
+wireguardPort: 0
+proxyProtocol: false
+preSharedKey: ""
+supportsCustomPorts: true
+requireSubdomain: false
+private: false
+maxDialTimeout: "0s"
+maxSessionIdleTimeout: "0s"
+mappingBatchWatchdog: "0s"
+geoDataDir: "/var/lib/netbird/geolocation"
+crowdSecAPIURL: ""
+crowdSecAPIKey: ""
+logLevel: "info"
+
+# Optional tunnel memory and throughput tuning.
+# preallocatedBuffers: 4096
+# maxBatchSize: 128
diff --git a/relay/cmd/config_test.go b/relay/cmd/config_test.go
index 1625e1908..d93b12be6 100644
--- a/relay/cmd/config_test.go
+++ b/relay/cmd/config_test.go
@@ -9,6 +9,20 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func TestExampleConfig(t *testing.T) {
+	require.NoError(t, rootCmd.ParseFlags(nil))
+	oldConfigPath := configPath
+	configPath = filepath.Join("..", "config.example.yaml")
+	t.Cleanup(func() {
+		configPath = oldConfigPath
+	})
+
+	cfg, err := loadConfig(rootCmd)
+	require.NoError(t, err)
+	assert.Equal(t, "rels://relay.example.com:443", cfg.ExposedAddress, "Example config should load")
+	assert.True(t, cfg.EnableSTUN, "Example config should enable STUN")
+}
+
 func TestLoadConfigPrecedence(t *testing.T) {
 	path := filepath.Join(t.TempDir(), "relay.yaml")
 	require.NoError(t, os.WriteFile(path, []byte(`
diff --git a/relay/config.example.yaml b/relay/config.example.yaml
new file mode 100644
index 000000000..cb3a56054
--- /dev/null
+++ b/relay/config.example.yaml
@@ -0,0 +1,22 @@
+# Command-line flags override environment variables, which override this file.
+listenAddress: ":443"
+exposedAddress: "rels://relay.example.com:443"
+metricsPort: 9090
+
+# Use either static certificates or Let's Encrypt.
+letsencryptEmail: ""
+letsencryptDataDir: ""
+letsencryptDomains: []
+letsencryptAWSRoute53: false
+tlsCertFile: "/etc/netbird/tls.crt"
+tlsKeyFile: "/etc/netbird/tls.key"
+
+authSecret: "replace-with-a-strong-secret"
+logLevel: "info"
+logFile: "console"
+healthcheckListenAddress: ":9000"
+trustedProxies: ""
+
+enableSTUN: true
+stunPorts: [3478]
+stunLogLevel: "info"
diff --git a/signal/cmd/config_test.go b/signal/cmd/config_test.go
index 823471548..163ce1693 100644
--- a/signal/cmd/config_test.go
+++ b/signal/cmd/config_test.go
@@ -9,6 +9,13 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
+func TestExampleConfig(t *testing.T) {
+	require.NoError(t, runCmd.ParseFlags(nil))
+	cfg, err := loadConfig(runCmd, filepath.Join("..", "config.example.yaml"))
+	require.NoError(t, err)
+	assert.Equal(t, "/etc/netbird/tls.crt", cfg.CertFile, "Example config should load")
+}
+
 func TestLoadConfigPrecedence(t *testing.T) {
 	configPath := filepath.Join(t.TempDir(), "signal.yaml")
 	require.NoError(t, os.WriteFile(configPath, []byte(`
diff --git a/signal/config.example.yaml b/signal/config.example.yaml
new file mode 100644
index 000000000..04e175d51
--- /dev/null
+++ b/signal/config.example.yaml
@@ -0,0 +1,15 @@
+# Command-line flags override environment variables, which override this file.
+# Set port to 0 to select 443 with TLS or 80 without TLS.
+port: 0
+metricsPort: 9090
+
+# Use either static certificates or Let's Encrypt.
+letsencryptDomain: ""
+letsencryptEmail: ""
+letsencryptDataDir: ""
+certFile: "/etc/netbird/tls.crt"
+certKey: "/etc/netbird/tls.key"
+
+logLevel: "info"
+logFile: "console"
+pprofAddress: ""