{"record":{"id":"bf112f9255455f4d","repo":"slackhq/nebula","slug":"failed-to-set-tun-address-s-s","errorCode":null,"errorMessage":"failed to set tun address %s: %s","messagePattern":"failed to set tun address (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_freebsd.go","lineNumber":433,"sourceCode":"\t\t\t\tLen:    unix.SizeofSockaddrInet4,\n\t\t\t\tFamily: unix.AF_INET,\n\t\t\t\tAddr:   getBroadcast(cidr).As4(),\n\t\t\t},\n\t\t\tMaskAddr: unix.RawSockaddrInet4{\n\t\t\t\tLen:    unix.SizeofSockaddrInet4,\n\t\t\t\tFamily: unix.AF_INET,\n\t\t\t\tAddr:   prefixToMask(cidr).As4(),\n\t\t\t},\n\t\t\tVHid: 0,\n\t\t}\n\t\ts, err := unix.Socket(unix.AF_INET, unix.SOCK_DGRAM, unix.IPPROTO_IP)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tdefer syscall.Close(s)\n\t\t// Note: unix.SIOCAIFADDR corresponds to FreeBSD's OSIOCAIFADDR\n\t\tif err := ioctl(uintptr(s), unix.SIOCAIFADDR, uintptr(unsafe.Pointer(&ifr))); err != nil {\n\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\tif cidr.Addr().Is6() {\n\t\tifr := ifreqAlias6{\n\t\t\tName: t.deviceBytes(),\n\t\t\tAddr: unix.RawSockaddrInet6{\n\t\t\t\tLen:    unix.SizeofSockaddrInet6,\n\t\t\t\tFamily: unix.AF_INET6,\n\t\t\t\tAddr:   cidr.Addr().As16(),\n\t\t\t},\n\t\t\tPrefixMask: unix.RawSockaddrInet6{\n\t\t\t\tLen:    unix.SizeofSockaddrInet6,\n\t\t\t\tFamily: unix.AF_INET6,\n\t\t\t\tAddr:   prefixToMask(cidr).As16(),\n\t\t\t},\n\t\t\tLifetime: addrLifetime{","sourceCodeStart":415,"sourceCodeEnd":451,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_freebsd.go#L415-L451","documentation":"addIp configures an IPv4 address on the FreeBSD tun interface via the SIOCAIFADDR ioctl on a routing socket. When that ioctl fails, the address string and the raw errno are wrapped in this error. It means the kernel rejected the ifaliasreq for this interface/address combination.","triggerScenarios":"Calling Activate() (which calls addIp per configured VPN network prefix) where the ioctl SIOCAIFADDR on the routing socket returns an error — invalid CIDR, address not belonging to the interface's subnet, or device not properly opened.","commonSituations":"Configuring an address whose subnet doesn't match the destination in the ifreq; the tun interface not yet up / wrong device name; running without sufficient privileges (ioctl on routing socket requires root or CAP_NET_ADMIN-equivalent on FreeBSD); malformed vpnNetworks config.","solutions":["Check the wrapped errno in the message — EPERM/EACCES means run as root or grant privileges; EINVAL/EADDRNOTAVAIL means the address/subnet is invalid","Ensure the configured CIDR is a valid IPv4 prefix (e.g. 10.0.0.1/24) and the address is inside the declared network","Verify the tun device was created and named correctly before Activate is called","Check kernel logs (dmesg) for ifconfig/ioctl rejections"],"exampleFix":"// before\nvpnNetworks: []netip.Prefix{netip.MustParsePrefix(\"10.0.0.1/16\")}, // host bits set\n// after\np, _ := netip.ParsePrefix(\"10.0.0.1/16\")\np = p.Masked() // 10.0.0.0/16\nvpnNetworks: []netip.Prefix{netip.MustParsePrefix(\"10.0.0.1/16\"), } // ensure .Masked() applied where required","handlingStrategy":"validation","validationCode":"p, err := netip.ParsePrefix(cfgAddr)\nif err != nil || !p.Addr().Is4() {\n    return fmt.Errorf(\"invalid IPv4 tun address %q\", cfgAddr)\n}","typeGuard":"func isIPv4Prefix(p netip.Prefix) bool { return p.IsValid() && p.Addr().Is4() }","tryCatchPattern":"if err := dev.Activate(); err != nil {\n    var serr syscall.Errno\n    if strings.Contains(err.Error(), \"failed to set tun address\") && errors.As(err, &serr) && (serr == syscall.EPERM || serr == syscall.EACCES) {\n        return fmt.Errorf(\"insufficient privileges to assign tun address: %w\", err)\n    }\n    return err\n}","preventionTips":["Validate IPv4 prefixes at config load with netip.ParsePrefix","Run with root/privileges when configuring interface addresses","Ensure the tun device exists and is open before Activate","Mask host bits or ensure address/subnet consistency before ioctl"],"tags":["freebsd","tun","ioctl","network-config","ipv4"],"backgroundTag":"ioctl-address-config-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"}