{"record":{"id":"207ffaf0722ffe0e","repo":"netbirdio/netbird","slug":"wgctl-w","errorCode":null,"errorMessage":"wgctl: %w","messagePattern":"wgctl: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/iface/configurer/kernel_unix.go","lineNumber":220,"sourceCode":"\t\tUpdateOnly:        true,\n\t\tReplaceAllowedIPs: true,\n\t\tAllowedIPs:        newAllowedIPs,\n\t}\n\n\tconfig := wgtypes.Config{\n\t\tPeers: []wgtypes.PeerConfig{peer},\n\t}\n\terr = c.configure(config)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"remove allowed IP %s on interface %s: %w\", allowedIP, c.deviceName, err)\n\t}\n\treturn nil\n}\n\nfunc (c *KernelConfigurer) getPeer(ifaceName, peerPubKey string) (wgtypes.Peer, error) {\n\twg, err := wgctrl.New()\n\tif err != nil {\n\t\treturn wgtypes.Peer{}, fmt.Errorf(\"wgctl: %w\", err)\n\t}\n\tdefer func() {\n\t\terr = wg.Close()\n\t\tif err != nil {\n\t\t\tlog.Errorf(\"Got error while closing wgctl: %v\", err)\n\t\t}\n\t}()\n\n\twgDevice, err := wg.Device(ifaceName)\n\tif err != nil {\n\t\treturn wgtypes.Peer{}, fmt.Errorf(\"get device %s: %w\", ifaceName, err)\n\t}\n\tfor _, peer := range wgDevice.Peers {\n\t\tif peer.PublicKey.String() == peerPubKey {\n\t\t\treturn peer, nil\n\t\t}\n\t}\n\treturn wgtypes.Peer{}, ErrPeerNotFound","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/configurer/kernel_unix.go#L202-L238","documentation":"KernelConfigurer.getPeer could not create a wgctrl client with wgctrl.New(). On Linux and FreeBSD wgctrl opens a netlink socket (falling back to the /dev/wg userspace protocol) to talk to the kernel WireGuard module; construction fails when the module is unavailable or the socket cannot be opened due to permissions. This happens before any device query, so every kernel-mode peer/device operation through getPeer is blocked by it.","triggerScenarios":"Kernel WireGuard module not loaded or not built into the kernel (no CONFIG_WIREGUARD); wireguard-kmod package missing on FreeBSD; process without CAP_NET_ADMIN opening the netlink socket; restrictive container or seccomp profile blocking netlink.","commonSituations":"Bare-metal or VM host without wireguard installed; minimal container images lacking kernel headers/modules; agent started unprivileged; custom kernels compiled without WireGuard support.","solutions":["Load the module: sudo modprobe wireguard (and install wireguard-tools/DKMS so it persists)","Run the daemon as root or with CAP_NET_ADMIN","If kernel WireGuard cannot be provided, use the userspace configurer (wireguard-go device with NewUSPConfigurer) instead","Probe wgctrl.New() at startup and log a clear 'kernel WireGuard unavailable' diagnostic"],"exampleFix":"// before: assume kernel WireGuard exists\nkernelCfg := configurer.NewKernelConfigurer(ifaceName)\n\n// after: probe and fall back to the userspace configurer\nif _, err := wgctrl.New(); err != nil {\n\tlog.Warnf(\"kernel WireGuard unavailable (%v), falling back to userspace\", err)\n\t// build a wireguard-go device and use configurer.NewUSPConfigurer(dev, ifaceName, recorder)\n}","handlingStrategy":"fallback","validationCode":"// probe kernel WireGuard support once at startup\nfunc kernelWgAvailable() bool {\n\tc, err := wgctrl.New()\n\tif err != nil {\n\t\treturn false\n\t}\n\tdefer c.Close()\n\treturn true\n}","typeGuard":null,"tryCatchPattern":"wg, err := wgctrl.New()\nif err != nil {\n\tlog.Warnf(\"kernel WireGuard unavailable (%v); using userspace device\", err)\n\t// construct wireguard-go device + NewUSPConfigurer instead of NewKernelConfigurer\n}","preventionTips":["Ship or load the wireguard kernel module on hosts meant to run kernel mode","Grant the daemon CAP_NET_ADMIN (containers: --cap-add=NET_ADMIN)","Probe wgctrl.New() at startup and select kernel vs userspace mode from the result","Log the probe failure once with a clear remediation hint instead of failing per operation"],"tags":["wireguard","wgctrl","kernel-module","privileges","go","environment"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}