diff --git a/docs/DOCKER_COMPOSE.md b/docs/DOCKER_COMPOSE.md index e76f08e14..da5254233 100755 --- a/docs/DOCKER_COMPOSE.md +++ b/docs/DOCKER_COMPOSE.md @@ -30,6 +30,14 @@ services: - CHOWN # Required for root-entrypoint to chown /data + /tmp before dropping privileges - 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. + # + # If using host networking, REMOVE the sysctls block below and apply + # settings directly on your Host OS instead (sudo sysctl -w ...). + # --------------------------- sysctls: # ARP flux mitigation (reduces duplicate/ambiguous ARP behavior on host networking) net.ipv4.conf.all.arp_ignore: 1 net.ipv4.conf.all.arp_announce: 2 diff --git a/docs/docker-troubleshooting/arp-flux-sysctls.md b/docs/docker-troubleshooting/arp-flux-sysctls.md index 1070659a7..5e86583cd 100644 --- a/docs/docker-troubleshooting/arp-flux-sysctls.md +++ b/docs/docker-troubleshooting/arp-flux-sysctls.md @@ -21,7 +21,9 @@ The running environment does not provide the expected kernel sysctl values. This ## How to Correct the Issue -Set these sysctls at container runtime. +### Option A: Via Docker (Standard Bridge Networking) + +If you are using standard bridged networking (default), set these sysctls at container runtime. - In `docker-compose.yml` (preferred): ```yaml @@ -44,6 +46,24 @@ Set these sysctls at container runtime. > - 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`) + +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`. + +In this scenario, you must apply the settings directly on your host operating system: + +1. **Remove** the `sysctls` section from your `docker-compose.yml`. +2. **Apply** on the host immediately: + ```bash + sudo sysctl -w net.ipv4.conf.all.arp_ignore=1 + sudo sysctl -w net.ipv4.conf.all.arp_announce=2 + ``` +3. **Make persistent** by adding the following lines to `/etc/sysctl.conf` on the host: + ```text + net.ipv4.conf.all.arp_ignore=1 + net.ipv4.conf.all.arp_announce=2 + ``` + ## Additional Resources For broader Docker Compose guidance, see: diff --git a/install/production-filesystem/entrypoint.d/37-host-optimization.sh b/install/production-filesystem/entrypoint.d/37-host-optimization.sh index 4dc5d0196..2fea0ab96 100755 --- a/install/production-filesystem/entrypoint.d/37-host-optimization.sh +++ b/install/production-filesystem/entrypoint.d/37-host-optimization.sh @@ -22,6 +22,9 @@ 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. + Detection accuracy may be reduced until configured. See: https://docs.netalertx.com/docker-troubleshooting/arp-flux-sysctls/