docs: Clarify ARP flux sysctl limitations with host networking#1552
docs: Clarify ARP flux sysctl limitations with host networking#1552MrMeatikins wants to merge 1 commit intonetalertx:mainfrom
Conversation
📝 WalkthroughWalkthroughDocumentation updates clarifying ARP flux mitigation configuration, specifically addressing incompatibility of sysctls in host network mode and providing separate guidance for bridge versus host networking approaches. Changes
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Tip Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs). Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/DOCKER_COMPOSE.md`:
- Around line 33-43: The documentation block incorrectly states that sysctl
overrides are blocked when using network_mode: host and instructs removal of the
sysctls block; update the text to reflect the actual behavior: keep the sysctls
(net.ipv4.conf.all.arp_ignore and net.ipv4.conf.all.arp_announce) when using
network_mode (NETALERTX_NETWORK_MODE) with host networking and ensure the note
explains that these sysctls require appropriate privileges (e.g.,
NET_ADMIN/capabilities) to be applied to the host namespace — only instruct
users to remove or apply sysctls when they explicitly lack those privileges or
when they prefer to configure on the Host OS via sudo sysctl -w.
In `@docs/docker-troubleshooting/arp-flux-sysctls.md`:
- Around line 49-65: Update the "Option B: Via Host OS (Required for
`network_mode: host`)" section to acknowledge that `sysctls` can be applied when
`network_mode: host` if the container is granted the `NET_ADMIN` capability (as
used in the repository's docker-compose.yml, install/docker/docker-compose.yml,
and install/docker/docker-compose.dev.yml), and remove the absolute statement
that `runc`/modern Docker always disallows `net.*` sysctls in host namespaces;
either reword to explain the correct pattern (host networking + cap_add:
NET_ADMIN + sysctls) or split into two cases (without NET_ADMIN: must set on
host, with NET_ADMIN: allowed in compose), keeping the examples and the guidance
on removing sysctls from compose only for the no-NET_ADMIN case.
In `@install/production-filesystem/entrypoint.d/37-host-optimization.sh`:
- Around line 25-26: Update the note to remove the absolute prohibition and
state that sysctl behavior with network_mode: host is capability- and
version-dependent: when a service grants NET_ADMIN, sysctls such as
net.ipv4.conf.all.arp_ignore and net.ipv4.conf.all.arp_announce may be accepted
and will modify the host namespace in practice, whereas other sysctls or older
Docker/Compose versions may still reject them; reword the line to reflect this
conditional behavior and recommend documenting the need for NET_ADMIN and
testing on target Docker/Compose versions.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: faa5be3c-6b60-4353-acb2-a437a78a1f1c
📒 Files selected for processing (3)
docs/DOCKER_COMPOSE.mddocs/docker-troubleshooting/arp-flux-sysctls.mdinstall/production-filesystem/entrypoint.d/37-host-optimization.sh
| # --- 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 |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify that existing compose files use network_mode: host WITH sysctls
echo "=== Checking docker-compose.yml ==="
rg -A2 'network_mode.*host' docker-compose.yml
echo ""
rg -A2 'sysctls:' docker-compose.yml
echo "=== Checking install/docker/docker-compose.yml ==="
rg -A2 'network_mode.*host' install/docker/docker-compose.yml
echo ""
rg -A2 'sysctls:' install/docker/docker-compose.yml
echo "=== Checking install/docker/docker-compose.dev.yml ==="
rg -A2 'network_mode.*host' install/docker/docker-compose.dev.yml
echo ""
rg -A2 'sysctls:' install/docker/docker-compose.dev.ymlRepository: netalertx/NetAlertX
Length of output: 1079
Major documentation error: Guidance contradicts the working baseline configuration and established behavior.
The comment claims that "modern Docker/runc will correctly block sysctl overrides" with network_mode: host and instructs users to "REMOVE the sysctls block below" when using host mode. This is contradicted by three critical facts:
-
All baseline compose files in this repository use both
network_mode: hostAND these sysctls together (docker-compose.yml, install/docker/docker-compose.yml, and install/docker/docker-compose.dev.yml all combine them successfully). -
The baseline defaults to host networking (line 21:
network_mode: ${NETALERTX_NETWORK_MODE:-host}), yet the new comment instructs removal of sysctls for host mode. This internal contradiction proves the guidance is incorrect. -
Established behavior confirms sysctls work with host networking + NET_ADMIN capability—they are accepted in practice and modify the host's network namespace directly, exactly as intended for ARP flux mitigation.
The documentation should be corrected to reflect actual working behavior instead of providing incorrect guidance that contradicts the codebase itself.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/DOCKER_COMPOSE.md` around lines 33 - 43, The documentation block
incorrectly states that sysctl overrides are blocked when using network_mode:
host and instructs removal of the sysctls block; update the text to reflect the
actual behavior: keep the sysctls (net.ipv4.conf.all.arp_ignore and
net.ipv4.conf.all.arp_announce) when using network_mode (NETALERTX_NETWORK_MODE)
with host networking and ensure the note explains that these sysctls require
appropriate privileges (e.g., NET_ADMIN/capabilities) to be applied to the host
namespace — only instruct users to remove or apply sysctls when they explicitly
lack those privileges or when they prefer to configure on the Host OS via sudo
sysctl -w.
| ### 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 | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Check if compose files combine network_mode: host with sysctls AND cap_add: NET_ADMIN
for file in docker-compose.yml install/docker/docker-compose.yml install/docker/docker-compose.dev.yml; do
echo "=== $file ==="
echo "Network mode:"
rg 'network_mode.*host' "$file"
echo "Capabilities:"
rg -A5 'cap_add:' "$file" | head -10
echo "Sysctls:"
rg -A2 'sysctls:' "$file"
echo ""
doneRepository: netalertx/NetAlertX
Length of output: 1817
Option B oversimplifies and contradicts actual supported configuration.
This section claims that "modern Docker versions (specifically the runc runtime) will not allow you to set net.* sysctls via the container configuration" with network_mode: host. However, all three Docker Compose files in this repository (docker-compose.yml, install/docker/docker-compose.yml, and install/docker/docker-compose.dev.yml) successfully combine network_mode: host with the exact sysctls mentioned (net.ipv4.conf.all.arp_ignore and net.ipv4.conf.all.arp_announce) alongside cap_add: NET_ADMIN.
The critical detail is that with NET_ADMIN capability, these sysctls ARE accepted and function as intended to mitigate ARP flux. The documentation presents a false dichotomy by suggesting sysctls must be set on the host OS when using host networking, when in reality the NetAlertX pattern (host networking + NET_ADMIN + sysctls in compose) is the supported and working approach.
Revise Option B to acknowledge that the NET_ADMIN capability enables sysctls to work with host networking, or refactor these options to better reflect the actual supported configuration pattern rather than implying host-level sysctl configuration is necessary.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/docker-troubleshooting/arp-flux-sysctls.md` around lines 49 - 65, Update
the "Option B: Via Host OS (Required for `network_mode: host`)" section to
acknowledge that `sysctls` can be applied when `network_mode: host` if the
container is granted the `NET_ADMIN` capability (as used in the repository's
docker-compose.yml, install/docker/docker-compose.yml, and
install/docker/docker-compose.dev.yml), and remove the absolute statement that
`runc`/modern Docker always disallows `net.*` sysctls in host namespaces; either
reword to explain the correct pattern (host networking + cap_add: NET_ADMIN +
sysctls) or split into two cases (without NET_ADMIN: must set on host, with
NET_ADMIN: allowed in compose), keeping the examples and the guidance on
removing sysctls from compose only for the no-NET_ADMIN case.
| 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. |
There was a problem hiding this comment.
Guidance contradicts learned behavior with NET_ADMIN capability.
The note states "you cannot set these via docker-compose sysctls" when using network_mode: host, but this conflicts with the retrieved learning:
"When a Docker Compose service uses
network_mode: hostand also hasNET_ADMINcapability, sysctls likenet.ipv4.conf.all.arp_ignoreandnet.ipv4.conf.all.arp_announceare accepted in practice (not rejected) and modify the host's network namespace directly. This is intentional for ARP flux mitigation."
The actual behavior is capability and version-dependent, not a blanket prohibition. All existing compose files in this repository successfully combine network_mode: host with these sysctls and NET_ADMIN capability.
Based on learnings, when a Docker Compose service uses network_mode: host and also has NET_ADMIN capability, sysctls like net.ipv4.conf.all.arp_ignore and net.ipv4.conf.all.arp_announce are accepted in practice (not rejected) and modify the host's network namespace directly. This is intentional for ARP flux mitigation. The claim that "net.* sysctls are always rejected with host networking" is incorrect — behavior varies by Docker version, sysctl, and capabilities.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@install/production-filesystem/entrypoint.d/37-host-optimization.sh` around
lines 25 - 26, Update the note to remove the absolute prohibition and state that
sysctl behavior with network_mode: host is capability- and version-dependent:
when a service grants NET_ADMIN, sysctls such as net.ipv4.conf.all.arp_ignore
and net.ipv4.conf.all.arp_announce may be accepted and will modify the host
namespace in practice, whereas other sysctls or older Docker/Compose versions
may still reject them; reword the line to reflect this conditional behavior and
recommend documenting the need for NET_ADMIN and testing on target
Docker/Compose versions.
1 participant
Fixes #1546.
Description
This PR addresses the issue where the
sysctlsconfiguration block for ARP flux mitigation causes errors on modern Docker engines when usingnetwork_mode: host.Changes:
37-host-optimization.shwarning to explicitly advise setting sysctls on the host OS when using host networking.docs/docker-troubleshooting/arp-flux-sysctls.mddescribing the different requirements for standard bridged networking vs. host networking.docker-compose.yml(DOCKER_COMPOSE.mdequivalent) to prevent users from applying thesysctlsblock incorrectly in host network mode.Summary by CodeRabbit