docs: Clarify ARP flux sysctl limitations with host networking#1552
docs: Clarify ARP flux sysctl limitations with host networking#1552jokob-sk merged 2 commits intonetalertx:mainfrom
Conversation
📝 WalkthroughWalkthroughDocumentation updates clarifying ARP flux mitigation configuration, specifically addressing incompatibility of applying ARP sysctls in host network mode and providing separate guidance for Docker (bridge) vs host-level approaches, plus expanded runtime warning text explaining NET_ADMIN implications. 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
install/production-filesystem/entrypoint.d/37-host-optimization.sh
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
🧹 Nitpick comments (1)
docs/docker-troubleshooting/arp-flux-sysctls.md (1)
24-27: Clarify that Option A modifies the host namespace when using host networking.When using
network_mode: hostwithNET_ADMIN, the sysctls configured in the container runtime will modify the host's network namespace directly, not an isolated container namespace. This is an important detail for users to understand the scope of impact. The entrypoint script (37-host-optimization.sh) explicitly notes: "When granted, these sysctls will modify the host namespace."Consider adding a sentence after line 26 to clarify this behavior, such as:
Note: When using
network_mode: host, these sysctls will modify the host's network namespace directly.Based on learnings: "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."🤖 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 24 - 27, The doc's Option A text needs an explicit warning that when using network_mode: host together with the NET_ADMIN capability the container-set sysctls will modify the host network namespace; update the "Option A: Via Docker (Standard Bridge Networking or `network_mode: host` with `NET_ADMIN`)" paragraph to add a sentence after the existing line (after the sentence starting "If you are using standard bridged networking...") stating: "Note: when using `network_mode: host` with `NET_ADMIN`, sysctls configured at container runtime (e.g., net.ipv4.conf.all.arp_ignore, net.ipv4.conf.all.arp_announce) will be applied to the host's network namespace directly." Also reference the entrypoint script 37-host-optimization.sh if helpful.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/docker-troubleshooting/arp-flux-sysctls.md`:
- Around line 24-27: The doc's Option A text needs an explicit warning that when
using network_mode: host together with the NET_ADMIN capability the
container-set sysctls will modify the host network namespace; update the "Option
A: Via Docker (Standard Bridge Networking or `network_mode: host` with
`NET_ADMIN`)" paragraph to add a sentence after the existing line (after the
sentence starting "If you are using standard bridged networking...") stating:
"Note: when using `network_mode: host` with `NET_ADMIN`, sysctls configured at
container runtime (e.g., net.ipv4.conf.all.arp_ignore,
net.ipv4.conf.all.arp_announce) will be applied to the host's network namespace
directly." Also reference the entrypoint script 37-host-optimization.sh if
helpful.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: b86a3715-bfed-4a6e-b3e7-228ccecaf54f
📒 Files selected for processing (3)
docs/DOCKER_COMPOSE.mddocs/docker-troubleshooting/arp-flux-sysctls.mdinstall/production-filesystem/entrypoint.d/37-host-optimization.sh
🚧 Files skipped from review as they are similar to previous changes (2)
- install/production-filesystem/entrypoint.d/37-host-optimization.sh
- docs/DOCKER_COMPOSE.md
|
Can we merge this or are you still working on it @adamoutler ? |
|
Good to go. |
|
Thanks @adamoutler ! |
3 participants
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