cilium/cilium · error

setsockopt(IP_TRANSPARENT) for %s failed: %w

Error message

setsockopt(IP_TRANSPARENT) for %s failed: %w

What it means

In transparent DNS proxy mode, setSoMarks enables IP_TRANSPARENT so the proxy can use a non-host address as the source. This error wraps a failed setsockopt(IP_TRANSPARENT) and includes the IP family name. IP_TRANSPARENT requires CAP_NET_ADMIN and kernel support for the family-specific option.

Source

Thrown at pkg/fqdn/dnsproxy/proxy.go:839

//   - So the client socket can not be left lingering around, as it causes network traffic destined
//     for the source pod to be intercepted to the dnsproxy, which is exactly what we want but only
//     until a DNS response has been received.
func setSoMarks(fd int, ipFamily ipfamily.IPFamily, secId identity.NumericIdentity) error {
	// Set SO_MARK to allow datapath to know these upstream packets from an egress proxy
	mark := linux_defaults.MakeMagicMark(linux_defaults.MagicMarkEgress, secId)
	err := unix.SetsockoptUint64(fd, unix.SOL_SOCKET, unix.SO_MARK, uint64(mark))
	if err != nil {
		return fmt.Errorf("error setting SO_MARK: %w", err)
	}

	// Rest of the options are only set in the transparent mode.
	if !option.Config.DNSProxyEnableTransparentMode {
		return nil
	}

	// Set IP_TRANSPARENT to be able to use a non-host address as the source address
	if err := unix.SetsockoptInt(fd, ipFamily.SocketOptsFamily, ipFamily.SocketOptsTransparent, 1); err != nil {
		return fmt.Errorf("setsockopt(IP_TRANSPARENT) for %s failed: %w", ipFamily.Name, err)
	}

	// Set SO_REUSEADDR to allow binding to an address that is already used by some other
	// connection in a lingering state. This is needed in cases where we close a client
	// connection but the client issues new requests re-using its source port. In that case we
	// need to be able to reuse the address likely very soon after the prior close, which may
	// not be allowed without this option.
	if err := unix.SetsockoptInt(int(fd), unix.SOL_SOCKET, unix.SO_REUSEADDR, 1); err != nil {
		return fmt.Errorf("setsockopt(SO_REUSEADDR) failed: %w", err)
	}

	// Set SO_REUSEPORT to allow two active connections to bind to the same address and
	// port. Normally this would not be needed, but is set to allow a new connection to be
	// created on a port where the old connection may not yet be closed. If two UDP sockets
	// using the same port due to this option were reading at the same time, the OS stack would
	// distribute incoming packets to them essentially randomly. We do not want that, so we
	// strive to avoid that situation. This may be helpful in avoiding bind errors in some cases
	// regardless.

View on GitHub (pinned to ac7b90affa)

Solutions

1. Grant CAP_NET_ADMIN to the process (required for IP_TRANSPARENT).
2. Disable DNSProxyEnableTransparentMode if you do not need non-host source addresses.
3. Verify kernel/config supports IP_TRANSPARENT and IPV6_TRANSPARENT (CONFIG_IPV6).

Example fix

// before
// DNSProxyEnableTransparentMode: true  // in unprivileged container
// after
// DNSProxyEnableTransparentMode: false
// (or add NET_ADMIN capability)

probe, err := unix.Socket(family, unix.SOCK_DGRAM, 0)
if err == nil {
    defer unix.Close(probe)
    if err := unix.SetsockoptInt(probe, optFamily, optTransparent, 1); err != nil {
        return fmt.Errorf("IP_TRANSPARENT unavailable: %w", err)
    }
}

if err := setSoMarks(fd, family, secID); err != nil {
    if errors.Is(err, unix.EPERM) || errors.Is(err, unix.EOPNOTSUPP) {
        // fall back to non-transparent mode or surface config error
    }
    return err
}

When it happens

Trigger: option.Config.DNSProxyEnableTransparentMode is true and unix.SetsockoptInt(fd, ipFamily.SocketOptsFamily, ipFamily.SocketOptsTransparent, 1) fails, usually EPERM without CAP_NET_ADMIN or EOPNOTSUPP/ENOPROTOOPT on kernels lacking the option for IPv6 (IPV6_TRANSPARENT).

Common situations: Transparent mode enabled in an unprivileged container; IPv6 socket on a kernel built without IPV6_TRANSPARENT; seccomp blocking thesockopt.

Related errors

• error setting SO_MARK: %w
• creating map base pinning directory: %w
• removing bpffs directory at %s: %w
• unable to create bpf mount directory: %w
• failed to mount %s: %w

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/4583a772cd692de9. Report an issue: GitHub.