{"record":{"id":"f3ccb8c29545df1f","repo":"netbirdio/netbird","slug":"add-jump-to-mss-clamp-chain-w","errorCode":null,"errorMessage":"add jump to MSS clamp chain: %w","messagePattern":"add jump to MSS clamp chain: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/firewall/iptables/router_linux.go","lineNumber":575,"sourceCode":"\tr.rules[\"static-nat-return\"] = rule2\n\n\treturn nil\n}\n\n// addMSSClampingRules adds MSS clamping rules to prevent fragmentation for forwarded traffic.\nfunc (r *router) addMSSClampingRules() error {\n\toverhead := uint16(ipv4TCPHeaderSize)\n\tif r.v6 {\n\t\toverhead = ipv6TCPHeaderSize\n\t}\n\tmss := r.mtu - overhead\n\n\t// Add jump rule from FORWARD chain in mangle table to our custom chain\n\tjumpRule := []string{\n\t\t\"-j\", chainRTMSSCLAMP,\n\t}\n\tif err := r.iptablesClient.Insert(tableMangle, chainFORWARD, 1, jumpRule...); err != nil {\n\t\treturn fmt.Errorf(\"add jump to MSS clamp chain: %w\", err)\n\t}\n\tr.rules[jumpMSSClamp] = jumpRule\n\n\truleOut := []string{\n\t\t\"-o\", r.wgIface.Name(),\n\t\t\"-p\", \"tcp\",\n\t\t\"--tcp-flags\", \"SYN,RST\", \"SYN\",\n\t\t\"-j\", \"TCPMSS\",\n\t\t\"--set-mss\", fmt.Sprintf(\"%d\", mss),\n\t}\n\tif err := r.iptablesClient.Append(tableMangle, chainRTMSSCLAMP, ruleOut...); err != nil {\n\t\treturn fmt.Errorf(\"add outbound MSS clamp rule: %w\", err)\n\t}\n\tr.rules[\"mss-clamp-out\"] = ruleOut\n\n\treturn nil\n}\n","sourceCodeStart":557,"sourceCodeEnd":593,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/firewall/iptables/router_linux.go#L557-L593","documentation":"addMSSClampingRules() inserts `-j NETBIRD-RT-MSSCLAMP` at position 1 of the mangle FORWARD chain so forwarded TCP SYNs get clamped to the interface MTU. A failure here is only logged by createContainers() (log.Errorf), not propagated, so the agent starts but forwarded TCP over the overlay may suffer fragmentation/blackholes on links with smaller MTUs.","triggerScenarios":"`iptables -t mangle -I FORWARD 1 -j NETBIRD-RT-MSSCLAMP` failing when iptable_mangle is not loaded, CAP_NET_ADMIN is missing, another tool rewrote FORWARD concurrently making the insert race, or the xtables lock is held.","commonSituations":"Stripped container hosts without the mangle table; hosts running firewalld that replaces the FORWARD chain wholesale; MTU-sensitive links (PPP, tunnels) where clamping mattered and silent failure shows as stalled TCP handshakes for routed traffic.","solutions":["Grep the agent log for 'failed to add MSS clamping rules' after `netbird up` (the error is not returned to the CLI)","Run `sudo iptables -t mangle -I FORWARD 1 -j NETBIRD-RT-MSSCLAMP` to see the real error","`modprobe iptable_mangle`","Reduce churn on the FORWARD chain (stop firewalld rewrites) or restart the agent after firewall changes","Verify afterwards: `sudo iptables -t mangle -S FORWARD | head` should show the NETBIRD-RT-MSSCLAMP jump"],"exampleFix":"// before\nif err := r.iptablesClient.Insert(tableMangle, chainFORWARD, 1, jumpRule...); err != nil {\n    return fmt.Errorf(\"add jump to MSS clamp chain: %w\", err)\n}\n\n// after: tolerate an identical jump inserted by a previous run\nexists, _ := r.iptablesClient.Exists(tableMangle, chainFORWARD, jumpRule...)\nif !exists {\n    if err := r.iptablesClient.Insert(tableMangle, chainFORWARD, 1, jumpRule...); err != nil {\n        return fmt.Errorf(\"add jump to MSS clamp chain: %w\", err)\n    }\n}\nr.rules[jumpMSSClamp] = jumpRule","handlingStrategy":"validation","validationCode":"func forwardChainProgrammable(ipt *iptables.IPTables) bool {\n    probe := []string{\"-j\", \"RETURN\"}\n    if err := ipt.Insert(\"mangle\", \"FORWARD\", 1, probe...); err != nil {\n        return false\n    }\n    _ = ipt.DeleteIfExists(\"mangle\", \"FORWARD\", probe...)\n    return true\n}","typeGuard":null,"tryCatchPattern":"This failure is log-only by design; catch it at the ops layer by grepping for 'failed to add MSS clamping rules' and re-running addMSSClampingRules on the next reconciliation instead of crashing.","preventionTips":["modprobe iptable_mangle on routed peers","Prevent firewalld/ufw from wholesale-replacing FORWARD","Verify `iptables -t mangle -S FORWARD` contains the NETBIRD-RT-MSSCLAMP jump after first start"],"tags":["network","linux","iptables","mss-clamping","mangle"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}