NetAlertX Documentation

File: README.md Copy Chapter

NetAlertX - Network Visibility & Asset Intelligence Framework

📷 Click for more screenshots

Head to https://netalertx.com/ for even more gifs and screenshots 📷.

NetAlertX is a network visibility and asset intelligence platform for homelabs, IT teams, MSPs, and distributed environments. It provides centralized network visibility and continuous asset discovery across remote sites, VLANs, branch offices, and segmented networks from a single interface.

NetAlertX gives you a real-time source of truth for connected devices, helps identify shadow IT and unauthorized hardware, supports compliance initiatives, and automates operational workflows across distributed customer environments.

Use NetAlertX to spot shadow IT, unauthorized hardware, IPAM drift, and other changes that matter to service teams. With multi-site sync, reporting, workflows, and webhooks, it helps MSPs stay ahead of problems without the overhead of a full NMS or SIEM.

Table of Contents Copy Chapter

• Quick Start
• Features
• Documentation
• Security & Privacy
• FAQ
• Troubleshooting Tips
• Everything else

Quick Start Copy Chapter

[!WARNING]
⚠️ Important: The docker-compose has recently changed. Carefully read the Migration guide for detailed instructions.

Start NetAlertX in seconds with Docker:

docker run -d \
  --network=host \
  --restart unless-stopped \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  --cap-add=NET_BIND_SERVICE \
  -v /local_data_dir:/data \
  -v /etc/localtime:/etc/localtime:ro \
  --tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
  -e PORT=20211 \
  -e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
  ghcr.io/netalertx/netalertx:latest

Note: Your /local_data_dir should contain a config and db folder.

To deploy a containerized instance directly from the source repository, execute the following BASH sequence:

git clone https://github.com/netalertx/NetAlertX.git
cd NetAlertX
docker compose up --force-recreate --build
# To customize: edit docker-compose.yaml and run that last command again

Need help configuring it? Check the usage guide or full documentation.

For Home Assistant users: Click here to add NetAlertX

For other install methods, check the installation docs

|| [Docker guide](https://docs.netalertx.com/DOCKER_INSTALLATION) || [Releases](https://github.com/netalertx/NetAlertX/releases) || [Docs](https://docs.netalertx.com/) || [Plugins](https://docs.netalertx.com/PLUGINS) || [Website](https://netalertx.com) Copy Section

Features Copy Chapter

Discovery & Asset Intelligence Copy Section

Continuous monitoring for unauthorized asset discovery, connection state changes, and IP address management (IPAM) drift. Discovery & scan methods include: arp-scan, Pi-hole - DB import, Pi-hole - DHCP leases import, Generic DHCP leases import, UNIFI controller import, SNMP-enabled router import. Check the Plugins docs for a full list of avaliable plugins.

Notification gateways Copy Section

Send notifications to more than 80+ services, including Telegram via Apprise, or use native Pushsafer, Pushover, or NTFY publishers.

Integrations and Plugins Copy Section

Feed your data and device changes into Home Assistant, read API endpoints, or use Webhooks to setup custom automation flows. You can also
build your own scanners with the Plugin system in as little as 15 minutes.

Workflows Copy Section

The workflows module automates IT governance by enforcing device categorization and cleanup policies. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.

MSP & Multi-Site Monitoring Copy Section

NetAlertX enables centralized monitoring across remote sites and isolated environments through Sync Nodes for VLANs and branch offices, providing unified visibility of assets across multiple networks. It supports NOC-style wallboard dashboards, Prometheus metrics export, workflow automation for device governance, and distributed discovery with centralized alerting for scalable network operations.

Documentation Copy Chapter

Explore all the documentation here or navigate to a specific installation option below.

Supported browsers: Chrome, Firefox

• [Installation] Docker
• [Installation] Home Assistant
• [Installation] Bare metal
• [Installation] Unraid App
• [Setup] Usage and Configuration
• [Development] API docs
• [Development] Custom Plugins

Security & Privacy Copy Chapter

NetAlertX scans your local network and can store metadata about connected devices. By default, all data is stored locally. No information is sent to external services unless you explicitly configure notifications or integrations.

Compliance & Hardening:

• Run it behind a reverse proxy with authentication
• Use firewalls to restrict access to the web UI
• Regularly update to the latest version for security patches
• Role-Based Access Control (RBAC) via Reverse Proxy: Integrate with your existing SSO/Identity provider for secure dashboard access.

See Security Best Practices for more details.

Designed for MSPs, NOCs & Distributed Networks Copy Chapter

NetAlertX supports centralized monitoring across VLANs, branch offices, customer environments, isolated networks, and remote sites.

Using Sync Nodes, distributed collectors securely send device inventory and network visibility data back to a central hub, enabling unified monitoring, alerting, and asset tracking across all locations.

This provides MSPs and NOCs with a single operational view of many independent networks, without requiring direct access or centralized scanning infrastructure.

Common deployments include MSP wallboards, NOC dashboards, multi-site inventory monitoring, and remote office discovery.

FAQ Copy Chapter

Q: How do I monitor VLANs or remote subnets?
A: Ensure the container has proper network access (e.g., use --network host on Linux). Also check that your scan method is properly configured in the UI.

Q: What is the recommended deployment for high-availability?
A: We recommend deploying via Docker with persistent volume mounts for database integrity and running behind a reverse proxy for secure access.

Q: Will this send any data to the internet?
A: No. All scans and data remain local, unless you set up cloud-based notifications.

Q: Can I use this without Docker?
A: You can install the application directly on your own hardware by following the bare metal installation guide.

Q: Where is the data stored?
A: In the /data/config and /data/db folders. Back up these folders regularly.

Troubleshooting Tips Copy Chapter

• Some scanners (e.g. ARP) may not detect devices on different subnets. See the Remote networks guide for workarounds.
• Wi-Fi-only networks may require alternate scanners for accurate detection.
• Notification throttling may be needed for large networks to prevent spam.
• On some systems, elevated permissions (like CAP_NET_RAW) may be needed for low-level scanning.

Check the GitHub Issues for the latest bug reports and solutions and consult the official documentation.

Everything else Copy Chapter

📧 Get notified what's new Copy Section

Get notified about a new release, what new functionality you can use and about breaking changes.

🔀 Other Alternative Apps Copy Section

• Fing - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
• NetBox - The gold standard for Network Source of Truth (NSoT) and IPAM.
• Zabbix or Nagios - Strong focus on infrastructure monitoring.
• Domotz - Commercial network monitoring and remote management platform aimed at MSPs, IT teams, and multi-site environments.
• NetAlertX - The streamlined, discovery-focused choice for real-time asset intelligence and noise-free alerting.

💙 Donations Copy Section

Thank you to everyone who appreciates this tool and donates.

Click for more ways to donate

• Bitcoin: 1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM
• Ethereum: 0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7

📧 Email me at [email protected] if you want to get in touch or if I should add other sponsorship platforms.

🏗 Contributors Copy Section

This project would be nothing without the amazing work of the community, with special thanks to:

pucherot/Pi.Alert (the original creator of PiAlert), leiweibau: Dark mode (and much more), Macleykun (Help with Dockerfile clean-up), vladaurosh for Alpine re-base help, Final-Hawk (Help with NTFY, styling and other fixes), TeroRERO (Spanish translations), Data-Monkey, (Split-up of the python.py file and more), cvc90 (Spanish translation and various UI work) to name a few. Check out all the amazing contributors.

🌍 Translations Copy Section

Proudly using Weblate. Help out and suggest languages in the online portal of Weblate.

License Copy Section

GPL 3.0 | Read more here | Source of the animated GIF (Loading Animation) | Source of the selfhosted Fonts

All product names, logos, and brands are property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.

File: docs/docker-troubleshooting/arp-flux-sysctls.md Copy Chapter

ARP Flux Sysctls Not Set

Issue Description Copy Chapter

NetAlertX detected that ARP flux protection sysctls are not set as expected:

• net.ipv4.conf.all.arp_ignore=1
• net.ipv4.conf.all.arp_announce=2

Security Ramifications Copy Chapter

This is not a direct container breakout risk, but detection quality can degrade:

• Incorrect IP/MAC associations
• Device state flapping
• Unreliable topology or presence data

Why You're Seeing This Issue Copy Chapter

The running environment does not provide the expected kernel sysctl values. This is common in Docker setups where sysctls were not explicitly configured.

How to Correct the Issue Copy Chapter

Option A: Via Docker (Standard Bridge Networking or `network_mode: host` with `NET_ADMIN`) Copy Section

If you are using standard bridged networking, or network_mode: host and the container is granted the NET_ADMIN capability (as is the default recommendation), set these sysctls at container runtime.

• In docker-compose.yml (preferred):

  yaml Copy

  services:
    netalertx:
      sysctls:
        net.ipv4.conf.all.arp_ignore: 1
        net.ipv4.conf.all.arp_announce: 2

• For docker run:

  bash Copy

  docker run \
    --sysctl net.ipv4.conf.all.arp_ignore=1 \
    --sysctl net.ipv4.conf.all.arp_announce=2 \
    ghcr.io/netalertx/netalertx:latest

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:

• 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 (Fallback for `network_mode: host`) Copy Section

If you are running the container with network_mode: host and cannot grant the NET_ADMIN capability, or if your container runtime environment explicitly blocks sysctl overrides, applying these settings via the container configuration will fail. Attempting to do so without sufficient privileges typically results 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 Copy

   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 Copy

   net.ipv4.conf.all.arp_ignore=1
   net.ipv4.conf.all.arp_announce=2

Additional Resources Copy Chapter

For broader Docker Compose guidance, see:

• DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/aufs-capabilities.md Copy Chapter

AUFS Legacy Storage Driver Support

Issue Description Copy Chapter

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 Copy Chapter

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:

Warning Log Copy Section

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 Copy Chapter

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 Copy Chapter

Choose the scenario that best matches your environment and security requirements.

Scenario A: Modern Systems (Recommended) Copy Section

Context: Systems using overlay2, btrfs, or zfs.
Action: No action required. The system auto-configures PUID=20211.

services:
  netalertx:
    image: netalertx/netalertx
    # No PUID/PGID needed; defaults to secure non-root

Scenario B: Legacy/Synology AUFS (The Fix) Copy Section

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.

services:
  netalertx:
    image: netalertx/netalertx
    environment:
      - PUID=0  # Required for arp-scan/nmap on AUFS
      - PGID=0

Scenario C: Forced Non-Root on AUFS Copy Section

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.

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) Copy Chapter

To solve the root cause and run securely as non-root, you must migrate off the AUFS driver.

1. Switch to Btrfs (Synology Recommended) Copy Section

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 Copy Section

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 Copy Chapter

Detection Mechanism Copy Section

The logic resides in _detect_storage_driver() within /root-entrypoint.sh. It parses the root mount point (/) to identify the underlying driver.

# Modern (overlay2) - Pass
overlay / overlay rw,relatime,lowerdir=...

# Legacy (AUFS) - Triggers Warning
none / aufs rw,relatime,si=...

Verification & Troubleshooting Copy Section

1. Confirm Storage Driver
If your host is using ext4 you might be defaulting to aufs:

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)

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

# 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 Copy Chapter

• Docker Storage Drivers: Use the OverlayFS storage driver
• Synology Docker Guide: Synology Docker Storage Drivers
• Configuration Guidance: DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/excessive-capabilities.md Copy Chapter

Excessive Capabilities

Issue Description Copy Chapter

Excessive Linux capabilities are detected beyond the necessary NET_ADMIN, NET_BIND_SERVICE, and NET_RAW. This may indicate overly permissive container configuration.

Security Ramifications Copy Chapter

While the detected capabilities might not directly harm operation, running with more privileges than necessary increases the attack surface. If the container is compromised, additional capabilities could allow broader system access or privilege escalation.

Why You're Seeing This Issue Copy Chapter

This occurs when your Docker configuration grants more capabilities than required for network monitoring. The application only needs specific network-related capabilities for proper function.

How to Correct the Issue Copy Chapter

Limit capabilities to only those required:

• In docker-compose.yml, specify only needed caps:
  yaml Copy

  cap_add:
    - NET_RAW
    - NET_ADMIN
    - NET_BIND_SERVICE

• Remove any unnecessary --cap-add or --privileged flags from docker run commands

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/file-permissions.md Copy Chapter

File Permission Issues

Issue Description Copy Chapter

NetAlertX cannot read from or write to critical configuration and database files. This prevents the application from saving data, logs, or configuration changes.

Security Ramifications Copy Chapter

Incorrect file permissions can expose sensitive configuration data or database contents to unauthorized access. Network monitoring tools handle sensitive information about devices on your network, and improper permissions could lead to information disclosure.

Why You're Seeing This Issue Copy Chapter

This occurs when the mounted volumes for configuration and database files don't have proper ownership or permissions set for the netalertx user (UID 20211). The container expects these files to be accessible by the service account, not root or other users.

How to Correct the Issue Copy Chapter

Fix permissions on the host system for the mounted directories:

• Ensure the config and database directories are owned by the netalertx user: chown -R 20211:20211 /path/to/config /path/to/db
• Set appropriate permissions: chmod -R 755 /path/to/config /path/to/db for directories, chmod 644 for files
• Alternatively, restart the container with root privileges temporarily to allow automatic permission fixing, then switch back to the default user

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/incorrect-user.md Copy Chapter

Incorrect Container User

Issue Description Copy Chapter

NetAlertX is running as a UID:GID that does not match the runtime service user configured for this container (default 20211:20211). Hardened ownership on writable paths may block writes if the UID/GID do not align with mounted volumes and tmpfs settings.

Security Ramifications Copy Chapter

The image uses a dedicated service user for writes and a readonly lock owner (UID 20211) for code/venv with 004/005 permissions. Running as an arbitrary UID is supported, but only when writable mounts (/data, /tmp/*) are owned by that UID. Misalignment can cause startup failures or unexpected permission escalation attempts.

Why You're Seeing This Issue Copy Chapter

• A user: override in docker-compose.yml or --user flag on docker run changes the runtime UID/GID without updating mount ownership.
• Tmpfs mounts still use uid=20211,gid=20211 while the container runs as another UID.
• Host bind mounts (e.g., /data) are owned by a different UID.

How to Correct the Issue Copy Chapter

Option A: Use defaults (recommended)

• Remove custom user: overrides and --user flags.
• Let the container run as the built-in service user (UID/GID 20211) and keep tmpfs at uid=20211,gid=20211.

Option B: Run with a custom UID/GID

• Set user: (or NETALERTX_UID/NETALERTX_GID) to your desired UID/GID.
• Align mounts: ensure /data (and any /tmp/* tmpfs) use the same uid=/gid= and that host bind mounts are chowned to that UID/GID.
• Recreate the container so ownership is consistent.

Additional Resources Copy Chapter

• Default compose and tmpfs guidance: DOCKER_COMPOSE.md
• General Docker install and runtime notes: DOCKER_INSTALLATION.md

File: docs/docker-troubleshooting/missing-capabilities.md Copy Chapter

Missing Network Capabilities

Issue Description Copy Chapter

Raw network capabilities (NET_RAW, NET_ADMIN, NET_BIND_SERVICE) are missing. Tools that rely on these capabilities (e.g., nmap -sS, arp-scan, nbtscan) will not function.

Security Ramifications Copy Chapter

Network scanning and monitoring requires low-level network access that these capabilities provide. Without them, the application cannot perform essential functions like ARP scanning, port scanning, or passive network discovery, severely limiting its effectiveness.

Why You're Seeing This Issue Copy Chapter

This occurs when the container doesn't have the necessary Linux capabilities granted. Docker containers run with limited capabilities by default, and network monitoring tools need elevated network privileges.

How to Correct the Issue Copy Chapter

Add the required capabilities to your container:

• In docker-compose.yml:
  yaml Copy

  cap_add:
    - NET_RAW
    - NET_ADMIN
    - NET_BIND_SERVICE

• For docker run: --cap-add=NET_RAW --cap-add=NET_ADMIN --cap-add=NET_BIND_SERVICE

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md

CAP_CHOWN required when cap_drop: [ALL] Copy Chapter

When you start NetAlertX with cap_drop: [ALL], the container loses CAP_CHOWN. The root priming step needs CAP_CHOWN to adjust ownership of /data and /tmp before dropping privileges to PUID:PGID. Without it, startup fails with a fatal failed to chown message and exits.

To fix:

• Add CHOWN back in cap_add when you also set cap_drop: [ALL]:

  yaml Copy

  cap_drop:
    - ALL
  cap_add:
    - CHOWN

• Or pre-chown the mounted host paths to your target PUID:PGID so the priming step does not need the capability.

If you harden capabilities further, expect priming to fail until you restore the minimum set needed for ownership changes.

File: docs/docker-troubleshooting/mount-configuration-issues.md Copy Chapter

Mount Configuration Issues

Issue Description Copy Chapter

NetAlertX has detected configuration issues with your Docker volume mounts. These may include write permission problems, data loss risks, or performance concerns marked with ❌ in the table.

Security Ramifications Copy Chapter

Improper mount configurations can lead to data loss, performance degradation, or security vulnerabilities. For persistent data (database and configuration), using non-persistent storage like tmpfs can result in complete data loss on container restart. For temporary data, using persistent storage may unnecessarily expose sensitive logs or cache data.

Why You're Seeing This Issue Copy Chapter

This occurs when your Docker Compose or run configuration doesn't properly map host directories to container paths, or when the mounted volumes have incorrect permissions. The application requires specific paths to be writable for operation, and some paths should use persistent storage while others should be temporary.

How to Correct the Issue Copy Chapter

Review and correct your volume mounts in docker-compose.yml:

• Ensure ${NETALERTX_DB} and ${NETALERTX_CONFIG} use persistent host directories
• Ensure ${NETALERTX_API}, ${NETALERTX_LOG} have appropriate permissions
• Avoid mounting sensitive paths to non-persistent filesystems like tmpfs for critical data
• Use bind mounts with proper ownership (netalertx user: 20211:20211)

Example volume configuration:

volumes:
  - ./data/db:/data/db
  - ./data/config:/data/config
  - ./data/log:/tmp/log

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/network-mode.md Copy Chapter

Network Mode Configuration

Issue Description Copy Chapter

NetAlertX is not running with --network=host. Bridge networking blocks passive discovery (ARP, NBNS, mDNS) and active scanning accuracy.

Security Ramifications Copy Chapter

Host networking is required for comprehensive network monitoring. Bridge mode isolates the container from raw network access needed for ARP scanning, passive discovery protocols, and accurate device detection. Without host networking, the application cannot fully monitor your network.

Why You're Seeing This Issue Copy Chapter

This occurs when your Docker configuration uses bridge networking instead of host networking. Network monitoring requires direct access to the host's network interfaces to perform passive discovery and active scanning.

How to Correct the Issue Copy Chapter

Enable host networking mode:

• In docker-compose.yml, add: network_mode: host
• For docker run, use: --network=host
• Ensure the container has required capabilities: --cap-add=NET_RAW --cap-add=NET_ADMIN --cap-add=NET_BIND_SERVICE

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md

File: docs/docker-troubleshooting/nginx-configuration-mount.md Copy Chapter

Nginx Configuration Mount Issues

Issue Description Copy Chapter

You've configured a custom port for NetAlertX, but the required nginx configuration mount is missing or not writable. Without this mount, the container cannot apply your port changes and will fall back to the default port 20211.

Security Ramifications Copy Chapter

Running in read-only mode (as recommended) prevents the container from modifying its own nginx configuration. Without a writable mount, custom port configurations cannot be applied, potentially exposing the service on unintended ports or requiring fallback to defaults.

Why You're Seeing This Issue Copy Chapter

This occurs when you set a custom PORT environment variable (other than 20211) but haven't provided a writable mount for nginx configuration. The container needs to write custom nginx config files when running in read-only mode.

How to Correct the Issue Copy Chapter

If you want to use a custom port, create a bind mount for the nginx configuration:

• Create a directory on your host: mkdir -p /path/to/nginx-config
• Add to your docker-compose.yml:
  yaml Copy

  volumes:
    - /path/to/nginx-config:/tmp/nginx/active-config
  environment:
    - PORT=your_custom_port

• Ensure it's owned by the netalertx user: chown -R 20211:20211 /path/to/nginx-config
• Set permissions: chmod -R 700 /path/to/nginx-config

If you don't need a custom port, simply omit the PORT environment variable and the container will use 20211 by default.

Additional Resources Copy Chapter

Docker Compose setup can be complex. We recommend starting with the default docker-compose.yml as a base and modifying it incrementally.

For detailed Docker Compose configuration guidance, see: DOCKER_COMPOSE.md