Skip to content

Commit 89811cd

Browse files
jokob-skjokob-sk
authored
Merge pull request #1544 from adamoutler/built-in-tests
Improve built-in test used during system startup - thanks @adamoutler 🙏
2 parents c73ce83 + b854206 commit 89811cd

14 files changed

Lines changed: 270 additions & 170 deletions

‎docker-compose.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,9 @@ services:
1919
- CHOWN # Required for root-entrypoint to chown /data + /tmp before dropping privileges
2020
- SETUID # Required for root-entrypoint to switch to non-root user
2121
- SETGID # Required for root-entrypoint to switch to non-root group
22+
sysctls: # ARP flux mitigation for host networking accuracy
23+
net.ipv4.conf.all.arp_ignore: 1
24+
net.ipv4.conf.all.arp_announce: 2
2225
volumes:
2326

2427
- type: volume # Persistent Docker-managed Named Volume for storage

‎docs/DOCKER_COMPOSE.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ services:
3030
- CHOWN # Required for root-entrypoint to chown /data + /tmp before dropping privileges
3131
- SETUID # Required for root-entrypoint to switch to non-root user
3232
- SETGID # Required for root-entrypoint to switch to non-root group
33+
sysctls: # ARP flux mitigation (reduces duplicate/ambiguous ARP behavior on host networking)
34+
net.ipv4.conf.all.arp_ignore: 1
35+
net.ipv4.conf.all.arp_announce: 2
3336

3437
volumes:
3538
- type: volume # Persistent Docker-managed named volume for config + database

‎docs/docker-troubleshooting/arp-flux-sysctls.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# ARP Flux Sysctls Not Set
2+
3+
## Issue Description
4+
5+
NetAlertX detected that ARP flux protection sysctls are not set as expected:
6+
7+
- `net.ipv4.conf.all.arp_ignore=1`
8+
- `net.ipv4.conf.all.arp_announce=2`
9+
10+
## Security Ramifications
11+
12+
This is not a direct container breakout risk, but detection quality can degrade:
13+
14+
- Incorrect IP/MAC associations
15+
- Device state flapping
16+
- Unreliable topology or presence data
17+
18+
## Why You're Seeing This Issue
19+
20+
The running environment does not provide the expected kernel sysctl values. This is common in Docker setups where sysctls were not explicitly configured.
21+
22+
## How to Correct the Issue
23+
24+
Set these sysctls at container runtime.
25+
26+
- In `docker-compose.yml` (preferred):
27+
```yaml
28+
services:
29+
netalertx:
30+
sysctls:
31+
net.ipv4.conf.all.arp_ignore: 1
32+
net.ipv4.conf.all.arp_announce: 2
33+
```
34+
35+
- For `docker run`:
36+
```bash
37+
docker run \
38+
--sysctl net.ipv4.conf.all.arp_ignore=1 \
39+
--sysctl net.ipv4.conf.all.arp_announce=2 \
40+
ghcr.io/netalertx/netalertx:latest
41+
```
42+
43+
> **Note:** Setting `net.ipv4.conf.all.arp_ignore` and `net.ipv4.conf.all.arp_announce` may fail with "operation not permitted" unless the container is run with elevated privileges. To resolve this, you can:
44+
> - Use `--privileged` with `docker run`.
45+
> - 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.
46+
47+
## Additional Resources
48+
49+
For broader Docker Compose guidance, see:
50+
51+
- [DOCKER_COMPOSE.md](https://docs.netalertx.com/DOCKER_COMPOSE)

‎install/docker/docker-compose.dev.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ services:
1313
- CHOWN
1414
- SETUID
1515
- SETGID
16+
sysctls:
17+
net.ipv4.conf.all.arp_ignore: 1
18+
net.ipv4.conf.all.arp_announce: 2
1619
volumes:
1720
- type: volume
1821
source: netalertx_data

‎install/docker/docker-compose.yml‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,9 @@ services:
1313
- CHOWN
1414
- SETUID
1515
- SETGID
16+
sysctls:
17+
net.ipv4.conf.all.arp_ignore: 1
18+
net.ipv4.conf.all.arp_announce: 2
1619
volumes:
1720
- type: volume
1821
source: netalertx_data

‎install/production-filesystem/entrypoint.d/36-override-individual-settings.sh‎

100644100755
Lines changed: 10 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -9,28 +9,17 @@ if [ ! -f "${NETALERTX_CONFIG}/app.conf" ]; then
99
exit 0
1010
fi
1111

12-
# Helper: set or append config key safely
13-
set_config_value() {
14-
_key="$1"
15-
_value="$2"
16-
17-
# Remove newlines just in case
18-
_value=$(printf '%s' "$_value" | tr -d '\n\r')
19-
20-
# Escape sed-sensitive chars
21-
_escaped=$(printf '%s\n' "$_value" | sed 's/[\/&]/\\&/g')
12+
if [ -n "${LOADED_PLUGINS:-}" ]; then
13+
echo "[ENV] Applying LOADED_PLUGINS override"
14+
value=$(printf '%s' "$LOADED_PLUGINS" | tr -d '\n\r')
15+
# declare delimiter for sed and escape it along with / and &
16+
delim='|'
17+
escaped=$(printf '%s\n' "$value" | sed "s/[\/${delim}&]/\\&/g")
2218

23-
if grep -q "^${_key}=" "${NETALERTX_CONFIG}/app.conf"; then
24-
sed -i "s|^${_key}=.*|${_key}=${_escaped}|" "${NETALERTX_CONFIG}/app.conf"
19+
if grep -q '^LOADED_PLUGINS=' "${NETALERTX_CONFIG}/app.conf"; then
20+
# use same delimiter when substituting
21+
sed -i "s${delim}^LOADED_PLUGINS=.*${delim}LOADED_PLUGINS=${escaped}${delim}" "${NETALERTX_CONFIG}/app.conf"
2522
else
26-
echo "${_key}=${_value}" >> "${NETALERTX_CONFIG}/app.conf"
23+
echo "LOADED_PLUGINS=${value}" >> "${NETALERTX_CONFIG}/app.conf"
2724
fi
28-
}
29-
30-
# ------------------------------------------------------------
31-
# LOADED_PLUGINS override
32-
# ------------------------------------------------------------
33-
if [ -n "${LOADED_PLUGINS:-}" ]; then
34-
echo "[ENV] Applying LOADED_PLUGINS override"
35-
set_config_value "LOADED_PLUGINS" "$LOADED_PLUGINS"
3625
fi

‎install/production-filesystem/entrypoint.d/37-host-optimization.sh‎

100644100755
Lines changed: 11 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,30 @@
11
#!/bin/sh
22

3-
# 37-host-optimization.sh: Apply and validate network optimizations (ARP flux fix)
3+
# 37-host-optimization.sh: Detect ARP flux sysctl configuration.
44
#
5-
# This script improves detection accuracy by ensuring proper ARP behavior.
6-
# It attempts to apply sysctl settings and warns if not possible.
5+
# This script does not change host/kernel settings.
76

8-
# --- Color Codes ---
9-
RED=$(printf '\033[1;31m')
107
YELLOW=$(printf '\033[1;33m')
118
RESET=$(printf '\033[0m')
129

13-
# --- Skip flag ---
14-
if [ -n "${SKIP_OPTIMIZATIONS:-}" ]; then
15-
exit 0
16-
fi
17-
18-
# --- Helpers ---
19-
20-
get_sysctl() {
21-
sysctl -n "$1" 2>/dev/null || echo "unknown"
22-
}
23-
24-
set_sysctl_if_needed() {
25-
key="$1"
26-
expected="$2"
27-
28-
current="$(get_sysctl "$key")"
29-
30-
# Already correct
31-
if [ "$current" = "$expected" ]; then
32-
return 0
33-
fi
34-
35-
# Try to apply
36-
if sysctl -w "$key=$expected" >/dev/null 2>&1; then
37-
return 0
38-
fi
39-
40-
# Failed
41-
return 1
42-
}
43-
44-
# --- Apply Settings (best effort) ---
45-
4610
failed=0
4711

48-
set_sysctl_if_needed net.ipv4.conf.all.arp_ignore 1 || failed=1
49-
set_sysctl_if_needed net.ipv4.conf.all.arp_announce 2 || failed=1
50-
set_sysctl_if_needed net.ipv4.conf.default.arp_ignore 1 || failed=1
51-
set_sysctl_if_needed net.ipv4.conf.default.arp_announce 2 || failed=1
12+
[ "$(sysctl -n net.ipv4.conf.all.arp_ignore 2>/dev/null || echo unknown)" = "1" ] || failed=1
13+
[ "$(sysctl -n net.ipv4.conf.all.arp_announce 2>/dev/null || echo unknown)" = "2" ] || failed=1
5214

53-
# --- Validate final state ---
54-
55-
all_ignore="$(get_sysctl net.ipv4.conf.all.arp_ignore)"
56-
all_announce="$(get_sysctl net.ipv4.conf.all.arp_announce)"
57-
58-
# --- Warning Output ---
59-
60-
if [ "$all_ignore" != "1" ] || [ "$all_announce" != "2" ]; then
15+
if [ "$failed" -eq 1 ]; then
6116
>&2 printf "%s" "${YELLOW}"
62-
>&2 cat <<EOF
17+
>&2 cat <<'EOF'
6318
══════════════════════════════════════════════════════════════════════════════
64-
⚠️ ATTENTION: ARP flux protection not enabled.
65-
66-
NetAlertX relies on ARP for device detection. Your system currently allows
67-
ARP replies from incorrect interfaces (ARP flux), which may result in:
68-
69-
• False devices being detected
70-
• IP/MAC mismatches
71-
• Flapping device states
72-
• Incorrect network topology
73-
74-
This is common when running in Docker or multi-interface environments.
75-
76-
──────────────────────────────────────────────────────────────────────────
77-
Recommended fix (Docker Compose):
78-
79-
sysctls:
80-
net.ipv4.conf.all.arp_ignore: 1
81-
net.ipv4.conf.all.arp_announce: 2
82-
83-
──────────────────────────────────────────────────────────────────────────
84-
Alternatively, apply on the host:
19+
⚠️ WARNING: ARP flux sysctls are not set.
8520
21+
Expected values:
8622
net.ipv4.conf.all.arp_ignore=1
8723
net.ipv4.conf.all.arp_announce=2
8824
89-
Detection accuracy may be reduced until this is configured.
25+
Detection accuracy may be reduced until configured.
26+
27+
See: https://docs.netalertx.com/docker-troubleshooting/arp-flux-sysctls/
9028
══════════════════════════════════════════════════════════════════════════════
9129
EOF
9230
>&2 printf "%s" "${RESET}"

‎install/production-filesystem/entrypoint.sh‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,10 +86,11 @@ for script in "${ENTRYPOINT_CHECKS}"/*; do
8686
fi
8787
script_name=$(basename "$script" | sed 's/^[0-9]*-//;s/\.(sh|py)$//;s/-/ /g')
8888
echo "--> ${script_name} "
89-
if [ -n "${SKIP_STARTUP_CHECKS:-}" ] && echo "${SKIP_STARTUP_CHECKS}" | grep -q "\b${script_name}\b"; then
90-
printf "%sskip%s\n" "${GREY}" "${RESET}"
91-
continue
92-
fi
89+
if [ -n "${SKIP_STARTUP_CHECKS:-}" ] &&
90+
printf '%s' "${SKIP_STARTUP_CHECKS}" | grep -wFq -- "${script_name}"; then
91+
printf "%sskip%s\n" "${GREY}" "${RESET}"
92+
continue
93+
fi
9394

9495
"$script"
9596
NETALERTX_DOCKER_ERROR_CHECK=$?

‎install/production-filesystem/services/healthcheck.sh‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -48,11 +48,13 @@ else
4848
log_error "python /app/server is not running"
4949
fi
5050

51-
# 5. Check port 20211 is open and contains "netalertx"
52-
if curl -sf --max-time 10 "http://localhost:${PORT:-20211}" | grep -i "netalertx" > /dev/null; then
53-
log_success "Port ${PORT:-20211} is responding and contains 'netalertx'"
51+
# 5. Check port 20211 is open
52+
CHECK_ADDR="${LISTEN_ADDR:-127.0.0.1}"
53+
[ "${CHECK_ADDR}" == "0.0.0.0" ] && CHECK_ADDR="127.0.0.1"
54+
if timeout 10 bash -c "</dev/tcp/${CHECK_ADDR}/${PORT:-20211}" 2>/dev/null; then
55+
log_success "Port ${PORT:-20211} is responding"
5456
else
55-
log_error "Port ${PORT:-20211} is not responding or doesn't contain 'netalertx'"
57+
log_error "Port ${PORT:-20211} is not responding"
5658
fi
5759

5860
# NOTE: GRAPHQL_PORT might not be set and is initailized as a setting with a default value in the container. It can also be initialized via APP_CONF_OVERRIDE
@@ -71,4 +73,4 @@ else
7173
echo "[HEALTHCHECK] ❌ One or more health checks failed"
7274
fi
7375

74-
exit $EXIT_CODE
76+
exit $EXIT_CODE

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ nav:
2020
- Docker Updates: UPDATES.md
2121
- Docker Maintenance: DOCKER_MAINTENANCE.md
2222
- Docker Startup Troubleshooting:
23+
- ARP flux sysctls: docker-troubleshooting/arp-flux-sysctls.md
2324
- Aufs capabilities: docker-troubleshooting/aufs-capabilities.md
2425
- Excessive capabilities: docker-troubleshooting/excessive-capabilities.md
2526
- File permissions: docker-troubleshooting/file-permissions.md

0 commit comments

Comments
 (0)