vh/NetAlertX
1
0
Fork 0
mirror of https://github.com/jokob-sk/NetAlertX.git synced 2026-03-31 07:12:23 -07:00
Code Issues Actions 15 Packages Projects Releases Wiki Activity

Merge pull request #1393 from adamoutler/Synology-fixes

Browse Source 
Enable Root PUID; Add AUFS filesystem capability warnings and documentation
This commit is contained in:
Jokob @NetAlertX
2026-01-09 12:56:48 +11:00
committed by GitHub
parent 28dd9fb5f2 51e31d8854
commit 77803c18be
8 changed files with 411 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

167
docs/docker-troubleshooting/aufs-capabilities.md Normal file
View File

@@ -0,0 +1,167 @@
# AUFS Legacy Storage Driver Support
## Issue Description
NetAlertX automatically detects the legacy `aufs` storage driver, which is commonly found on older Synology NAS devices (DSM 6.x/7.0.x) or Linux systems where the underlying filesystem lacks `d_type` support. This occurs on older ext4 and other filesystems which did not support capabilites at time of last formatting. While ext4 currently support capabilities and filesystem overlays, older variants of ext4 did not and require a reformat to enable the support. Old variants result in docker choosing `aufs` and newer may use `overlayfs`.
**The Technical Limitation:**
AUFS (Another Union File System) does not support or preserve extended file attributes (`xattrs`) during Docker image extraction. NetAlertX relies on these attributes to grant granular privileges (`CAP_NET_RAW` and `CAP_NET_ADMIN`) to network scanning binaries like `arp-scan`, `nmap`, and `nbtscan`.
**The Result:**
When the container runs as a standard non-root user (default) on AUFS, these binaries are stripped of their capabilities. Consequently, layer-2 network discovery will fail silently, find zero devices, or exit with "Operation not permitted" errors.
## Operational Logic
The container is designed to inspect the runtime environment at startup (`/root-entrypoint.sh`). It respects user configuration first, falling back to safe defaults (with warnings) where necessary.
**Behavior Matrix:**
| Filesystem | PUID Config | Runtime User | Outcome |
| :--- | :--- | :--- | :--- |
| **Modern (Overlay2/Btrfs)** | Unset | `20211` | **Secure.** Full functionality via preserved `setcap`. |
| **Legacy (AUFS)** | Unset | `20211` | **Degraded.** Logs warning. L2 scans fail due to missing perms. |
| **Legacy (AUFS)** | `PUID=0` | `Root` | **Functional.** Root privileges bypass capability requirements. |
| **Legacy (AUFS)** | `PUID=1000` | `1000` | **Degraded.** Logs warning. L2 scans fail due to missing perms. |
### Warning Log
When AUFS is detected without root privileges, the system emits the following warning during startup:
> ⚠️ WARNING: Reduced functionality (AUFS + non-root user).
>
> AUFS strips Linux file capabilities, so tools like arp-scan, nmap, and nbtscan fail when NetAlertX runs as a non-root PUID.
>
> **Action:** Set PUID=0 on AUFS hosts for full functionality.
## Security Ramifications
To mitigate the AUFS limitation, the recommended fix is to run the application as the **root** user (`PUID=0`).
* **Least Privilege:** Even when running as root, NetAlertX applies `cap_drop: - ALL` and re-adds only the strictly necessary capabilities (`NET_RAW`, `NET_ADMIN`). This maintains a "least privilege" posture, though it is inherently less secure than running as a specific UID.
* **Attack Surface:** Running as UID 0 increases the theoretical attack surface. If the container were compromised, the attacker would have root access *inside* the container (though still isolated from the host by the Docker runtime).
* **Legacy Risks:** Reliance on the deprecated AUFS driver often indicates an older OS kernel or filesystem configuration, which may carry its own unpatched vulnerabilities compared to modern `overlay2` or `btrfs` setups.
## How to Correct the Issue
Choose the scenario that best matches your environment and security requirements.
### Scenario A: Modern Systems (Recommended)
**Context:** Systems using `overlay2`, `btrfs`, or `zfs`.
**Action:** No action required. The system auto-configures `PUID=20211`.
```yaml
services:
netalertx:
image: netalertx/netalertx
# No PUID/PGID needed; defaults to secure non-root
```
### Scenario B: Legacy/Synology AUFS (The Fix)
**Context:** Synology DSM 6.x/7.x or Linux hosts using AUFS.
**Action:** Explicitly elevate to root. This bypasses the need for file capabilities because Root inherits runtime capabilities directly from Docker.
```yaml
services:
netalertx:
image: netalertx/netalertx
environment:
- PUID=0 # Required for arp-scan/nmap on AUFS
- PGID=0
```
### Scenario C: Forced Non-Root on AUFS
**Context:** Strict security compliance requires non-root, even if it breaks functionality.
**Action:** The warning will persist. The Web UI and Database will function, but network discovery (ARP/Nmap) will be severely limited.
```yaml
services:
netalertx:
image: netalertx/netalertx
environment:
- PUID=1000
- PGID=1000
# Note: cap_add is ineffective here due to AUFS stripping the binary's file caps
```
## Infrastructure Upgrades (Long-term Fix)
To solve the root cause and run securely as non-root, you must migrate off the AUFS driver.
### 1. Switch to Btrfs (Synology Recommended)
If your NAS supports it, creating a new volume formatted as **Btrfs** allows Docker to use the native `btrfs` storage driver.
* **Benefit:** This driver fully supports extended attributes and Copy-on-Write (CoW), creating the most robust environment for Docker.
### 2. Reformat Ext4 with `d_type` Support
If you must use `ext4`, the issue is likely that your volume lacks `d_type` support (common on older volumes created before DSM 6).
* **Fix:** Back up your data and reformat the volume.
* **Result:** Modern formatting usually enables `d_type` by default. This allows Docker to automatically select the modern **`overlay2`** driver instead of failing back to AUFS.
## Technical Implementation
### Detection Mechanism
The logic resides in `_detect_storage_driver()` within `/root-entrypoint.sh`. It parses the root mount point (`/`) to identify the underlying driver.
```bash
# Modern (overlay2) - Pass
overlay / overlay rw,relatime,lowerdir=...
# Legacy (AUFS) - Triggers Warning
none / aufs rw,relatime,si=...
```
### Verification & Troubleshooting
**1. Confirm Storage Driver**
If your host is using ext4 you might be defaulting to aufs:
```bash
docker info | grep "Storage Driver"
# OR inside the container:
docker exec netalertx grep " / " /proc/mounts
```
**2. Verify Capability Loss**
If scans fail, check if the binary permissions were stripped.
* **Modern FS:** Returns `cap_net_admin,cap_net_raw+eip`
* **AUFS:** Returns empty output (stripped)
```bash
docker exec netalertx getcap /usr/sbin/arp-scan
```
**3. Simulating AUFS (Dev/Test)**
Developers can force the AUFS logic path on a modern machine by mocking the mounts file. Note: Docker often restricts direct bind-mounts of host `/proc` paths, so the test suite uses an environment-variable injection instead (see `test_puid_pgid.py`).
```bash
# Create mock mounts content and encode it as base64
echo "none / aufs rw,relatime 0 0" | base64
# Run the container passing the encoded mounts via NETALERTX_PROC_MOUNTS_B64
# (the entrypoint decodes this and uses it instead of reading /proc/mounts directly)
docker run --rm -e NETALERTX_PROC_MOUNTS_B64="bm9uZSAvIGF1ZnMgcncs..." netalertx/netalertx
```
## Additional Resources
* **Docker Storage Drivers:** [Use the OverlayFS storage driver](https://docs.docker.com/storage/storagedriver/overlayfs-driver/)
* **Synology Docker Guide:** [Synology Docker Storage Drivers](https://www.google.com/search?q=https://kb.synology.com/en-global/DSM/tutorial/How_to_use_Docker_on_Synology_NAS)
* **Configuration Guidance:** [DOCKER_COMPOSE.md](https://github.com/jokob-sk/NetAlertX/blob/main/docs/DOCKER_COMPOSE.md)

44
install/production-filesystem/entrypoint.d/10-capabilities-audit.sh
View File

@@ -12,6 +12,31 @@ YELLOW=$(printf '\033[1;33m')
GREY=$(printf '\033[90m')
RESET=$(printf '\033[0m')
_detect_storage_driver() {
mounts_path="/proc/mounts"
if [ -n "${NETALERTX_PROC_MOUNTS_B64:-}" ]; then
mounts_override="/tmp/netalertx_proc_mounts_inline_capcheck"
if printf '%s' "${NETALERTX_PROC_MOUNTS_B64}" | base64 -d > "${mounts_override}" 2>/dev/null; then
chmod 600 "${mounts_override}" 2>/dev/null || true
mounts_path="${mounts_override}"
fi
elif [ -n "${NETALERTX_PROC_MOUNTS_OVERRIDE:-}" ]; then
mounts_path="${NETALERTX_PROC_MOUNTS_OVERRIDE}"
fi
if [ ! -r "${mounts_path}" ]; then
echo "other"
return
fi
if grep -qE '^[^ ]+ / aufs ' "${mounts_path}" 2>/dev/null; then
echo "aufs"
else
echo "other"
fi
}
# Parse Bounding Set from /proc/self/status
cap_bnd_hex=$(awk '/CapBnd/ {print $2}' /proc/self/status 2>/dev/null || echo "0")
# Convert hex to dec (POSIX compliant)
@@ -69,4 +94,23 @@ if [ -n "${missing_admin}" ]; then
fi
fi
storage_driver=$(_detect_storage_driver)
runtime_uid=$(id -u 2>/dev/null || echo 0)
if [ "${storage_driver}" = "aufs" ] && [ "${runtime_uid}" -ne 0 ]; then
printf "%s" "${YELLOW}"
cat <<'EOF'
══════════════════════════════════════════════════════════════════════════════
⚠️ WARNING: Reduced functionality (AUFS + non-root user).
AUFS strips Linux file capabilities, so tools like arp-scan, nmap, and
nbtscan fail when NetAlertX runs as a non-root PUID.
Set PUID=0 on AUFS hosts for full functionality:
https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/aufs-capabilities.md
══════════════════════════════════════════════════════════════════════════════
EOF
printf "%s" "${RESET}"
fi
exit 0

3
install/production-filesystem/entrypoint.sh
View File

@@ -51,7 +51,8 @@ fi
# hands control back to this script.
if [ "${ENTRYPOINT_PRIMED:-0}" != "1" ] && [ "$(id -u)" -eq 0 ] && [ -x "/root-entrypoint.sh" ]; then
>&2 cat <<'EOF'
NetAlertX is running as ROOT (UID 0). Prefer setting PUID/PGID to 20211 for better isolation.
ℹ️ NetAlertX startup: Running privilege check and path priming as ROOT.
(On modern systems, privileges will be dropped to PUID after setup)
EOF
export ENTRYPOINT_PRIMED=1
exec /root-entrypoint.sh "$@"

76
install/production-filesystem/root-entrypoint.sh
View File

@@ -23,23 +23,66 @@
# - EXEC: Direct entrypoint execution as current user.
#
# 2. RUNTIME: ROOT (Container started as user: 0)
# A. TARGET: PUID=0 (User requested root)
# - Permissions priming skipped (already root).
# - EXEC: Direct entrypoint execution as root (with security warning).
#
# B. TARGET: PUID > 0 (User requested privilege drop)
# - PRIMING: Attempt chown on /data & /tmp to PUID:PGID.
# (Failures logged but non-fatal to support NFS/ReadOnly mounts).
# - EXEC: Attempt `su-exec PUID:PGID`.
# - Success: Process runs as PUID.
# - Failure (Missing CAPS): Fallback to running as root to prevent crash.
# - If PUID=0, log a warning and run directly.
# - Otherwise, attempt to prime paths and `su-exec` to PUID:PG
# - PRIMING: Always ensure paths exist and chown to requested PUID:PGID
# (defaults to 20211). Failures are logged but non-fatal to support
# NFS/ReadOnly mounts.
# - EXEC: Attempt `su-exec PUID:PGID` (including 0:0) to keep a single
# execution path. On failure (missing caps/tool), log and run as root.
# - If PUID=0, warn operators that processes remain root-owned.
PROC_MOUNTS_PATH="/proc/mounts"
PROC_MOUNTS_OVERRIDE_REASON=""
if [ -n "${NETALERTX_PROC_MOUNTS_B64:-}" ]; then
PROC_MOUNTS_INLINE_PATH="/tmp/netalertx_proc_mounts_inline"
if printf '%s' "${NETALERTX_PROC_MOUNTS_B64}" | base64 -d > "${PROC_MOUNTS_INLINE_PATH}" 2>/dev/null; then
chmod 600 "${PROC_MOUNTS_INLINE_PATH}" 2>/dev/null || true
PROC_MOUNTS_PATH="${PROC_MOUNTS_INLINE_PATH}"
PROC_MOUNTS_OVERRIDE_REASON="inline"
else
>&2 printf 'Warning: Failed to decode NETALERTX_PROC_MOUNTS_B64; continuing with %s.\n' "${PROC_MOUNTS_PATH}"
fi
elif [ -n "${NETALERTX_PROC_MOUNTS_OVERRIDE:-}" ]; then
PROC_MOUNTS_PATH="${NETALERTX_PROC_MOUNTS_OVERRIDE}"
PROC_MOUNTS_OVERRIDE_REASON="file"
fi
if [ "${PROC_MOUNTS_OVERRIDE_REASON}" = "inline" ]; then
>&2 echo "Note: Using inline /proc/mounts override for storage-driver detection."
elif [ "${PROC_MOUNTS_PATH}" != "/proc/mounts" ]; then
>&2 printf 'Note: Using override for /proc/mounts at %s\n' "${PROC_MOUNTS_PATH}"
fi
# Detect AUFS storage driver; emit warnings so operators can take corrective action
_detect_storage_driver() {
local mounts_path="${PROC_MOUNTS_PATH}"
if [ ! -r "${mounts_path}" ]; then
>&2 printf 'Note: Unable to read %s; assuming non-AUFS storage.\n' "${mounts_path}"
echo "other"
return
fi
# Check mounts file to detect if root filesystem uses aufs
if grep -qE '^[^ ]+ / aufs ' "${mounts_path}" 2>/dev/null; then
echo "aufs"
else
echo "other"
fi
}
STORAGE_DRIVER="$(_detect_storage_driver)"
PUID="${PUID:-${NETALERTX_UID:-20211}}"
PGID="${PGID:-${NETALERTX_GID:-20211}}"
if [ "${STORAGE_DRIVER}" = "aufs" ]; then
>&2 cat <<'EOF'
⚠️ WARNING: Legacy AUFS storage driver detected.
AUFS strips file capabilities (setcap) during image extraction which breaks
layer-2 scanners (arp-scan, etc.) when running as non-root.
Action: set PUID=0 (root) on AUFS hosts or migrate to a supported driver.
Details: https://github.com/jokob-sk/NetAlertX/blob/main/docs/docker-troubleshooting/aufs-capabilities.md
EOF
fi
RED=$(printf '\033[1;31m')
RESET=$(printf '\033[0m')
@@ -130,11 +173,6 @@ if [ "$(id -u)" -ne 0 ]; then
exec /entrypoint.sh "$@"
fi
if [ "${PUID}" -eq 0 ]; then
>&2 echo "WARNING: Running as root (PUID=0). Prefer a non-root PUID."
exec /entrypoint.sh "$@"
fi
_prime_paths() {
runtime_root="${NETALERTX_RUNTIME_BASE:-/tmp}"
paths="/tmp ${NETALERTX_DATA:-/data} ${NETALERTX_CONFIG:-/data/config} ${NETALERTX_DB:-/data/db} ${NETALERTX_LOG:-${runtime_root}/log} ${NETALERTX_PLUGINS_LOG:-${runtime_root}/log/plugins} ${NETALERTX_API:-${runtime_root}/api} ${SYSTEM_SERVICES_RUN:-${runtime_root}/run} ${SYSTEM_SERVICES_RUN_TMP:-${runtime_root}/run/tmp} ${SYSTEM_SERVICES_RUN_LOG:-${runtime_root}/run/logs} ${SYSTEM_SERVICES_ACTIVE_CONFIG:-${runtime_root}/nginx/active-config} ${runtime_root}/nginx"
@@ -154,6 +192,10 @@ _prime_paths() {
}
_prime_paths
if [ "${PUID}" -eq 0 ]; then
>&2 echo "ℹ️ Running as root (PUID=0). Paths will be owned by root."
fi
unset NETALERTX_PRIVDROP_FAILED
if ! su-exec "${PUID}:${PGID}" /entrypoint.sh "$@"; then
rc=$?

2
test/docker_tests/configurations/mount-tests/docker-compose.mount-test.data_noread.yml
View File

@@ -37,7 +37,7 @@ services:
read_only: false
tmpfs:
- "/tmp:mode=1777,uid=20211,gid=20211,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
- "/tmp:mode=1755,uid=20211,gid=20211,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
volumes:
test_netalertx_data:

20
test/docker_tests/test_container_environment.py
View File

@@ -36,7 +36,7 @@ import pytest
IMAGE = os.environ.get("NETALERTX_TEST_IMAGE", "netalertx-test")
GRACE_SECONDS = float(os.environ.get("NETALERTX_TEST_GRACE", "2"))
DEFAULT_CAPS = ["NET_RAW", "NET_ADMIN", "NET_BIND_SERVICE"]
SUBPROCESS_TIMEOUT_SECONDS = float(os.environ.get("NETALERTX_TEST_SUBPROCESS_TIMEOUT", "60"))
SUBPROCESS_TIMEOUT_SECONDS = float(os.environ.get("NETALERTX_TEST_SUBPROCESS_TIMEOUT", "30"))
CONTAINER_TARGETS: dict[str, str] = {
"data": "/data",
@@ -665,7 +665,7 @@ def _run_container(
stdout=subprocess.PIPE, # MUST capture stdout for test assertions and debugging
stderr=subprocess.PIPE, # MUST capture stderr for test assertions and debugging
text=True,
timeout=max(SUBPROCESS_TIMEOUT_SECONDS, sleep_seconds),
timeout=max(SUBPROCESS_TIMEOUT_SECONDS, sleep_seconds), # Coderabbit - please stop trying to increase the length of timeout.
check=False,
)
@@ -1372,7 +1372,21 @@ def test_restrictive_permissions_handling(tmp_path: pathlib.Path) -> None:
assert "permission denied" not in result_root.output.lower()
assert "unable to write" not in result_root.output.lower()
_assert_contains(result_root, "NetAlertX is running as ROOT", result_root.args)
_assert_contains(
result_root,
"NetAlertX startup: Running privilege check and path priming as ROOT.",
result_root.args,
)
_assert_contains_any(
result_root,
[
"Running as root (PUID=0). Paths will be owned by root.",
"WARNING: Running as root (PUID=0). Prefer a non-root PUID.",
"NetAlertX is running as ROOT",
"NetAlertX note: current UID 0 GID 0",
],
result_root.args,
)
check_cmd = [
"docker", "run", "--rm",

4
test/docker_tests/test_docker_compose_scenarios.py
View File

@@ -76,8 +76,8 @@ CONTAINER_PATHS = {
TMPFS_ROOT = "/tmp:uid=20211,gid=20211,mode=1700,rw,noexec,nosuid,nodev,async,noatime,nodiratime"
DEFAULT_HTTP_PORT = int(os.environ.get("NETALERTX_DEFAULT_HTTP_PORT", "20211"))
COMPOSE_PORT_WAIT_TIMEOUT = "30"
COMPOSE_SETTLE_WAIT_SECONDS = "20"
COMPOSE_PORT_WAIT_TIMEOUT = 30
COMPOSE_SETTLE_WAIT_SECONDS = 20
PREFERRED_CUSTOM_PORTS = (22111, 22112)
HOST_ADDR_ENV = os.environ.get("NETALERTX_HOST_ADDRS", "")

123
test/docker_tests/test_puid_pgid.py
View File

@@ -6,6 +6,7 @@ They run in NETALERTX_CHECK_ONLY mode to avoid starting long-running services.
from __future__ import annotations
import base64
import os
import subprocess
import uuid
@@ -28,6 +29,27 @@ def _run_root_entrypoint(
) -> subprocess.CompletedProcess[str]:
name = f"netalertx-test-puidpgid-{uuid.uuid4().hex[:8]}".lower()
env_vars = dict(env or {})
processed_volumes: list[str] = []
proc_mounts_b64: str | None = None
if volumes:
for volume in volumes:
parts = volume.split(":")
if len(parts) >= 2 and os.path.normpath(parts[1]) == "/proc/mounts":
source_path = parts[0]
try:
with open(source_path, "rb") as fh:
proc_mounts_b64 = base64.b64encode(fh.read()).decode("ascii")
except OSError as exc:
raise RuntimeError(f"Failed to read mock /proc/mounts source: {source_path}") from exc
continue
else:
processed_volumes.append(volume)
if proc_mounts_b64 and "NETALERTX_PROC_MOUNTS_B64" not in env_vars:
env_vars["NETALERTX_PROC_MOUNTS_B64"] = proc_mounts_b64
cmd = [
"docker",
"run",
@@ -66,12 +88,12 @@ def _run_root_entrypoint(
if user:
cmd.extend(["--user", user])
if volumes:
for volume in volumes:
if processed_volumes:
for volume in processed_volumes:
cmd.extend(["-v", volume])
if env:
for key, value in env.items():
if env_vars:
for key, value in env_vars.items():
cmd.extend(["-e", f"{key}={value}"])
cmd.extend(["--entrypoint", "/root-entrypoint.sh"])
@@ -212,6 +234,99 @@ def test_synology_like_fresh_volume_is_primed() -> None:
print(result.stderr) # DO NOT REMOVE OR MODIFY - MANDATORY LOGGING FOR DEBUGGING & CI.
@pytest.mark.feature_complete
def test_aufs_explicit_root_no_warning() -> None:
"""Verify that explicitly setting PUID=0 on AUFS doesn't trigger the non-root warning."""
volume = f"nax_test_data_aufs_root_{uuid.uuid4().hex[:8]}".lower()
try:
subprocess.run(["docker", "volume", "create", volume], check=True, capture_output=True, text=True, timeout=15)
# Mock AUFS environment
mock_mounts_content = "none / aufs rw,relatime 0 0\n"
mock_file_path = f"/tmp/mock_mounts_{uuid.uuid4().hex[:8]}"
with open(mock_file_path, "w") as f:
f.write(mock_mounts_content)
try:
# Run with explicit PUID=0 - should not warn about non-root
result = _run_root_entrypoint(
env={"PUID": "0", "PGID": "0", "SKIP_TESTS": "1"},
volumes=[f"{volume}:/data", f"{mock_file_path}:/proc/mounts:ro"],
)
combined = (result.stdout or "") + (result.stderr or "")
assert result.returncode == 0, f"Container should start: {combined}"
assert "Running as root (PUID=0)" in combined, f"Should confirm running as root: {combined}"
# Should NOT have the AUFS reduced functionality warning when running as root
assert "Reduced functionality (AUFS + non-root user)" not in combined, f"Should not warn when explicitly using root: {combined}"
finally:
# Clean up mock file
if os.path.exists(mock_file_path):
os.unlink(mock_file_path)
finally:
subprocess.run(["docker", "volume", "rm", "-f", volume], check=False, capture_output=True, text=True, timeout=15)
@pytest.mark.feature_complete
def test_aufs_non_root_warns() -> None:
"""Verify that AUFS hosts warn when running as a non-root PUID."""
volume = f"nax_test_data_aufs_warn_{uuid.uuid4().hex[:8]}".lower()
try:
subprocess.run(["docker", "volume", "create", volume], check=True, capture_output=True, text=True, timeout=15)
mock_mounts_content = "none / aufs rw,relatime 0 0\n"
mock_file_path = f"/tmp/mock_mounts_{uuid.uuid4().hex[:8]}"
with open(mock_file_path, "w") as f:
f.write(mock_mounts_content)
try:
result = _run_root_entrypoint(
env={"PUID": "20211", "PGID": "20211"},
volumes=[f"{volume}:/data", f"{mock_file_path}:/proc/mounts:ro"],
)
combined = (result.stdout or "") + (result.stderr or "")
assert result.returncode == 0, f"Container should continue with warnings: {combined}"
assert "Reduced functionality (AUFS + non-root user)" in combined, f"AUFS warning missing: {combined}"
assert "aufs-capabilities" in combined, "Warning should link to troubleshooting guide"
finally:
if os.path.exists(mock_file_path):
os.unlink(mock_file_path)
finally:
subprocess.run(["docker", "volume", "rm", "-f", volume], check=False, capture_output=True, text=True, timeout=15)
@pytest.mark.feature_complete
def test_non_aufs_defaults_to_20211() -> None:
"""Verify that non-AUFS storage drivers default to PUID=20211."""
volume = f"nax_test_data_nonaufs_{uuid.uuid4().hex[:8]}".lower()
try:
subprocess.run(["docker", "volume", "create", volume], check=True, capture_output=True, text=True, timeout=15)
# Run with NO PUID set and normal storage driver - should default to 20211
result = _run_root_entrypoint(
env={"SKIP_TESTS": "1"},
volumes=[f"{volume}:/data"],
)
combined = (result.stdout or "") + (result.stderr or "")
assert result.returncode == 0, f"Container should start: {combined}"
# Should NOT mention AUFS
assert "AUFS" not in combined and "aufs" not in combined, f"Should not detect AUFS: {combined}"
# Should not auto-default to root
assert "Auto-defaulting to PUID=0" not in combined, f"Should not auto-default to root: {combined}"
finally:
subprocess.run(["docker", "volume", "rm", "-f", volume], check=False, capture_output=True, text=True, timeout=15)
@pytest.mark.feature_complete
def test_missing_cap_chown_fails_priming() -> None:
"""Verify that priming fails when CAP_CHOWN is missing and ownership change is needed."""