Architecture and security

Discovery and provisioning

The capture socket is Linux AF_PACKET, bound to the configured interface without promiscuous mode. A classic BPF filter selects IPv4 GRE in the kernel, including up to two outer VLAN tags. The bounded parser validates Ethernet, IPv4 header and packet lengths (including options), fragmentation, GRE flags and protocol, inner VLAN ID and source MAC. Only packets addressed to the capture interface's IPv4 address can trigger provisioning; outgoing packets are ignored.

For each new remote, native NETLINK_ROUTE requests create an unkeyed gretap interface and a VLAN interface per configured mapping. Requests include kernel acknowledgments, bounded attributes and a three-second receive timeout. Hash tables index remote IPv4 addresses and MAC addresses. One poll loop owns capture, API clients and signalfd signals, so readers never race deletions. The capture loop handles at most 64 packets per batch and the API accepts at most 16 clients per iteration. Network and firewall setup happen synchronously for new peers and MACs.

The daemon links only against libc: the hash tables, string buffers, INI reader and process helper are small in-tree modules (hashmap.c, compat.c, softgred_config.c, helper.c) covered by unit tests and fuzzing. Allocation failure aborts the process, which systemd restarts, rather than limping on with a half-built state.

Kernel bridges and gretap forward established traffic. Repeated packets from known MACs use hash lookups and do not spawn commands or recreate interfaces. ebtables receives explicit argument arrays, never shell command strings, and each external command has a three-second deadline.

Protocol scope

Accepted traffic uses outer IPv4, unkeyed GRE v0 with zero flags, Ethernet protocol 0x6558 (RFC 2784) and one inner VLAN mapped to a configured bridge. Inner ARP, IPv4 and IPv6 are forwarded by the kernel. The parser supports up to two outer VLAN tags and IPv4 options.

Packets with an unknown VLAN, a foreign destination, a zero, multicast or loopback source IPv4, an invalid source MAC, IPv4 fragmentation, GRE keys, checksums or other optional fields, or a nonzero GRE version cannot provision. Outer IPv6, untagged inner Ethernet and inner QinQ are unsupported. The parser does not authenticate or validate inner IP payloads.

Firewall and trust model

SoftGRE owns SOFTGRE_IN in the ebtables nat table and SOFTGRE_OUT in filter. Jumps are scoped to each owned tunnel's VLAN interfaces: nat PREROUTING validates source MACs before bridge learning or local delivery, and filter FORWARD and OUTPUT validate destination MACs. This protects both bridged traffic and local services, and prevents a MAC forged on a different tunnel from poisoning the bridge forwarding database. Egress broadcast and multicast are permitted for ARP, DHCP and neighbor discovery. It never flushes built-in chains or changes their policies. Startup refuses preexisting owned chain names, preventing accidental takeover of another instance or abandoned firewall state. Each learned MAC installs one ingress and one egress rule; cleanup revokes permissions and removes jumps before deleting owned chains. Packet-derived values never enter a shell.

GRE has no built-in authentication, and observing a source MAC is discovery, not identity verification. Because the daemon trusts the packet's source IPv4 and MAC, a host that can send IP protocol 47 to the capture interface with a spoofed source can otherwise create tunnels, inject frames onto the service bridges, or claim a subscriber's MAC before its real AP does and deny it service (a MAC stays bound to the first remote that uses it).

Set global.allow-remotes to the authorized AP addresses or networks so only they can provision. An explicit allowlist must contain at least one address or CIDR; empty entries and binary NUL bytes in configuration are rejected. The allowlist checks the claimed source IPv4, so an attacker able to spoof an authorized address can still pass it. Enforce ingress anti-spoofing and restrict protocol 47 to trusted remotes or a protected transport; the allowlist provides no cryptographic peer authentication. A capacity limit (a full tunnel or the slot table) only drops the offending packet: it never pauses provisioning for other peers. The AP's own frames can also be learned, using one client slot per tunnel. DHCP option 82 is only trustworthy when the AP strips client-supplied copies (see DHCP and subscriber services).

Limits and performance

Compile-time ceilings are 4096 tunnel slots, 1024 MACs per tunnel and ten VLAN-to-bridge mappings; free interface names and host resources also affect capacity. Capture buffering requests 4 MiB, which the kernel may cap. A setup failure backs off new work globally for one second. Kernel deletion failures keep records for another cleanup attempt, and an incomplete full cleanup pauses discovery until a successful SIGUSR1 retry. Full cleanup flushes owned MAC chains in bulk instead of launching a process per MAC.

Steady-state discovery uses average O(1) IPv4 and MAC lookups. Initial setup needs netlink round trips and two firewall processes per MAC, which temporarily block the owner loop, each for at most its timeout. For high churn or very large MAC populations, measure setup latency, ebtables rule traversal and packet drops before choosing a deployment size. AF_PACKET still copies captured packets into user space; the daemon does not use PACKET_MMAP or claim zero-copy capture.

Relationship to Alcatel-Lucent/Nokia 7750 SR

SoftGRE implements packet-driven GRE discovery and Linux bridging. The corresponding 7750 SR feature is WLAN-GW soft-GRE. Nokia describes learning AP encapsulation without configuring every AP endpoint. Its WLAN-GW design uses ISA/ESA resources; available features depend on the platform and SR OS release. See the official Wi-Fi aggregation and offload guide.

The subscriber-management example is documented in Nokia's Basic Open SSID configuration guide. For residential bridging, Nokia documents soft-GRE access in its Virtual Residential Gateway guide. This project's service boundary is the Linux bridge; routing, DHCP and subscriber services are designed separately. No interoperability or throughput comparison with a physical 7750 SR has been measured, and matching the encapsulation subset alone does not establish feature parity.