diff --git a/README.md b/README.md index 7e9521bc..092be6ce 100755 --- a/README.md +++ b/README.md @@ -16,24 +16,10 @@ unknown devices. It also warns if a "always connected" devices disconnects. [![Docker Pulls](https://img.shields.io/docker/pulls/jokobsk/pi.alert?label=Pulls&logo=docker&color=0aa8d2&logoColor=fff)](https://hub.docker.com/r/jokobsk/pi.alert) [![Docker Pushed](https://img.shields.io/badge/dynamic/json?color=0aa8d2&logoColor=fff&label=Pushed&query=last_updated&url=https%3A%2F%2Fhub.docker.com%2Fv2%2Frepositories%2Fjokobsk%2Fpi.alert%2F&logo=docker&link=http://left&link=https://hub.docker.com/repository/docker/jokobsk/pi.alert)](https://hub.docker.com/r/jokobsk/pi.alert) -🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert)
-πŸ“„ [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile)
-πŸ“š [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md) - - -Dark mode (and much more) within this fork courtesy of [leiweibau](https://github.com/leiweibau/Pi.Alert) - -## How it works -The system continuously scans the network for: - - New devices - - New connections (re-connections) - - Disconnections - - "Always Connected" devices down - - Devices IP changes - - Internet IP address changes +🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) | πŸ“„ [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) | πŸ“š [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md) ## πŸ” Scan Methods -Up to three scanning methods are used: +The system continuously scans the network for, **New devices**, **New connections** (re-connections), **Disconnections**, **"Always Connected" devices down**, Devices **IP changes** and **Internet IP address changes**. Scanning methods are: - **Method 1: arp-scan**. The arp-scan system utility is used to search for devices on the network using arp frames. - **Method 2: Pi-hole**. This method is optional and complementary to @@ -46,49 +32,44 @@ Up to three scanning methods are used: that were not discovered by the other methods. -### 🧩 Integrations - - [Apprise](https://hub.docker.com/r/caronc/apprise) - - [Pushsafer](https://www.pushsafer.com/) - - [NTFY](https://ntfy.sh/) +## 🧩 Notification Integrations + - [Apprise](https://hub.docker.com/r/caronc/apprise), [Pushsafer](https://www.pushsafer.com/), [NTFY](https://ntfy.sh/) - Webhooks ([sample JSON](docs/webhook_json_sample.json)) - - (❗Experimental) Home Assistant (via [MQTT](https://www.home-assistant.io/integrations/mqtt/) (processing ~5s per device, deleting not supported, use [MQTT Explorer](https://mqtt-explorer.com/) for now)) + - (❗Experimental) Home Assistant via [MQTT](https://www.home-assistant.io/integrations/mqtt/) + - discovery ~10s per device, deleting not supported, use [MQTT Explorer](https://mqtt-explorer.com/) for now - | ![Report 1][report1] | ![Report 2][report2] | - | -------------------- | -------------------- | -### πŸ” Security -There is a configurable login to prevent unauthorized use. +## πŸ” Security -> * Set `PIALERT_WEB_PROTECTION = True` in `pialert.conf` to enable. The default password is `123456`. -> To change password run `/home/pi/pialert/back/pialert-cli` +- Configurable login to prevent unauthorized use. +- Set `PIALERT_WEB_PROTECTION = True` in `pialert.conf` to enable. +- The default password is `123456`. +- To change password run `/home/pi/pialert/back/pialert-cli` ## πŸ“‘ Features - - Display in a visual way all the information collected by the back - - Sessions, Connected devices, Favorites - - Events, Presence, Concurrent devices - - Down alerts - - IP's + - Display: + - Sessions, Connected devices, Favorites, Events, Presence, Concurrent devices, Down alerts, IP's - Manual Nmap scans, Optional speedtest for Device "Internet" - Simple Network relationship display - Maintenance tasks and Settings like: - Status Infos (active scans, database size, backup counter) - - Theme Selection (blue, red, green, yellow, black, purple) - - Language Selection (english, german, spanish) - - Light/Dark-Mode Switch + - Theme Selection (blue, red, green, yellow, black, purple) and Light/Dark-Mode Switch + - Language Selection (English, German, Spanish) - Pause arp-scan - - DB maintenance, Backup, Restore tools - - CSV Export / Import + - DB maintenance, Backup, Restore tools and CSV Export / Import - Help/FAQ Section | ![Screen 1][screen1] | ![Screen 2][screen2] | | -------------------- | -------------------- | | ![Screen 3][screen3] | ![Screen 4][screen4] | | ![Screen 5][screen5] | ![Screen 6][screen6] | + | ![Report 1][report1] | ![Report 2][report2] | + # πŸ“₯ Installation - ⚠ Please note, this [fork (jokob-sk)](https://github.com/jokob-sk/Pi.Alert) is only tested via the [docker install method](dockerfiles/README.md). Check out [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) if you want to install Pi.Alert on the server directly. + ⚠ This [fork (jokob-sk)](https://github.com/jokob-sk/Pi.Alert) is only tested via the [docker install method](dockerfiles/README.md). Check out [leiweibau's fork](https://github.com/leiweibau/Pi.Alert/) if you want to install Pi.Alert on the server directly. Instructions for [pucherot's original code can be found here](https://github.com/pucherot/Pi.Alert/) @@ -118,7 +99,7 @@ Instructions for [pucherot's original code can be found here](https://github.com This code is a collaborative body of work, with special thanks to: - πŸ† [pucherot/Pi.Alert](https://github.com/pucherot/Pi.Alert) is the original creator od PiAlert - - [leiweibau](https://github.com/leiweibau/Pi.Alert): Things + - [leiweibau](https://github.com/leiweibau/Pi.Alert): Dark mode (and much more) - [Macleykun](https://github.com/Macleykun): Help with Dockerfile clean-up - [Final-Hawk](https://github.com/Final-Hawk): Help with NTFY, styling and other fixes - [TeroRERO](https://github.com/terorero): Spanish translation diff --git a/config/pialert.conf b/config/pialert.conf index 7656e881..287dfb2b 100755 --- a/config/pialert.conf +++ b/config/pialert.conf @@ -7,6 +7,9 @@ # Puche 2021 pi.alert.application@gmail.com GNU GPLv3 #------------------------------------------------------------------------------- +# GENERAL settings +# ---------------------- + PIALERT_PATH = '/home/pi/pialert' DB_PATH = PIALERT_PATH + '/db/pialert.db' LOG_PATH = PIALERT_PATH + '/log' @@ -15,9 +18,11 @@ PRINT_LOG = False TIMEZONE = 'Europe/Berlin' PIALERT_WEB_PROTECTION = False PIALERT_WEB_PASSWORD = '8d969eef6ecad3c29a3a629280e686cf0c3f5d5a86aff3ca12020c923adc6c92' -# Specifies which events trigger notofications. Remove the event type(s) you don't want to get notified on (overrides device-specific settings in the UI). -INCLUDED_SECTIONS = ['internet', 'new_devices', 'down_devices', 'events'] -SCAN_CYCLE_MINUTES = 5 # delay between scans + +INCLUDED_SECTIONS = ['internet', 'new_devices', 'down_devices', 'events'] # Specifies which events trigger notifications. + # Remove the event type(s) you don't want to get notified on + # Overrides device-specific settings in the UI. +SCAN_CYCLE_MINUTES = 5 # delay between scans # EMAIL settings # ---------------------- @@ -38,13 +43,11 @@ REPORT_DASHBOARD_URL = 'http://pi.alert/' # ---------------------- REPORT_WEBHOOK = False WEBHOOK_URL = 'http://n8n.local:5555/webhook-test/aaaaaaaa-aaaa-aaaa-aaaaa-aaaaaaaaaaaa' -# webhook payload data format for the "body > attachements > text" attribute in https://github.com/jokob-sk/Pi.Alert/blob/main/docs/webhook_json_sample.json -# supported values: 'json' or 'html' or 'text' -# e.g.: for discord use 'html' -WEBHOOK_PAYLOAD = 'json' -WEBHOOK_REQUEST_METHOD = 'GET' # POST, GET... -# set event level to 0 for no message, 1 for Internet changes only, 2 for new devices and 1, 3 for down devices and 2 and 4 for events and 3. i.e. everything -EVENT_LEVEL = 4 +WEBHOOK_PAYLOAD = 'json' # webhook payload data format for the "body > attachements > text" attribute + # in https://github.com/jokob-sk/Pi.Alert/blob/main/docs/webhook_json_sample.json + # supported values: 'json', 'html' or 'text' + # e.g.: for discord use 'html' +WEBHOOK_REQUEST_METHOD = 'GET' # POST, GET... # Apprise settings #----------------------- @@ -57,9 +60,8 @@ APPRISE_URL = 'mailto://smtp-relay.sendinblue.com:587?from=user@gmai REPORT_NTFY = False NTFY_HOST = 'https://ntfy.sh' NTFY_TOPIC = 'replace_my_secure_topicname_91h889f28' -# set username and password if authentication is used https://docs.ntfy.sh/config/#users-and-roles -NTFY_USER = '' -NTFY_PASSWORD = '' +NTFY_USER = 'user' # set username... +NTFY_PASSWORD = 'passw0rd' # ...and password if authentication is used https://docs.ntfy.sh/config/#users-and-roles # PUSHSAFER (https://www.pushsafer.com/) settings # ---------------------- @@ -74,7 +76,7 @@ MQTT_PORT = 1883 MQTT_USER = 'mqtt' MQTT_PASSWORD = 'passw0rd' MQTT_QOS = 0 -MQTT_DELAY_SEC = 2 # delay in seconds, increase if not all devices are created in Home Assistant +MQTT_DELAY_SEC = 2 # delay in seconds, increase if not all devices are created in Home Assistant # DynDNS # ---------------------- @@ -110,6 +112,6 @@ DHCP_LEASES = '/etc/pihole/dhcp.leases' SCAN_SUBNETS = '--localnet' -# Maintenance Tasks Cron +# Maintenance Task Settings # ---------------------- DAYS_TO_KEEP_EVENTS = 90 diff --git a/dockerfiles/README.md b/dockerfiles/README.md index eedfa6a4..798ccf24 100755 --- a/dockerfiles/README.md +++ b/dockerfiles/README.md @@ -6,9 +6,8 @@ # 🐳 A docker image for Pi.Alert -🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert)
-πŸ“„ [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile)
-πŸ“š [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md) + +🐳 [Docker hub](https://registry.hub.docker.com/r/jokobsk/pi.alert) | πŸ“„ [Dockerfile](https://github.com/jokob-sk/Pi.Alert/blob/main/Dockerfile) | πŸ“š [Docker instructions](https://github.com/jokob-sk/Pi.Alert/blob/main//dockerfiles/README.md) Big thanks to @Macleykun for help and tips&tricks for Dockerfile(s): @@ -16,23 +15,23 @@ Big thanks to @Macleykun for help and -## β„Ή Usage +## β„Ή Basic Usage -pialert.conf +### pialert.conf - Everytime you rebuilt the container with a new image check if new settings have been added in [pialert.conf](https://github.com/jokob-sk/Pi.Alert/blob/main/config/pialert.conf). -Network +### Network - You will have to run the container on the host network, e.g: `sudo docker run --rm --net=host jokobsk/pi.alert` -Default Port +### Default Port - The app is accessible on the port `:20211`. -> Please note - the cronjob is executed every 3 and 5 minutes so wait that long for all of the scans to run. +> Please note - the initial scan can take up-to 20min (with 50 devices and MQTT). Subsequent ones 3 and 5 minutes so wait that long for all of the scans to run. ## πŸ’Ύ Setup and Backups 1. (**required**) Download `pialert.conf` and `version.conf` from [here](https://github.com/jokob-sk/Pi.Alert/tree/main/config). -2. (**required**) In `pialert.conf` specify your network adapter (will probably be `eth0` or `eth1`) and the network filter (which **significantly** speeds up the scan process), e.g. if your DHCP server assigns IPs in the 192.168.1.0 to 192.168.1.255 range specify it the following way: +2. (**required**) In `pialert.conf` specify your network adapter (will probably be `eth0` or `eth1`) and the network filter (which **significantly** speeds up the scan process), e.g. if your DHCP server assigns IPs in the 192.168.1.0 to 192.168.1.255 range, specify it the following way: * `SCAN_SUBNETS = '192.168.1.0/24 --interface=eth0'` 3. (**required**) Use your configuration by: * Mapping the container folder `/home/pi/pialert/config` to a persistent folder containing `pialert.conf` and `version.conf`, @@ -41,13 +40,13 @@ Default Port 5. Database backup * Download the [original DB from GitHub](https://github.com/jokob-sk/Pi.Alert/blob/main/db/pialert.db). * Map the `pialert.db` file (⚠ not folder) from above to `/home/pi/pialert/db/pialert.db` (see [Examples](https://github.com/jokob-sk/Pi.Alert/tree/main/dockerfiles#-examples) for details). - * If facing issues (AJAX errors, can't write to DB, etc,) make sure permissions are set correctly, alternatively check the logs under `/home/pi/pialert/log`. + * If facing issues (AJAX errors, can't write to DB, etc,) make sure permissions are set correctly, and check the logs under `/home/pi/pialert/log`. * To solve permission issues you can also try to create a DB backup and then run a DB Restore via the **Maintenance > Backup/Restore** section. - * If the database is in read-only mode you can solve this by setting the owner and group by executing the following command on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. + * You can try also setting the owner and group of the `pialert.db` by executing the following on the host system: `docker exec pialert chown -R www-data:www-data /home/pi/pialert/db/pialert.db`. 6. The container supports mapping to local User nad Group IDs. Specify the enviroment variables `HOST_USER_ID` and `HOST_USER_GID` if needed. 7. You can override the port by specifying the `PORT` env variable. -Config examples can be found below. +Docker-compose examples can be found below. ## πŸ“„ Examples