NetAlertX/docs/DEBUG_TIPS.md

Debugging and troubleshooting

Please follow tips 1 - 4 to get a more detailed error.

1. More Logging 📃

When debugging an issue always set the highest log level:

LOG_LEVEL='trace'

2. Surfacing errors when container restarts 🔁

Start the container via the terminal with a command similar to this one:

docker run --rm --network=host \
  -v local/path/netalertx/config:/app/config \
  -v local/path/netalertx/db:/app/db \
  -e TZ=Europe/Berlin \
  -e PORT=20211 \
  jokobsk/netalertx:latest

⚠ Please note, don't use the -d parameter so you see the error when the container crashes. Use this error in your issue description.

3. Check the _dev image and open issues ❓

If possible, check if your issue got fixed in the _dev image before opening a new issue. The container is:

jokobsk/netalertx-dev:latest

⚠ Please backup your DB and config beforehand!

Please also search open issues.

4. Disable restart behavior 🛑

To prevent a Docker container from automatically restarting in a Docker Compose file, specify the restart policy as no:

version: '3'

services:
  your-service:
    image: your-image:tag
    restart: no
    # Other service configurations...

5. Sharing application state

Sometimes specific log sections are needed to debug issues. The Devices and CurrentScan table data is sometimes needed to figure out what's wrong.

1. Please set LOG_LEVEL to trace (Disable it once you have the info as this produces big log files).
2. Wait for the issue to occur.
3. Search for ================ DEVICES table content ================ in your logs.
4. Search for ================ CurrentScan table content ================ in your logs.
5. Open a new issue and post (redacted) output into the issue description (or send to the netalertx@gmail.com email if sensitive data present).
6. Please set LOG_LEVEL to debug or lower.

📃Common issues

Permissions

• If facing issues (AJAX errors, can't write to DB, empty screen, etc,) make sure permissions are set correctly, and check the logs under /app/log.
• To solve permission issues you can try setting the owner and group of the app.db by executing the following on the host system: docker exec netalertx chown -R www-data:www-data /app/db/app.db.
• If still facing issues, try to map the app.db file (⚠ not folder) to :/app/db/app.db (see docker-compose Examples for details)

Container restarts / crashes

• Check the logs for details. Often a required setting for a notification method is missing.

unable to resolve host

• Check that your SCAN_SUBNETS variable is using the correct mask and --interface. See teh subnets docs for details.

Invalid JSON

Check the Invalid JSON errors debug help docs on how to proceed.

sudo execution failing (e.g.: on arpscan) on a Raspberry Pi 4

sudo: unexpected child termination condition: 0

Resolution based on this issue

wget ftp.us.debian.org/debian/pool/main/libs/libseccomp/libseccomp2_2.5.3-2_armhf.deb
sudo dpkg -i libseccomp2_2.5.3-2_armhf.deb

The link above will probably break in time too. Go to https://packages.debian.org/sid/armhf/libseccomp2/download to find the new version number and put that in the url.

Only Router and own device show up

Make sure that the subnet and interface in SCAN_SUBNETS are correct. If your device/NAS has multiple ethernet ports, you probably need to change eth0 to something else.