{"record":{"id":"5ff39462e57e0d53","repo":"slackhq/nebula","slug":"failed-to-set-tun-device-head-w","errorCode":null,"errorMessage":"failed to set tun device head: %w","messagePattern":"failed to set tun device head: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"overlay/tun_netbsd.go","lineNumber":313,"sourceCode":"\t\t\treturn fmt.Errorf(\"failed to set tun address %s: %s\", cidr.Addr().String(), err)\n\t\t}\n\t\treturn nil\n\t}\n\n\treturn fmt.Errorf(\"unknown address type %v\", cidr)\n}\n\nfunc (t *tun) Activate() error {\n\tmode := int32(unix.IFF_BROADCAST)\n\terr := ioctl(uintptr(t.fd), TUNSIFMODE, uintptr(unsafe.Pointer(&mode)))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to set tun device mode: %w\", err)\n\t}\n\n\tv := 1\n\terr = ioctl(uintptr(t.fd), TUNSIFHEAD, uintptr(unsafe.Pointer(&v)))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to set tun device head: %w\", err)\n\t}\n\n\terr = t.doIoctlByName(unix.SIOCSIFMTU, uint32(t.MTU))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to set tun mtu: %w\", err)\n\t}\n\n\tfor i := range t.vpnNetworks {\n\t\terr = t.addIp(t.vpnNetworks[i])\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\treturn t.addRoutes(false)\n}\n\nfunc (t *tun) doIoctlByName(ctl uintptr, value uint32) error {","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_netbsd.go#L295-L331","documentation":"This error is returned by the NetBSD TUN device's Activate method when the TUNSIFHEAD ioctl fails. TUNSIFHEAD enables the 4-byte address-family header on packets read/written to the tun device, which is required to carry both IPv4 and IPv6 over the same tunnel. If the kernel rejects the ioctl, the device cannot be used for dual-stack VPN traffic, so activation aborts.","triggerScenarios":"Calling Activate() on a NetBSD tun where the ioctl(fd, TUNSIFHEAD, &1) call fails — e.g. the file descriptor is not a tun device, the tun driver is not loaded, or the fd lacks sufficient permissions.","commonSituations":"Running the VPN binary on a NetBSD host where /dev/tun was not opened correctly, the kernel lacks the tun(4) driver, or the process runs without root privileges to configure the interface.","solutions":["Verify the process runs as root or with the privileges needed to configure network interfaces.","Confirm the fd passed to newTun is a valid NetBSD tun device (/dev/tunN) and the tun kernel module is loaded (modload if_tun).","Check the wrapped errno (%w) with errors.Is to identify whether it is EBADF/ENOTTY/EPERM and fix accordingly.","Rebuild/reboot the kernel with tun(4) support if the ioctl returns ENOTTY or ENODEV."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// Before Activate: ensure we are root and the tun driver is present\nif os.Geteuid() != 0 {\n    return fmt.Errorf(\"activating tun device requires root privileges\")\n}\nif _, err := os.Stat(\"/dev/tun\"); err != nil {\n    return fmt.Errorf(\"tun device not available: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := t.Activate(); err != nil {\n    var syscallErr syscall.Errno\n    if errors.As(err, &syscallErr) {\n        switch syscallErr {\n        case unix.EPERM, unix.EACCES:\n            // missing privileges\n        case unix.ENOTTY, unix.ENODEV:\n            // fd is not a tun device / driver missing\n        }\n    }\n    return fmt.Errorf(\"tun activation failed: %w\", err)\n}","preventionTips":["Run the VPN process as root or with equivalent interface-configuration privileges.","Confirm the NetBSD kernel has tun(4) support (modload if_tun) before starting.","Check errors.Is/errors.As on the wrapped errno to diagnose ioctl failures precisely.","Open the tun device through the library's newTun path rather than passing arbitrary fds."],"tags":["netbsd","tun","ioctl","network"],"backgroundTag":"tun-ioctl-failed","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"}