Skip to content

Agent Mesh

nano-init: say which profile's tun setup failed, and what to change

Antonio Ojea7148729d36d1
diff --git a/cmd/nano-init/isolation.go b/cmd/nano-init/isolation.go
index 0ba365d9..b323db6d 100644
--- a/cmd/nano-init/isolation.go
+++ b/cmd/nano-init/isolation.go
@@ -15,8 +15,11 @@
package main
import (
+ "errors"
"fmt"
+ "os"
"strings"
+ "syscall"
"github.com/vishvananda/netlink"
)
@@ -71,3 +74,45 @@ func isolationError(links []string) error {
strings.Join(foreign, ", "),
)
}
+
+// tunDevice is the clone device every tun is created through. Its absence and
+// its permissions are two different problems with two different fixes, which
+// is the whole reason for the diagnosis below.
+const tunDevice = "/dev/net/tun"
+
+// describeTunFailure turns a netlink error into the thing to change.
+func describeTunFailure(err error) string {
+ _, statErr := os.Stat(tunDevice)
+ return tunHint(err, statErr)
+}
+
+// tunHint explains a failed tun creation.
+//
+// The old message asked whether the kernel had CONFIG_TUN, which is the right
+// question in a microVM and useless in a container, where the same failure
+// means the device was not passed in or the capability was not granted. The
+// profiles fail differently, so they are told apart here rather than left to
+// whoever is reading a log at the time.
+func tunHint(err error, statErr error) string {
+ switch {
+ case os.IsNotExist(statErr):
+ return "there is no " + tunDevice + ". In a microVM that means a guest kernel built without CONFIG_TUN" +
+ " (the stock Firecracker CI kernels carry vsock but no tun driver; 6.18.41 has it)." +
+ " In a container it means the device was not passed in: `--device /dev/net/tun` for docker," +
+ " or a device plugin for a Kubernetes pod, since the device cgroup denies it by default"
+
+ case os.IsPermission(statErr):
+ return tunDevice + " exists but cannot be opened. Under Kubernetes the device cgroup denies it unless a" +
+ " device plugin grants it; a user namespace does not help, because opening the device is checked" +
+ " against the host and not against the namespace"
+
+ case errors.Is(err, syscall.EPERM), errors.Is(err, syscall.EACCES):
+ return "creating a tun was refused. It needs CAP_NET_ADMIN in the user namespace that owns this network" +
+ " namespace: `--cap-add NET_ADMIN` for docker, securityContext.capabilities.add: [NET_ADMIN] for a pod," +
+ " or a user namespace of your own, which grants it over the namespaces it owns"
+
+ case errors.Is(err, syscall.ENODEV):
+ return "the kernel has no tun driver. Rebuild the guest kernel with CONFIG_TUN=y"
+ }
+ return "the tun device could not be created, and the cause is not one this knows how to explain"
+}
diff --git a/cmd/nano-init/isolation_test.go b/cmd/nano-init/isolation_test.go
index 86ca96c2..7e956917 100644
--- a/cmd/nano-init/isolation_test.go
+++ b/cmd/nano-init/isolation_test.go
@@ -15,10 +15,79 @@
package main
import (
+ "errors"
+ "io/fs"
"strings"
+ "syscall"
"testing"
)
+func TestTunHint(t *testing.T) {
+ notExist := &fs.PathError{Op: "stat", Path: tunDevice, Err: syscall.ENOENT}
+ denied := &fs.PathError{Op: "stat", Path: tunDevice, Err: syscall.EACCES}
+
+ for _, tc := range []struct {
+ name string
+ err error
+ statErr error
+ // want is a phrase naming the fix, so the test fails when the advice
+ // stops matching the cause rather than only when the wording changes.
+ want string
+ }{
+ {
+ name: "a guest kernel with no tun driver names CONFIG_TUN",
+ err: syscall.ENODEV,
+ statErr: notExist,
+ want: "CONFIG_TUN",
+ },
+ {
+ name: "a container missing the device is told to pass it in",
+ err: syscall.ENOENT,
+ statErr: notExist,
+ want: "--device /dev/net/tun",
+ },
+ {
+ name: "a pod missing the device is pointed at a device plugin",
+ err: syscall.ENOENT,
+ statErr: notExist,
+ want: "device plugin",
+ },
+ {
+ name: "a device that cannot be opened is not blamed on capabilities",
+ statErr: denied,
+ err: syscall.EPERM,
+ want: "device cgroup",
+ },
+ {
+ name: "a refused create names the capability",
+ err: syscall.EPERM,
+ want: "CAP_NET_ADMIN",
+ },
+ {
+ name: "EACCES is treated as EPERM is",
+ err: syscall.EACCES,
+ want: "CAP_NET_ADMIN",
+ },
+ {
+ name: "the kernel driver case is named even when the device exists",
+ err: syscall.ENODEV,
+ want: "CONFIG_TUN=y",
+ },
+ {
+ name: "an unrecognised cause says so rather than guessing",
+ err: errors.New("something else entirely"),
+ want: "not one this knows how to explain",
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ got := tunHint(tc.err, tc.statErr)
+ if !strings.Contains(got, tc.want) {
+ t.Errorf("tunHint(%v, %v) = %q, want it to mention %q", tc.err, tc.statErr, got, tc.want)
+ }
+ })
+ }
+}
+
func TestIsolationError(t *testing.T) {
for _, tc := range []struct {
name string