Skip to content

docs: Clarify ARP flux sysctl limitations with host networking #1552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MrMeatikins wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: Clarify ARP flux sysctl limitations with host networking #1552

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions docs/DOCKER_COMPOSE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment on lines +33 to 43
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 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.yml

Repository: 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:

  1. All baseline compose files in this repository use both network_mode: host AND these sysctls together (docker-compose.yml, install/docker/docker-compose.yml, and install/docker/docker-compose.dev.yml all combine them successfully).

  2. 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.

  3. 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.

Expand Down
22 changes: 21 additions & 1 deletion docs/docker-troubleshooting/arp-flux-sysctls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
```
Comment on lines +49 to +65
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 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 ""
done

Repository: 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.


## Additional Resources

For broader Docker Compose guidance, see:
Expand Down
3 changes: 3 additions & 0 deletions install/production-filesystem/entrypoint.d/37-host-optimization.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Comment on lines +25 to +26
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

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: 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 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.


Detection accuracy may be reduced until configured.

See: https://docs.netalertx.com/docker-troubleshooting/arp-flux-sysctls/
Expand Down