slackhq/nebula · error

failed to set tun mtu: %v

Error message

failed to set tun mtu: %v

What it means

During Activate on macOS, nebula opens a control socket for the device and sets the interface MTU with the SIOCSIFMTU ioctl using t.DefaultMTU. If that ioctl fails, the errno is wrapped in this error. It means the kernel refused to apply the MTU to the utun device.

Source

Thrown at overlay/tun_darwin.go:182

func (t *tun) Activate() error {
	devName := t.deviceBytes()

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

	fd := uintptr(s)

	// Set the MTU on the device
	ifm := ifreqMTU{Name: devName, MTU: int32(t.DefaultMTU)}
	if err = ioctl(fd, unix.SIOCSIFMTU, uintptr(unsafe.Pointer(&ifm))); err != nil {
		return fmt.Errorf("failed to set tun mtu: %v", err)
	}

	// Get the device flags
	ifrf := ifReq{Name: devName}
	if err = ioctl(fd, unix.SIOCGIFFLAGS, uintptr(unsafe.Pointer(&ifrf))); err != nil {
		return fmt.Errorf("failed to get tun flags: %s", err)
	}

	linkAddr, err := getLinkAddr(t.Device)
	if err != nil {
		return err
	}
	if linkAddr == nil {
		return fmt.Errorf("unable to discover link_addr for tun interface")
	}
	t.linkAddr = linkAddr

	for _, network := range t.vpnNetworks {

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Run nebula with root privileges (sudo) so SIOCSIFMTU is permitted.
2. Verify tun.dev matches the interface name reported at startup (e.g. utun5) and is not misconfigured.
3. Check tun.mtu in config; remove it to use the default (1300) if a custom value is rejected.
4. Confirm the utun interface still exists in `ifconfig` before Activate runs.

Example fix

// before
sudo ./nebula -config config.yml   # run as non-root user fails SIOCSIFMTU
// after
sudo ./nebula -config config.yml   # run as root, or setcap/grant network privileges

if os.Geteuid() != 0 {
    return errors.New("nebula needs root on macOS to set interface MTU")
}

if err := start(); err != nil && strings.Contains(err.Error(), "failed to set tun mtu") {
    // advise: run with sudo, check tun.dev and tun.mtu config
}

When it happens

Trigger: ioctl(fd, SIOCSIFMTU, ifreqMTU{devName, DefaultMTU}) fails during tun.Activate — device name wrong/nonexistent, permission denied (not root), or MTU value rejected by the kernel.

Common situations: Running nebula without root/sudo on macOS (ioctls on interfaces need privileges); tun.dev renamed/mismatched with the actual utun name; extremely small or large MTU values in config.

Related errors

• failed to get tun flags: %s
• CTLIOCGINFO: %v
• system socket: %v
• SYS_CONNECT: %v
• failed to retrieve tun name: %w

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