DOCSEARCHbyAlgolia
Submit Docs

WatchYourLAN Documentation

repository·main·Indexed 27 days ago

https://github.com/aceberg/watchyourlan

A lightweight network IP scanner with a web GUI that monitors host online/offline history, maintains host lists, and sends notifications for new hosts. It supports data export to InfluxDB2 and Prometheus for Grafana dashboards. The tool provides a REST API for host management and history retrieval, and can be deployed via Docker, Docker Compose, or as a native Linux binary (.deb, .rpm, .apk, .tar.gz).

Tokens
4.1K
Snippets
23
Records
45
Agent score
92%

What's inside WatchYourLAN

  2. Build the frontend for production

    main

    Build the application for production using the build script. This command bundles Solid in production mode, optimizes the build for performance, minifies the output, and includes hashes in the filenames. The production-ready files are generated in the dist folder.

    npm run build

  4. Quick start with Docker

    main

    To run WatchYourLAN using Docker, use the following command. Note that you must replace $YOURTIMEZONE with your actual timezone, $YOURIFACE with the network interface you want to scan, and $DOCKERDATAPATH with your desired data storage path. The container must use --network="host" to function correctly.

    The Web GUI will be available at http://localhost:8840.

    docker run --name wyl \
	-e "IFACES=$YOURIFACE" \
	-e "TZ=$YOURTIMEZONE" \
	--network="host" \
	-v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \
    aceberg/watchyourlan

  6. Setup Local Network Only (Air-gapped/Independent)

    main

    By default, WatchYourLAN pulls themes, icons, and fonts from the internet. To run an independent setup without global network access, use the aceberg/node-bootstrap image to provide the necessary modules and fonts locally.

    1. Run the bootstrap container:
    docker run --name node-bootstrap -p 8850:8850 aceberg/node-bootstrap
    1. Run WatchYourLAN pointing to the bootstrap container using the -n flag:
    docker run --name wyl \
	-e "IFACES=$YOURIFACE" \
	-e "TZ=$YOURTIMEZONE" \
	--network="host" \
	-v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \
    aceberg/watchyourlan -n "http://$YOUR_IP:8850"
    docker run --name node-bootstrap          \
    -p 8850:8850                          \
    aceberg/node-bootstrap
    docker run --name wyl \
	-e "IFACES=$YOURIFACE" \
	-e "TZ=$YOURTIMEZONE" \
	--network="host" \
	-v $DOCKERDATAPATH/wyl:/data/WatchYourLAN \
    aceberg/watchyourlan -n "http://$YOUR_IP:8850"

  8. Configure WatchYourLAN via Environment Variables or Config File

    main
    Configuration can be managed via a config file (config_v2.yaml), the Web GUI, or environment variables. When using environment variables, use the exact names provided in the tables below. When using the config_v2.yaml file, use lowercase keys.

  9. Perform complex scans using ARP_STRS

    main

    For complex scanning scenarios like VLANs or docker0 interfaces, use ARP_STRS. When this is set, WatchYourLAN initiates scans completely separate from the IFACES list. Each string in the list must be a complete arp-scan command.

    Important:

    • ARP_STRS can only be set via the GUI or the config file.
    • When constructing strings, place the interface (e.g., -I eth0) at the end of the string, as the last element is used to set the Interface for found hosts.
    arp_strs:
    - -gNx 172.17.0.1/24 -I docker0
    - -glNx -I virbr0

  10. Configure network interfaces with IFACES

    main

    The IFACES variable is required for WatchYourLAN to function. It defines a space-separated list of network interfaces to be scanned. You can set this via the GUI, the configuration file, or environment variables. To find your available interfaces, use commands like ip link show or netstat -i.

    IFACES: "enp4s0 wlxf4ec3892dd51"

  11. Set complex scans via environment variables with ARP_STRS_JOINED

    main

    If you are using environment variables (such as in docker-compose), use ARP_STRS_JOINED to define multiple scan strings. This variable accepts a comma-separated list of strings with no spaces before or after the commas.

    ARP_STRS_JOINED: "-gNx 172.17.0.1/24 -I docker0,-gNx 10.0.107.0/24 -Q 107 -I eth0"

  12. Add additional arguments to arp-scan with ARP_ARGS

    main

    The ARP_ARGS variable is optional and allows you to pass additional arguments to the arp-scan command. These arguments will be applied to every interface listed in IFACES. You can find all available arguments in the man arp-scan manual.

    ARP_ARGS: "-r 1"