linux: allow %d anywhere in the tun.dev template

examples/config.yml

@@ -242,6 +242,10 @@ tun:
   # When tun is disabled, a lighthouse can be started without a local tun interface (and therefore without root)
   disabled: false
   # Name of the device. If not set, a default will be chosen by the OS.
+  # For Linux: a single `%d` anywhere in the name is treated as a template and replaced with the
+  #   lowest number that yields an unused device name (e.g. `nebula%d` becomes `nebula0`, then `nebula1`, and so on, `neb%dprod` becomes `neb0prod`).
+  #   Only on Linux: `nebula%d` is the default if tun.dev is unset.
+  #   The resulting name must be shorter than the kernel limit of 16 characters.
   # For macOS: if set, must be in the form `utun[0-9]+`.
   # For NetBSD: Required to be set, must be in the form `tun[0-9]+`
   dev: nebula1

overlay/tun_linux.go

@@ -5,6 +5,7 @@ package overlay
 
 import (
 	"encoding/binary"
+	"errors"
 	"fmt"
 	"io"
 	"log/slog"
@@ -250,6 +251,13 @@ func newTunFromFd(c *config.C, l *slog.Logger, deviceFd int, vpnNetworks []netip
 }
 
 func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue bool) (*tun, error) {
+	// Resolve (and validate) the device name up front so a bad tun.dev fails
+	// fast, before we open /dev/net/tun or leak a file descriptor.
+	tunName, err := findNextTunName(c.GetString("tun.dev", "nebula%d"))
+	if err != nil {
+		return nil, err
+	}
+
 	fd, err := unix.Open("/dev/net/tun", os.O_RDWR, 0)
 	if err != nil {
 		// If /dev/net/tun doesn't exist, try to create it (will happen in docker)
@@ -277,12 +285,11 @@ func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue
 	if multiqueue {
 		req.Flags |= unix.IFF_MULTI_QUEUE
 	}
-	nameStr := c.GetString("tun.dev", "")
-	copy(req.Name[:], nameStr)
+	copy(req.Name[:], tunName)
 	if err = ioctl(uintptr(fd), uintptr(unix.TUNSETIFF), uintptr(unsafe.Pointer(&req))); err != nil {
 		_ = unix.Close(fd)
 		return nil, &NameError{
-			Name:       nameStr,
+			Name:       tunName,
 			Underlying: err,
 		}
 	}
@@ -298,6 +305,68 @@ func newTun(c *config.C, l *slog.Logger, vpnNetworks []netip.Prefix, multiqueue
 	return t, nil
 }
 
+func validateTunName(tunName string) error {
+	if !strings.Contains(tunName, "%d") {
+		if len(tunName) >= unix.IFNAMSIZ {
+			return fmt.Errorf("tun.dev %q is not shorter than the maximum device name length of %d", tunName, unix.IFNAMSIZ)
+		}
+		return nil
+	}
+	if strings.Count(tunName, "%d") > 1 {
+		return fmt.Errorf("tun.dev template %q may only contain a single %%d", tunName)
+	}
+	if tunName == "%d" {
+		return errors.New("please don't name your tun device '%d'")
+	}
+	// The shortest name a template can produce replaces %d with a single digit;
+	// if even that is not shorter than IFNAMSIZ the template can never yield a
+	// usable name.
+	if len(tunName)-len("%d")+len("0") >= unix.IFNAMSIZ {
+		return fmt.Errorf("tun.dev template %q would result in a name that is not shorter than the maximum device name length of %d", tunName, unix.IFNAMSIZ)
+	}
+	return nil
+}
+
+// findNextTunName resolves a tun.dev value into a concrete device name. A value
+// without a "%d" is returned unchanged; a "%d" placeholder (anywhere in the
+// name) has the lowest unused integer substituted in based on the devices
+// currently present.
+func findNextTunName(tunName string) (string, error) {
+	if err := validateTunName(tunName); err != nil {
+		return "", err
+	}
+	if !strings.Contains(tunName, "%d") {
+		return tunName, nil
+	}
+
+	links, err := netlink.LinkList()
+	if err != nil {
+		return "", err
+	}
+	used := make(map[string]struct{}, len(links))
+	for _, link := range links {
+		used[link.Attrs().Name] = struct{}{}
+	}
+	return nextTunName(tunName, used)
+}
+
+// nextTunName substitutes the lowest unused integer into a template's "%d"
+// placeholder, skipping any name present in used. tunName is assumed to have
+// already passed validateTunName (exactly one "%d", room for a digit). It errors
+// only if every candidate that is shorter than IFNAMSIZ is already taken.
+func nextTunName(tunName string, used map[string]struct{}) (string, error) {
+	prefix, suffix, _ := strings.Cut(tunName, "%d")
+	for i := 0; ; i++ {
+		candidateName := fmt.Sprintf("%s%d%s", prefix, i, suffix)
+		if len(candidateName) >= unix.IFNAMSIZ {
+			return "", fmt.Errorf("all device names matching template %q shorter than the maximum length of %d are already in use", tunName, unix.IFNAMSIZ)
+		}
+		if _, taken := used[candidateName]; !taken {
+			return candidateName, nil
+		}
+	}
+}
+
 // newTunGeneric does all the stuff common to different tun initialization paths. It will close your files on error.
 func newTunGeneric(c *config.C, l *slog.Logger, fd int, vpnNetworks []netip.Prefix) (*tun, error) {
 	tfd, err := newTunFd(fd)
@@ -768,7 +837,6 @@ func (t *tun) isGatewayInVpnNetworks(gwAddr netip.Addr) bool {
 
 func (t *tun) getGatewaysFromRoute(r *netlink.Route) routing.Gateways {
 	var gateways routing.Gateways
-
 	link, err := netlink.LinkByName(t.Device)
 	if err != nil {
 		t.l.Error("Ignoring route update: failed to get link by name", "deviceName", t.Device)

overlay/tun_linux_test.go

@@ -3,7 +3,12 @@
 
 package overlay
 
-import "testing"
+import (
+	"strings"
+	"testing"
+
+	"golang.org/x/sys/unix"
+)
 
 var runAdvMSSTests = []struct {
 	name     string
@@ -32,3 +37,91 @@ func TestTunAdvMSS(t *testing.T) {
 		})
 	}
 }
+
+func nameSet(names ...string) map[string]struct{} {
+	used := make(map[string]struct{}, len(names))
+	for _, n := range names {
+		used[n] = struct{}{}
+	}
+	return used
+}
+
+func TestValidateTunName(t *testing.T) {
+	// A device name must be shorter than IFNAMSIZ (i.e. IFNAMSIZ-1 chars max).
+	maxLenName := strings.Repeat("a", unix.IFNAMSIZ-1)
+
+	tests := []struct {
+		name    string
+		tmpl    string
+		wantErr bool
+	}{
+		{"short literal name is fine", "nebula1", false},
+		{"literal name at the max length is fine", maxLenName, false},
+		{"literal name at IFNAMSIZ is rejected", strings.Repeat("a", unix.IFNAMSIZ), true},
+		{"trailing template is fine", "nebula%d", false},
+		{"mid-string template is fine", "neb%dprod", false},
+		{"leading template is fine", "%dnebula", false},
+		{"template at the max static length is fine", strings.Repeat("a", unix.IFNAMSIZ-2) + "%d", false},
+		{"bare %d is rejected", "%d", true},
+		{"multiple %d is rejected", "neb%d%dprod", true},
+		{"template with no room for a digit is rejected", strings.Repeat("a", unix.IFNAMSIZ-1) + "%d", true},
+		{"mid-string template with no room for a digit is rejected", "neb%d" + strings.Repeat("a", unix.IFNAMSIZ-3), true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateTunName(tt.tmpl)
+			if tt.wantErr && err == nil {
+				t.Fatalf("expected an error for %q, got none", tt.tmpl)
+			}
+			if !tt.wantErr && err != nil {
+				t.Fatalf("unexpected error for %q: %v", tt.tmpl, err)
+			}
+		})
+	}
+}
+
+func TestNextTunName(t *testing.T) {
+	// A prefix long enough that only single-digit suffixes (0-9) fit within
+	// IFNAMSIZ, so marking all ten used exercises running out of names.
+	longPrefix := strings.Repeat("a", unix.IFNAMSIZ-2)
+	longUsed := make([]string, 0, 10)
+	for i := 0; i < 10; i++ {
+		longUsed = append(longUsed, longPrefix+string(rune('0'+i)))
+	}
+
+	tests := []struct {
+		name    string
+		tmpl    string
+		used    map[string]struct{}
+		want    string
+		wantErr bool
+	}{
+		{"nothing used picks zero", "nebula%d", nil, "nebula0", false},
+		{"skips taken names", "nebula%d", nameSet("nebula0", "nebula1"), "nebula2", false},
+		{"picks the lowest free index", "nebula%d", nameSet("nebula0", "nebula2"), "nebula1", false},
+		{"ignores unrelated names", "nebula%d", nameSet("eth0", "tun5"), "nebula0", false},
+		{"mid-string placeholder picks zero", "neb%dprod", nil, "neb0prod", false},
+		{"mid-string placeholder skips taken", "neb%dprod", nameSet("neb0prod", "neb1prod"), "neb2prod", false},
+		{"leading placeholder picks zero", "%dnebula", nameSet("tun0"), "0nebula", false},
+		{"runs out of names within IFNAMSIZ", longPrefix + "%d", nameSet(longUsed...), "", true},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := nextTunName(tt.tmpl, tt.used)
+			if tt.wantErr {
+				if err == nil {
+					t.Fatalf("expected an error, got name %q", got)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("unexpected error: %v", err)
+			}
+			if got != tt.want {
+				t.Errorf("got %q, want %q", got, tt.want)
+			}
+		})
+	}
+}