From 17c3dc4914edff16b91ff5bed0dc6562356834b8 Mon Sep 17 00:00:00 2001 From: Jokob-sk Date: Fri, 25 Aug 2023 07:40:44 +1000 Subject: [PATCH] Docs cleanup --- front/plugins/arp_scan/README.md | 27 +++++++-------------------- front/plugins/pholus_scan/README.md | 24 +++++------------------- front/plugins/pholus_scan/config.json | 4 ++-- 3 files changed, 14 insertions(+), 41 deletions(-) diff --git a/front/plugins/arp_scan/README.md b/front/plugins/arp_scan/README.md index 622c5306..26673cbc 100755 --- a/front/plugins/arp_scan/README.md +++ b/front/plugins/arp_scan/README.md @@ -1,27 +1,14 @@ ## Overview -A plugin allowing for importing Un-Discoverable devices from the settings page. -The main usecase is to add dumb network gear like unmanaged hubs and switches to the network view. -There might be other usecases, please let me know. +Arp-scan is a command-line tool that uses the ARP protocol to discover and fingerprint IP hosts on the local network. An alternative to ARP scan is to enable the `PIHOLE_RUN` PiHole integration settings. The arp-scan (and other Network-scan plugin times using the `SCAN_SUBNETS` setting) time depends on the number of IP addresses to check so set this up carefully with the appropriate network mask and interface. Check the [subnets documentation](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/SUBNETS.md) for help on setting up VLANs, what VLANs are supported, or how to figure out the network mask and your interface. ### Usage -- Go to settings and find Un-Discoverabe Devices in the list of plugins. -- Enable the plugin by changing the RUN parameter from disabled to `once` or `always_after_scan`. -- Add the name of your device to the list. (remove the sample entry first) +- Go to settings and set the `SCAN_SUBNETS` setting as per [subnets documentation](https://github.com/jokob-sk/Pi.Alert/blob/main/docs/SUBNETS.md). +- Enable the plugin by changing the RUN parameter from disabled to your preferred run time (usually: `schedule`). + - Specify the schedule in the `ARPSCAN_RUN_SCHD` setting +- Adjust the timeout if needed in the `ARPSCAN_RUN_TIMEOUT` setting +- Review remaining settings - SAVE -- wait for the next scan to finish +- Wait for the next scan to finish -#### Examples: -Settings: -![settings](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/52883307-19a5-4602-b13a-9825461f6cc4) - -resulting in these devices: -![devices](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/9f7659e7-75a8-4ae9-9f5f-781bdbcbc949) - -Allowing Un-Discoverable devices like hubs, switches or APs to be added to the network view. -![network](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/b5ccc3b3-f5fd-4f5b-b0f0-e4e637c6da33) - -### Known Limitations - - Un-Discoverable Devices always show as offline. That is expected as they can not be discovered by Pi.Alert. - - All IPs are set to 0.0.0.0 therefore the "Random MAC" icon might show up. diff --git a/front/plugins/pholus_scan/README.md b/front/plugins/pholus_scan/README.md index 622c5306..4392c9e3 100755 --- a/front/plugins/pholus_scan/README.md +++ b/front/plugins/pholus_scan/README.md @@ -1,27 +1,13 @@ ## Overview -A plugin allowing for importing Un-Discoverable devices from the settings page. -The main usecase is to add dumb network gear like unmanaged hubs and switches to the network view. -There might be other usecases, please let me know. +A plugin to resolve `(unknown)` device names. It uses the [Pholus](https://github.com/jokob-sk/Pi.Alert/tree/main/front/plugins/pholus_scan/pholus) sniffing tool. ### Usage -- Go to settings and find Un-Discoverabe Devices in the list of plugins. -- Enable the plugin by changing the RUN parameter from disabled to `once` or `always_after_scan`. -- Add the name of your device to the list. (remove the sample entry first) +- Go to settings and find Pholus-Scan (Name discovery) in the list of settings. +- Enable the plugin by changing the `RUN` parameter from disabled to one you prefer (`schedule`, `always_after_scan`, `on_new_device`). +- Specify the `PHOLUS_RUN_TIMEOUT` (Will be divided by the number of subnets specified in the Arp-Scan (Network scan) plugin setting `SCAN_SUBNETS`) - SAVE -- wait for the next scan to finish +- Wait for the next scan to finish -#### Examples: -Settings: -![settings](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/52883307-19a5-4602-b13a-9825461f6cc4) -resulting in these devices: -![devices](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/9f7659e7-75a8-4ae9-9f5f-781bdbcbc949) - -Allowing Un-Discoverable devices like hubs, switches or APs to be added to the network view. -![network](https://github.com/Data-Monkey/Pi.Alert/assets/7224371/b5ccc3b3-f5fd-4f5b-b0f0-e4e637c6da33) - -### Known Limitations - - Un-Discoverable Devices always show as offline. That is expected as they can not be discovered by Pi.Alert. - - All IPs are set to 0.0.0.0 therefore the "Random MAC" icon might show up. diff --git a/front/plugins/pholus_scan/config.json b/front/plugins/pholus_scan/config.json index 7e17da58..b004f69c 100755 --- a/front/plugins/pholus_scan/config.json +++ b/front/plugins/pholus_scan/config.json @@ -71,11 +71,11 @@ "description": [ { "language_code":"en_us", - "string" : "Pholus is a sniffing tool to discover additional information about the devices on the network, including the device name. If enabled this will execute the scan before every network scan cycle until there are no (unknown) or (name not found) devices. Please be aware it can spam the network with unnecessary traffic. Depends on the SCAN_SUBNETS setting. For a scheduled or one-off scan, check the PHOLUS_RUN setting.Specify when your Name-discovery scan will run. Typical setting would be on_new_device or schedule and then you specify a cron-like schedule in the PHOLUS_RUN_SCHDsetting." + "string" : "Pholus is a sniffing tool to discover additional information about the devices on the network, including the device name. If enabled this will execute the scan before every network scan cycle until there are no (unknown) or (name not found) devices. Please be aware it can spam the network with unnecessary traffic. Depends on the SCAN_SUBNETS setting. For a scheduled or one-off scan, check the PHOLUS_RUN setting.Specify when your Name-discovery scan will run. Typical setting would be on_new_device or schedule and then you specify a cron-like schedule in the PHOLUS_RUN_SCHDsetting." }, { "language_code":"es_es", - "string" : "Pholus es una herramienta de rastreo para descubrir información adicional sobre los dispositivos en la red, incluido el nombre del dispositivo. Si está habilitado, ejecutará el escaneo antes de cada ciclo de escaneo de red hasta que no haya dispositivos (unknown) o (name not found). Tenga en cuenta que puede enviar spam a la red con tráfico innecesario. Depende de la configuración de SCAN_SUBNETS. Para un análisis programado o único, verifique la configuración de PHOLUS_RUN." + "string" : "Pholus es una herramienta de rastreo para descubrir información adicional sobre los dispositivos en la red, incluido el nombre del dispositivo. Si está habilitado, ejecutará el escaneo antes de cada ciclo de escaneo de red hasta que no haya dispositivos (unknown) o (name not found). Tenga en cuenta que puede enviar spam a la red con tráfico innecesario. Depende de la configuración de SCAN_SUBNETS. Para un análisis programado o único, verifique la configuración de PHOLUS_RUN." } ] },