Address CodeRabbit review: Clarify sysctl behavior in host network mode

Author: Meatloaf Bot

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

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:
 

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.