From df3ca50c5c7ba5564507bf03eceb15558090e220 Mon Sep 17 00:00:00 2001 From: Meatloaf Bot Date: Tue, 10 Mar 2026 12:04:30 -0400 Subject: [PATCH] Address CodeRabbit review: Clarify sysctl behavior in host network mode --- docs/DOCKER_COMPOSE.md | 10 +++++----- docs/docker-troubleshooting/arp-flux-sysctls.md | 8 ++++---- .../entrypoint.d/37-host-optimization.sh | 6 ++++-- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/DOCKER_COMPOSE.md b/docs/DOCKER_COMPOSE.md index da525423..92c93cc3 100755 --- a/docs/DOCKER_COMPOSE.md +++ b/docs/DOCKER_COMPOSE.md @@ -31,12 +31,12 @@ services: - SETUID # Required for root-entrypoint to switch to non-root user - SETGID # Required for root-entrypoint to switch to non-root group # --- ARP FLUX MITIGATION --- - # Note: If running in `network_mode: host`, modern Docker/runc will correctly - # block sysctl overrides via the container configuration to prevent - # unauthorized changes to the host's global kernel settings. + # Note: When using `network_mode: host`, these sysctls require the + # NET_ADMIN capability to be applied to the host namespace. # - # If using host networking, REMOVE the sysctls block below and apply - # settings directly on your Host OS instead (sudo sysctl -w ...). + # If your environment restricts capabilities, or you prefer to configure + # them on the Host OS, REMOVE the sysctls block below and apply via: + # sudo sysctl -w net.ipv4.conf.all.arp_ignore=1 net.ipv4.conf.all.arp_announce=2 # --------------------------- sysctls: # ARP flux mitigation (reduces duplicate/ambiguous ARP behavior on host networking) net.ipv4.conf.all.arp_ignore: 1 diff --git a/docs/docker-troubleshooting/arp-flux-sysctls.md b/docs/docker-troubleshooting/arp-flux-sysctls.md index 5e86583c..786a2f46 100644 --- a/docs/docker-troubleshooting/arp-flux-sysctls.md +++ b/docs/docker-troubleshooting/arp-flux-sysctls.md @@ -21,9 +21,9 @@ The running environment does not provide the expected kernel sysctl values. This ## How to Correct the Issue -### Option A: Via Docker (Standard Bridge Networking) +### Option A: Via Docker (Standard Bridge Networking or `network_mode: host` with `NET_ADMIN`) -If you are using standard bridged networking (default), set these sysctls at container runtime. +If you are using standard bridged networking, or `network_mode: host` and the container is granted the `NET_ADMIN` capability (as is the default recommendation), set these sysctls at container runtime. - In `docker-compose.yml` (preferred): ```yaml @@ -46,9 +46,9 @@ If you are using standard bridged networking (default), set these sysctls at con > - Use `--privileged` with `docker run`. > - Use the more restrictive `--cap-add=NET_ADMIN` (or `cap_add: [NET_ADMIN]` in `docker-compose` service definitions) to allow the sysctls to be applied at runtime. -### Option B: Via Host OS (Required for `network_mode: host`) +### Option B: Via Host OS (Fallback for `network_mode: host`) -If you are running the container with `network_mode: host`, modern Docker versions (specifically the `runc` runtime) **will not allow** you to set `net.*` sysctls via the container configuration. Attempting to do so will result in an OCI runtime error: `sysctl "net.ipv4.conf.all.arp_announce" not allowed in host network namespace`. +If you are running the container with `network_mode: host` and cannot grant the `NET_ADMIN` capability, or if your container runtime environment explicitly blocks sysctl overrides, applying these settings via the container configuration will fail. Attempting to do so without sufficient privileges typically results in an OCI runtime error: `sysctl "net.ipv4.conf.all.arp_announce" not allowed in host network namespace`. In this scenario, you must apply the settings directly on your host operating system: diff --git a/install/production-filesystem/entrypoint.d/37-host-optimization.sh b/install/production-filesystem/entrypoint.d/37-host-optimization.sh index 2fea0ab9..d282ffbf 100755 --- a/install/production-filesystem/entrypoint.d/37-host-optimization.sh +++ b/install/production-filesystem/entrypoint.d/37-host-optimization.sh @@ -22,8 +22,10 @@ if [ "$failed" -eq 1 ]; then net.ipv4.conf.all.arp_ignore=1 net.ipv4.conf.all.arp_announce=2 - Note: If using 'network_mode: host', you cannot set these via docker-compose - sysctls. You must configure them directly on your host operating system instead. + Note: If using 'network_mode: host', setting these via docker-compose sysctls + requires the NET_ADMIN capability. When granted, these sysctls will + modify the host namespace. Otherwise, you must configure them directly + on your host operating system instead. Detection accuracy may be reduced until configured.