slackhq/nebula · error

failed to set tun address %s: %s

Error message

failed to set tun address %s: %s

What it means

addIp configures an IPv4 address on the tun device using the SIOCAIFADDR ioctl on a UDP socket. If the ioctl fails, the library wraps the errno with this message naming the CIDR being assigned. Commonly the interface is down, the address/mask is invalid, or permission is lacking.

Source

Thrown at overlay/tun_netbsd.go:264

		req.DstAddr = unix.RawSockaddrInet4{
			Len:    unix.SizeofSockaddrInet4,
			Family: unix.AF_INET,
			Addr:   cidr.Addr().As4(),
		}
		req.MaskAddr = unix.RawSockaddrInet4{
			Len:    unix.SizeofSockaddrInet4,
			Family: unix.AF_INET,
			Addr:   prefixToMask(cidr).As4(),
		}

		s, err := unix.Socket(unix.AF_INET, unix.SOCK_DGRAM, unix.IPPROTO_IP)
		if err != nil {
			return err
		}
		defer syscall.Close(s)

		if err := ioctl(uintptr(s), unix.SIOCAIFADDR, uintptr(unsafe.Pointer(&req))); err != nil {
			return fmt.Errorf("failed to set tun address %s: %s", cidr.Addr(), err)
		}

		return nil
	}

	if cidr.Addr().Is6() {
		var req ifreqAlias6
		req.Name = t.deviceBytes()
		req.Addr = unix.RawSockaddrInet6{
			Len:    unix.SizeofSockaddrInet6,
			Family: unix.AF_INET6,
			Addr:   cidr.Addr().As16(),
		}
		req.PrefixMask = unix.RawSockaddrInet6{
			Len:    unix.SizeofSockaddrInet6,
			Family: unix.AF_INET6,
			Addr:   prefixToMask(cidr).As16(),
		}

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Run the process as root (or with appropriate privilege) — tun ioctls require elevated rights
2. Create the device first: ifconfig tun0 create, and bring it up before/after address assignment
3. Verify the IPv4 CIDR is valid and matches the configured range

Example fix

// before
sudo ./app
// after
# as root, and ensure device exists first
ifconfig tun0 create
sudo ./app

if err := validateCIDRv4(cidr); err != nil { return err }
if os.Geteuid() != 0 { return errors.New("tun address setup requires root") }

if err := iface.AddIp(cidr); err != nil {
    log.Printf("add IPv4 %s failed: %v — check privileges and that the device exists", cidr, err)
}

When it happens

Trigger: Calling Activate()/addIp with an IPv4 CIDR while the SIOCAIFADDR ioctl returns an error (EADDRNOTAVAIL, EINVAL, EPERM, or interface not created/up).

Common situations: Running without root/CAP_NET_ADMIN on NetBSD; assigning an address before the tun device exists; netmask mismatches.

Related errors

• unknown address type %v
• failed to set tun device mode: %w
• failed to set tun device head: %w
• failed to set tun mtu: %w
• failed to set tun mtu: %v

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/47701d5f42430796. Report an issue: GitHub.