{"record":{"id":"dfb26e48fe7c2092","repo":"slackhq/nebula","slug":"failed-to-bring-the-tun-device-up-s","errorCode":null,"errorMessage":"failed to bring the tun device up: %s","messagePattern":"failed to bring the tun device up: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_linux.go","lineNumber":490,"sourceCode":"\tifrq := ifreqQLEN{Name: devName, Value: int32(t.TXQueueLen)}\n\tif err = ioctl(t.ioctlFd, unix.SIOCSIFTXQLEN, uintptr(unsafe.Pointer(&ifrq))); err != nil {\n\t\t// If we can't set the queue length nebula will still work but it may lead to packet loss\n\t\tt.l.Error(\"Failed to set tun tx queue length\", \"error\", err)\n\t}\n\n\tconst modeNone = 1\n\tif err = netlink.LinkSetIP6AddrGenMode(link, modeNone); err != nil {\n\t\tt.l.Warn(\"Failed to disable link local address generation\", \"error\", err)\n\t}\n\n\tif err = t.addIPs(link); err != nil {\n\t\treturn err\n\t}\n\n\t// Bring up the interface\n\tifrf.Flags = ifrf.Flags | unix.IFF_UP\n\tif err = ioctl(t.ioctlFd, unix.SIOCSIFFLAGS, uintptr(unsafe.Pointer(&ifrf))); err != nil {\n\t\treturn fmt.Errorf(\"failed to bring the tun device up: %s\", err)\n\t}\n\n\t//set route MTU\n\tfor i := range t.vpnNetworks {\n\t\tif err = t.setDefaultRoute(t.vpnNetworks[i]); err != nil {\n\t\t\treturn fmt.Errorf(\"failed to set default route MTU: %w\", err)\n\t\t}\n\t}\n\n\t// Set the routes\n\tif err = t.addRoutes(false); err != nil {\n\t\treturn err\n\t}\n\n\t// Run the interface\n\tifrf.Flags = ifrf.Flags | unix.IFF_UP | unix.IFF_RUNNING\n\tif err = ioctl(t.ioctlFd, unix.SIOCSIFFLAGS, uintptr(unsafe.Pointer(&ifrf))); err != nil {\n\t\treturn fmt.Errorf(\"failed to run tun device: %s\", err)","sourceCodeStart":472,"sourceCodeEnd":508,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_linux.go#L472-L508","documentation":"Raised in tun.Activate when the SIOCSIFFLAGS ioctl that sets IFF_UP on the tun interface fails. The device exists and its flags were read successfully, but the kernel refused to bring the interface administratively up.","triggerScenarios":"Activate() calls ioctl(t.ioctlFd, SIOCSIFFLAGS, ...) with Flags|IFF_UP and the kernel returns an error — typically EPERM from missing privileges or ENODEV if the link vanished.","commonSituations":"Running nebula without root/CAP_NET_ADMIN; interface removed concurrently by a network manager; containers where SIOCSIFFLAGS on the host-owned device is denied.","solutions":["Run with sufficient privileges (root or CAP_NET_ADMIN) so interface flags can be changed.","Check the %s errno: EPERM = permissions, ENODEV = interface gone.","Ensure the device isn't being torn down concurrently (unmanaged in NetworkManager/systemd-networkd).","Manually verify with `ip link set <dev> up` to confirm it's a privilege vs device issue."],"exampleFix":"// before\n$ ./nebula -config config.yml  # EPERM\n// after\n$ sudo setcap cap_net_admin=ep ./nebula\n$ ./nebula -config config.yml","handlingStrategy":"validation","validationCode":"// require privileges before attempting to bring the interface up\nif os.Geteuid() != 0 && !hasCapNetAdmin() {\n    return errors.New(\"bringing tun up requires root or CAP_NET_ADMIN\")\n}","typeGuard":null,"tryCatchPattern":"if err := t.Activate(netstack); err != nil {\n    if strings.Contains(err.Error(), \"failed to bring the tun device up\") {\n        if errors.Is(err, os.ErrPermission) || strings.Contains(err.Error(), \"operation not permitted\") {\n            log.Error(\"grant CAP_NET_ADMIN: setcap cap_net_admin=ep <binary>\")\n        }\n    }\n}","preventionTips":["Deploy with setcap cap_net_admin=ep or run under a privileged service","Test `ip link set <dev> up` manually to separate privileges from device issues","Keep network managers from resetting interface flags during startup"],"tags":["network","tun","linux","permissions"],"backgroundTag":"operation-not-permitted","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}