From eeb21ada42fa0a777a81b61637b79f021263ccdb Mon Sep 17 00:00:00 2001 From: Kristoffer Dalby Date: Fri, 6 Nov 2026 10:38:04 +0000 Subject: [PATCH] derp/server: return STUN bind errors to Serve log.Fatal exited the process and skipped the graceful shutdown. Fixes #3499 --- CHANGELOG.md | 1 + hscontrol/app.go | 7 ++++++- hscontrol/app_test.go | 20 ++++++++++++++++++++ hscontrol/derp/server/derp_server.go | 20 +++++++++++++++----- hscontrol/derp/server/derp_server_test.go | 7 +++++-- 5 files changed, 47 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4ed3f1e92..dff4f14bd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -192,6 +192,7 @@ is not connected, or refuses is "not found". See [the client docs](https://heads - DERP map refreshes keep the node order. Clients keep their home relay. [#3649](https://github.com/juanfont/headscale/pull/3649) - A `derp.urls` or `derp.paths` source that fails to load (unreachable, an HTTP status other than 200, or an invalid map) is logged as a warning and skipped instead of stopping headscale from starting. Headscale still refuses to start when no DERP region remains; a refresh with a failing source keeps the previous map [#3142](https://github.com/juanfont/headscale/issues/3142) - Fix the embedded STUN server returning IPv4 addresses as IPv4-mapped IPv6 addresses (`::ffff:a.b.c.d`), and change it to use Tailscale's STUN server implementation [#3573](https://github.com/juanfont/headscale/issues/3573) +- A STUN listen address that cannot be bound now stops headscale with the same error and hint as the other listeners, after a graceful shutdown; a server component that fails while running now shuts headscale down instead of leaving it half running [#3499](https://github.com/juanfont/headscale/issues/3499) - Nodes with `disable-ipv4` get their peers over IPv6 only. [#3649](https://github.com/juanfont/headscale/pull/3649) - A node name follows a new hostname at login, unless an administrator set the name. [#3649](https://github.com/juanfont/headscale/pull/3649) - `AllowedIPs` list the node's own addresses first. `tailscale whois` reads them in this order. [#3649](https://github.com/juanfont/headscale/pull/3649) diff --git a/hscontrol/app.go b/hscontrol/app.go index 560598c7a..dfce478cc 100644 --- a/hscontrol/app.go +++ b/hscontrol/app.go @@ -632,7 +632,12 @@ func (h *Headscale) Serve(ctx context.Context) error { return errSTUNAddressNotSet } - go h.DERPServer.ServeSTUN() + stunServer, err := h.DERPServer.ListenSTUN(ctx) + if err != nil { + return err + } + + errorGroup.Go(stunServer.Serve) } // Start on the sources that loaded; only a map with no region at all, diff --git a/hscontrol/app_test.go b/hscontrol/app_test.go index 855163848..8470954ca 100644 --- a/hscontrol/app_test.go +++ b/hscontrol/app_test.go @@ -6,6 +6,7 @@ import ( "net/http" "net/http/httptest" "path/filepath" + "syscall" "testing" "time" @@ -115,6 +116,25 @@ func serveTestConfig(t *testing.T, stunAddr string) *types.Config { } } +// A component that cannot start must hand its error back to Serve so the +// deferred shutdown runs; log.Fatal used to exit the process and skip it. +// https://github.com/juanfont/headscale/issues/3499 +func TestServeReturnsSTUNBindError(t *testing.T) { + taken, err := new(net.ListenConfig).ListenPacket(t.Context(), "udp", "127.0.0.1:0") + require.NoError(t, err) + + defer taken.Close() + + app, err := NewHeadscale(serveTestConfig(t, taken.LocalAddr().String())) + require.NoError(t, err) + + err = app.Serve(t.Context()) + require.ErrorIs(t, err, syscall.EADDRINUSE) + + var bindErr *types.ListenerBindError + require.ErrorAs(t, err, &bindErr) +} + // Cancelling the context must run the graceful shutdown and return nil, so // an embedder can stop Serve without sending the process a signal. func TestServeStopsOnContextCancel(t *testing.T) { diff --git a/hscontrol/derp/server/derp_server.go b/hscontrol/derp/server/derp_server.go index 90eff3627..db0f85119 100644 --- a/hscontrol/derp/server/derp_server.go +++ b/hscontrol/derp/server/derp_server.go @@ -377,13 +377,23 @@ func DERPBootstrapDNSHandler( } } -// ServeSTUN starts a STUN server on the configured addr. It uses Tailscale's -// stunserver so replies match what Tailscale's own derpers send. -func (d *DERPServer) ServeSTUN() { - err := stunserver.New(context.Background()).ListenAndServe(d.cfg.STUNAddr) +// ListenSTUN binds a STUN server on the configured addr; the caller runs its +// Serve, which returns once ctx is cancelled. It uses Tailscale's stunserver +// so replies match what Tailscale's own derpers send. +func (d *DERPServer) ListenSTUN(ctx context.Context) (*stunserver.STUNServer, error) { + srv := stunserver.New(ctx) + + err := srv.Listen(d.cfg.STUNAddr) if err != nil { - log.Fatal().Err(err).Msg("failed to open STUN listener") + return nil, &types.ListenerBindError{ + Listener: "STUN", + YAMLKey: "derp.server.stun_listen_addr", + Addr: d.cfg.STUNAddr, + Err: err, + } } + + return srv, nil } func NewDERPVerifyTransport(handleVerifyRequest func(*http.Request, io.Writer) error) *DERPVerifyTransport { diff --git a/hscontrol/derp/server/derp_server_test.go b/hscontrol/derp/server/derp_server_test.go index 3d659631a..ffb1eb765 100644 --- a/hscontrol/derp/server/derp_server_test.go +++ b/hscontrol/derp/server/derp_server_test.go @@ -111,7 +111,10 @@ func TestSTUNServerUnmapsIPv4(t *testing.T) { } d := &DERPServer{cfg: &types.DERPConfig{STUNAddr: fmt.Sprintf("0.0.0.0:%d", local.Port)}} - go d.ServeSTUN() + srv, err := d.ListenSTUN(t.Context()) + require.NoError(t, err) + + go srv.Serve() //nolint:errcheck // Serve returns nil once the test context ends tests := []struct { network string @@ -134,7 +137,7 @@ func TestSTUNServerUnmapsIPv4(t *testing.T) { var n int - // Retry until ServeSTUN has bound the port. + // Retry until Serve answers. require.EventuallyWithT(t, func(c *assert.CollectT) { _, err := conn.Write(stun.Request(txid)) require.NoError(c, err)