Skip to content

PIALERT_CONF.md

Latest commit

 

History

History
412 lines (294 loc) · 46.5 KB

PIALERT_CONF.md

File metadata and controls

412 lines (294 loc) · 46.5 KB
Raw

pialert.conf

In this configuration file many functions of Pi.Alert can be set according to the personal wishes. Since the possibilities are various, I would like to give a short explanation to the individual points.

✳️ General Settings

Option Description
PIALERT_PATH This variable is set during installation and should not be changed.
DB_PATH This variable is set during installation and should not be changed.
LOG_PATH This variable is set during installation and should not be changed.
PRINT_LOG If this entry is set to True, additional timestamps for the individual sub-functions are added to the scan log. By default this entry is set to False
VENDORS_DB This variable is set during installation and should not be changed.
PIALERT_APIKEY With the API key it is possible to make queries to the database without using the web page. The API key is a random string that can be set via the settings or via pialert-cli
PIALERT_WEB_PROTECTION Enables or disables the password protection of the Pi.Alert web interface.
PIALERT_WEB_PASSWORD This field contains the hashed password for the web interface. The password cannot be entered here in plain text, but must be set with pialert-cli
NETWORK_DNS_SERVER IP address of the DNS server in the network. This entry is required to attempt to resolve a hostname in the network.
AUTO_UPDATE_CHECK Enables or disables automatic search for Pi.Alert updates.
AUTO_DB_BACKUP Enables or disables automatic creation of database and configuration backups.
AUTO_DB_BACKUP_KEEP This specifies how many automatic backups should be retained, including the current backup. This includes both configuration backups and database backup. This value is not relevant during manual cleanup, where the last 3 backups are retained.
REPORT_NEW_CONTINUOUS Enables or disables the recurring notification for devices marked as "New".
NEW_DEVICE_PRESET_EVENTS Enables or disables the notification for all events on new devices.
NEW_DEVICE_PRESET_DOWN Enables or disables the notification for "Down" events on new devices.
SYSTEM_TIMEZONE If a time zone has already been set in php.ini, this will of course be used. If no time zone is set, i.e. PHP uses "UTC", then the time zone stored in pialert.conf is applied. PHP Timezones
OFFLINE_MODE After the installation and the initial test of all script components, the offline mode can be configured to prevent any communication with the Internet

✳️ Other Modules

Option Description
SCAN_WEBSERVICES Here the function for monitoring web services can be switched on (True) or off (False)
ICMPSCAN_ACTIVE ICMP Monitoring on/off
SATELLITES_ACTIVE Enable the Satellite management and import function. One or more companion scripts can perform remote scans and send them to the central Pi.Alert instance.

✳️ Special Protocol Scanning

Option Description
SCAN_ROGUE_DHCP Activates the search for foreign, also called "rogue", DHCP servers. This function is used to detect whether there is a foreign DHCP server in the network that could take control of IP management.
DHCP_SERVER_ADDRESS The IP of the known DHCP server is stored here. A list of DHCP servers is also supported

✳️ Custom Cronjobs

Option Description
AUTO_UPDATE_CHECK_CRON Interval, in crontab syntax, at which to search for new updates from Pi.Alert. The shortest interval is 3 minutes. All larger intervals must be an integer multiples of 3 minutes (15, 30, 36, etc).
AUTO_DB_BACKUP_CRON Interval, in crontab syntax, at which the automatic backups should be created. The shortest interval is 3 minutes. All larger intervals must be aninteger multiples of 3 minutes (15, 30, 36, etc).
REPORT_NEW_CONTINUOUS_CRON Interval, in Crontab syntax, at which notifications should be sent repeatedly. The shortest interval is 3 minutes. All larger intervals must be an integer multiple of 3 minutes (15, 30, 36, etc.).
SPEEDTEST_TASK_CRON Full hour, or comma-separated hours, at which the speed test is to be started. The shortest interval is 3 minutes. All larger intervals must be integer multiples of 3 minutes (15, 30, 36, etc).

✳️ Mail-Account Settings

Option Description
SMTP_SERVER Address of the e-mail server (e.g. smtp.gmail.com)
SMTP_PORT The port of the SMTP server. The port may vary depending on the server configuration.
SMTP_USER User name used to authenticate with the SMTP server.
SMTP_PASS Password used to authenticate with the SMTP server.
SMTP_SSL Use SSL immediately when connecting to the SMTP server (SMTPS / SSL-on-connect).
SMTP_SKIP_TLS Skip STARTTLS after connecting with regular SMTP. This setting is ignored when SMTP_SSL is True.
SMTP_SKIP_LOGIN There are SMTP servers which do not require a login. In such a case, this value can be set to True.

SMTP transport modes:

  • SMTP_SSL = True: Connect with SMTPS / SSL-on-connect. STARTTLS is not used.
  • SMTP_SSL = False and SMTP_SKIP_TLS = False: Connect with SMTP and upgrade the connection with STARTTLS.
  • SMTP_SSL = False and SMTP_SKIP_TLS = True: Connect with SMTP without TLS.

✳️ WebGUI Reporting

Option Description
REPORT_WEBGUI Enables/disables the notifications about changes in the network in the web interface.
REPORT_WEBGUI_WEBMON Enables/disables the notifications about changes in the monitored web services in the web interface.
REPORT_TO_ARCHIVE Number of hours after which a report is moved to the archive. The value 0 disables the feature

✳️ MQTT Reporting

Option Description
REPORT_TO_MQTT General activation/deactivation of the MQTT function.
REPORT_MQTT_BROKER The IP or host name of the MQTT server/broker. The URL scheme "mqtt://" is not supported as input and must be removed.
REPORT_MQTT_PORT The port under which the MQTT server can be accessed. The standard MQTT port is 1883. If SSL/TLS is used, 8883 is usually used.
REPORT_MQTT_USERNAME Username for logging in to the MQTT server. If no authentication is used, leave this field blank.
REPORT_MQTT_PASSWORD Password for logging in to the MQTT server. If no authentication is used, leave this field blank.
REPORT_MQTT_TLS Enable or disable SSL/TLS.
PUBLISH_MQTT_STATUS Activation or deactivation of general information about the Pi.Alert installation. The following sensors are created: “Pi.Alert Status”, “Pi.Alert local”, “Pi.Alert <Satellite Name>”
PUBLISH_MQTT_SUBNET_STATUS Publishes per-local-IPv4-subnet counters when REPORT_TO_MQTT is also True. This switch is independent of PUBLISH_MQTT_STATUS and defaults to False.

When subnet status is enabled, Pi.Alert discovers directly attached IPv4 networks from active local interfaces without root privileges. IPv6 networks are not included. Each valid managed Device and ICMP target is assigned to exactly one network; when networks overlap, the longest (most specific) prefix wins.

For example, 192.168.0.0/24 uses the identifier 192168000000 and publishes retained values below pi_alert/subnet_192168000000/. The nine value names are all, online, new, down, offline, archive, icmp_all, icmp_online, and icmp_offline. The first six have the same meaning as the general Device counters. The ICMP counters include only non-archived targets. Home Assistant discovery sensors are published for every value. If two local CIDRs have the same network address, their identifiers receive a _p<prefix> suffix to avoid collisions.

All Pi.Alert MQTT values and discovery configurations are retained. Pi.Alert records their topic names in db/mqtt_published_topics.json. Turning off a subordinate switch removes only that group's retained topics. Turning off REPORT_TO_MQTT removes every recorded Pi.Alert state and discovery topic on the next main run; failed removals remain recorded and are retried. Disabling MQTT for an individual Device or ICMP target likewise removes its four state topics (online, ip, location, and scansource) and four discovery topics. A fresh installation with MQTT disabled does not contact the default broker merely to remove speculative legacy topics.

✳️ Mail Reporting

Option Description
REPORT_MAIL Enables/disables the notifications about changes in the network via e-mail.
REPORT_MAIL_WEBMON Enables/disables the notification of changes in the monitored web services by e-mail.
REPORT_FROM Name or identifier of the sender.
REPORT_TO E-mail address to which the notification should be sent.
REPORT_DEVICE_URL URL of the Pi.Alert installation to create a clickable link in the e-mail to the detected device.
REPORT_DASHBOARD_URL URL of the Pi.Alert installation, to be able to create a clickable link in the e-mail.

✳️ Pushsafer

Option Description
REPORT_PUSHSAFER Enables/disables notifications about changes in the network via Pushsafer.
REPORT_PUSHSAFER_WEBMON Enables/disables notifications about changes in the monitored web services via Pushsafer.
PUSHSAFER_TOKEN This is the private key that can be viewed on the pushsafer page.
PUSHSAFER_DEVICE The device ID to which the message will be sent. ‘a’ means the message will be sent to all configuring devices and will consume a corresponding number of API calls.
PUSHSAFER_PRIO Integer priority accepted by the Pushsafer API, from -2 through 2.
PUSHSAFER_SOUND Pushsafer sound ID from 0 (silent) through 62.

✳️ Pushover

Option Description
REPORT_PUSHOVER Enables/disables notifications about changes in the network via Pushover.
REPORT_PUSHOVER_WEBMON Enables/disables the notifications about changes in the monitored web services via Pushover.
PUSHOVER_TOKEN Also called "APP TOKEN" or "API TOKEN". This token can be queried on the pushover page.
PUSHOVER_USER Also called "USER KEY". This key is displayed right after login on the start page.
PUSHOVER_PRIO Integer Pushover priority from -2 through 2. Priority 2 uses the emergency retry and expiration settings below.
PUSHOVER_RETRY Retry interval in seconds for emergency-priority messages (30..10800, default 60).
PUSHOVER_EXPIRE Maximum retry period in seconds for emergency messages (30..10800, default 3600); it must not be smaller than PUSHOVER_RETRY.
PUSHOVER_SOUND Notification sound.

✳️ NTFY

Option Description
REPORT_NTFY Enables/Disables notifications about changes in the network via NTFY
REPORT_NTFY_WEBMON Enables/Disables notifications about changes in monitored web services via NTFY
NTFY_HOST The hostname or IP address of the NTFY server.
NTFY_TOPIC The subject of notifications sent via NTFY.
NTFY_USER The username used for authentication with the NTFY server.
NTFY_PASSWORD The password used for authentication with the NTFY server.
NTFY_PRIORITY Priority of notifications sent via NTFY
NTFY_CLICKABLE Enables or disables the click action for the notification.

❗ If you want to use a token instead of username and password, leave the username blank and use the token as the password.

✳️ Telegram

Option Description
REPORT_TELEGRAM Enables/disables notifications about changes in the network via Telegram.
REPORT_TELEGRAM_WEBMON Enables/disables notifications about changes in monitored web services via Telegram.
TELEGRAM_BOT_TOKEN Secret bot token issued by BotFather. It is sent directly to the Telegram Bot API.
TELEGRAM_CHAT_IDS List of destination chat IDs. Negative group IDs and @channelusername values are supported.
TELEGRAM_BOT_TOKEN_URL Deprecated compatibility input containing the former Shoutrrr URL. Used only when both new settings are empty; Shoutrrr is not started.

✳️ Discord

Option Description
REPORT_DISCORD Enables/disables notifications about network changes via Discord.
REPORT_DISCORD_WEBMON Enables/disables notifications about monitored web service changes via Discord.
DISCORD_BOT_TOKEN_URL The Discord webhook URL used to send the notification.

✳️ DynDNS and IP

Option Description
QUERY_MYIP_SERVER Server URL that determines and returns the current public IP.
QUERY_MYIP_SERVER_FALLBACK Fallback server URL used when the primary public IP lookup fails.
DDNS_ACTIVE Enables/Disables the configured DDNS service in Pi.Alert. DDNS, also known as DynDNS, allows a domain name to be updated with a regularly changing IP address. This service is provided by various providers.
DDNS_DOMAIN Domain name or host name that should be updated by the configured DDNS provider.
DDNS_USER User name used to authenticate with the DDNS provider.
DDNS_PASSWORD Password used to authenticate with the DDNS provider.
DDNS_UPDATE_URL Provider-specific update URL used to send the current public IP to the DDNS service.

✳️ Automatic Speedtest

Option Description
SPEEDTEST_TASK_ACTIVE Activate/deactivate the automatic speed test. This requires the installation of the Ookla speed test in the "Tools" tab of the "Internet" device. Follow the instructions during installation.

✳️ Arp-scan Options & Samples

Option Description
MAC_IGNORE_LIST ['MAC-Address 1', 'MAC-Address 2']
This MAC address(es) (save with small letters) will be filtered out from the scan results. It is also possible to specify only the beginning of a MAC address. All addresses with the same prefix will also be filtered out
IP_IGNORE_LIST ['IP-Address 1', 'IP-Address 2']
This IP address(es) will be filtered out from the scan results. It is also possible to specify only the beginning of a IP address. All addresses with the same prefix will also be filtered out. A syntax such as “172.17.0.0/24” does not lead to success. In this case, use an entry such as “172.17.”
HOSTNAME_IGNORE_LIST ['Hostname', 'Host*', '*stna*', '*stname']
If no “*” is specified, the exact host name is searched for. “*”, however, serves as a wildcard. No distinction is made between upper and lower case letters.
SCAN_SUBNETS --localnet scans the automatically detected local network. --localnet --interface=<name> selects a specific interface. To scan several networks, use a list. Each entry starts with an IPv4 network in CIDR notation and then uses --interface=<name>, --vlan=<id>, or both. For an existing Linux VLAN interface use, for example, '192.168.123.0/24 --interface=eth0.123'; the kernel handles the VLAN tag. To make arp-scan add an 802.1Q tag on a parent interface, use '192.168.123.0/24 --interface=eth0 --vlan=123'. Do not combine a VLAN subinterface such as eth0.123 with --vlan=123, because that can produce double tagging. The shorter form '192.168.123.0/24 --vlan=123' is supported, but then arp-scan automatically selects an interface and may choose the wrong one on multi-interface systems. VLAN IDs from 0 through 4095 are accepted, matching arp-scan. Options are passed before the target network in the generated command. Interface names are not restricted to eth*; classic, predictable, WLAN, bridge, bond, VLAN, virtual, alias, and custom valid Linux names are supported. Interface existence and VLAN availability are checked by the scan at runtime, not while parsing the configuration. A saved configuration must contain exactly one active assignment. If the WebEditor submission contains several, it keeps the last semantically valid assignment from the newly edited text and removes the others; the backup is never used to choose this value. Direct backend loading remains strict and rejects duplicate keys.

Subnet lists can span multiple lines. Comments and a trailing comma are supported; the GUI reads the import switches independently of the list layout:

SCAN_SUBNETS = [
    '192.168.10.0/24 --interface=eth0',
    '192.168.20.0/24 --interface=eth0 --vlan=20',
]

✳️ ICMP Monitoring Options

Option Description
ICMP_ONLINE_TEST Number of attempts to determine if a device is online (Default 1).
ICMP_GET_AVG_RTT Number of "ping's" to calculate the average response time (Default 2).

✳️ Pi-hole Configuration

Option Description
PIHOLE_ACTIVE This variable is set during installation.
PIHOLE_VERSION The version information is necessary because access to the Pi-hole data has fundamentally changed from version 5 to 6. Default is 6 after the official realease of Pihole 6
PIHOLE_DB This variable is set during installation and should not be changed.
PIHOLE6_URL Pi-hole 6 HTTP(S) base URL, for example https://192.168.10.4 or http://pi.hole:8080. Do not append /admin or /api; Pi.Alert adds the API endpoint itself. A trailing slash is optional.
PIHOLE6_PASSWORD Enter the password for the Pi-hole web interface here.
PIHOLE6_API_MAXCLIENTS Specifies the maximum number of clients that are returned as a response from the API
DHCP_ACTIVE This variable is valid for the DHCP server of Pihole 5.x as well as for 6.x
DHCP_LEASES This path is only relevant for version 5.x of Pihole and should not be changed.
DHCP_INCL_SELF_TO_LEASES Adds the Mac addresses of Pi-hole itself to the DHCP leases to import Pi-hole itself into the database if it is not in the local network of Pi.Alert

For example, use PIHOLE6_URL = 'https://192.168.10.4' even when the browser opens https://192.168.10.4/admin/. Pi.Alert authenticates at https://192.168.10.4/api/auth. If a reverse proxy exposes Pi-hole under a path, keep that base path, for example https://example.net/pihole.

An accidental trailing /admin or /admin/ is removed in memory with a scan-log notice; the configuration file is not rewritten. Correct the saved URL to avoid the notice on subsequent scans. HTTP errors, timeouts and invalid JSON responses are logged and the affected Pi-hole request is skipped so other scan sources can continue. The configuration validator does not test API connectivity or credentials.

✳️ Fritzbox Configuration

Option Description
FRITZBOX_ACTIVE If a Fritzbox is used in the network, it can be used as a data source. This can be activated or deactivated at this point.
FRITZBOX_IP IP address or host name of the Fritzbox.
FRITZBOX_USER User name for Fritzbox authentication. Password-only logins are not supported.
FRITZBOX_PASS Password for the configured Fritzbox user.

✳️ Mikrotik Configuration

Option Description
MIKROTIK_ACTIVE If a Mikrotik router is used in the network, it can be used as a data source. This can be enabled or disabled at this point.
MIKROTIK_IP IP address or host name of the Mikrotik router.
MIKROTIK_USER User name used to authenticate with the Mikrotik router.
MIKROTIK_PASS Password used to authenticate with the Mikrotik router.

✳️ UniFi Configuration

Option Description
UNIFI_ACTIVE If a UniFi system is used in the network, it can be used as a data source. This can be enabled or disabled at this point.
UNIFI_IP IP address or host name of the UniFi controller or UniFi OS device.
UNIFI_API Possible UNIFI APIs are v4, v5, unifiOS, UDMP-unifiOS, default
UNIFI_USER User name used to authenticate with the UniFi controller.
UNIFI_PASS Password used to authenticate with the UniFi controller.

✳️ OpenWRT Configuration

Option Description
OPENWRT_ACTIVE Enables the OpenWrt data source. The luci-mod-rpc package must be installed on the router.
OPENWRT_IP IP address or host name without a URL scheme or embedded port. IPv4, IPv6 and host names are supported.
OPENWRT_USER User name used to authenticate with the OpenWrt router.
OPENWRT_PASS Password used to authenticate with the OpenWrt router.
OPENWRT_SSL True first uses HTTPS and accepts self-signed certificates without verification. TLS, connection and timeout failures trigger one HTTP retry on port 80. False uses HTTP directly. New installations default to True; migrated installations retain the previous behavior with False.
OPENWRT_PORT Port for the explicitly selected primary transport (1..65535). New installations default to 443; migrated installations default to 80. The automatic HTTP fallback always uses port 80.

✳️ Asus Configuration

Option Description
ASUSWRT_ACTIVE If a Asus router is used in the network, it can be used as a data source. This can be activated or deactivated at this point. The Python package “asusrouter” is used for communication with the router, which supports a large number of devices. You can check whether your router is supported at “https://pypi.org/project/asusrouter/”.
ASUSWRT_IP IP address or host name of the AsusWRT router.
ASUSWRT_USER User name used to authenticate with the AsusWRT router.
ASUSWRT_PASS Password used to authenticate with the AsusWRT router.
ASUSWRT_SSL Set to True for https or False for http when connecting to the router.

✳️ pfsense Configuration

Option Description
PFSENSE_ACTIVE Enables the import of pfSense. To do this, the REST API must be installed in pfSense. You can find more details here: pfSense REST API. The API is used to import the DHCP leases and the ARP table from pfSense.
PFSENSE_IP IP address or domain name of the pfSense firewall.
PFSENSE_PORT The port through which the web interface can be accessed. This is usually 443 for https (PFSENSE_SSL = True) and 80 for http (PFSENSE_SSL = False).
PFSENSE_APIKEY The API key that was created after installing the API in pfSense under ‘System’ -> ‘REST API’ -> 'Keys'
PFSENSE_SSL Set to True for https or False for http.
PFSENSE_EXCLUDE_INT Interfaces that should be ignored during import

✳️ OPNsense Configuration

Option Description
OPNSENSE_ACTIVE Enables the import of OPNsense data. Pi.Alert uses the OPNsense API to read DHCP lease and ARP information.
OPNSENSE_IP IP address or domain name of the OPNsense firewall.
OPNSENSE_PORT The port used by the OPNsense web interface and API. This is usually 443 for https and 80 for http.
OPNSENSE_APIKEY API key created for the OPNsense API user.
OPNSENSE_APISECRET API secret that belongs to the configured API key.
OPNSENSE_SSL Set to True for https or False for http.
OPNSENSE_EXCLUDE_INT Interfaces that should be ignored during import.

✳️ AdGuard Configuration

Option Description
ADGUARD_ACTIVE Enables or disables the AdGuard import.
ADGUARD_IP IP address or host name of the AdGuard Home instance.
ADGUARD_PORT Port used by the AdGuard web interface and API.
ADGUARD_USER User name used to authenticate with the AdGuard web interface.
ADGUARD_PASSWORD Password for the AdGuard web interface. If you enter a password with \ in the GUI, pialert.conf may show \\. This is expected and preserves the correct value.
ADGUARD_SSL Set to True for https or False for http.
ADGUARD_QUERY_MINUTES Query time window, in minutes, that is used to mark AdGuard lease entries as active.
ADGUARD_ACTIVITY_MINUTES Retention time, in minutes, for entries in the AdGuard activity table before they are removed as inactive.
ADGUARD_QUERY_LIMIT Maximum number of query log entries requested from AdGuard per run.

✳️ Satellite Configuration

Option Description
SATELLITE_PROXY_MODE Activates/deactivates the support of an external API to which the satellites send their data. If this function is deactivated, Pi.Alert only uses scan events that were sent directly to this instance.
SATELLITE_PROXY_URL URL of the Pi.Alert Satellite Proxy API that receives scan data from satellite instances.

✳️ Maintenance Tasks

Option Description
DAYS_TO_KEEP_ONLINEHISTORY Number of days for which the online history (activity graph) is to be stored in the database. One day generates 288 such records.
DAYS_TO_KEEP_EVENTS Number of days for which the events of the individual devices are to be stored.

Back

Web service target handling

The web service monitor supports internal and external HTTP and HTTPS URLs without a separate network allowlist. Private IPv4 networks, loopback, link-local addresses, private IPv6 networks, .local names, single-label hostnames and public Internet services can therefore be monitored directly.

Every URL is structurally validated before use. Credentials in URLs, fragments, control characters, ambiguous numeric IPv4 forms, invalid ports and invalid percent encoding are rejected. Commas in a path or query remain valid.

DNS is resolved before connecting and connections are pinned to the validated addresses. For dual-stack host names, Pi.Alert tries IPv4 addresses first and uses IPv6 as a fallback; IPv6-only services and explicit IPv6 URL literals remain supported. Resolver order is retained within each address family. If one address cannot establish a connection, the next validated address is tried within the shared total time limit. The same validation and DNS resolution are repeated for every redirect. Up to ten redirects are followed within a fixed total time limit, and repeated URL/cookie states are reported as redirect loops instead of being confused with a longer valid redirect chain. Known cloud metadata addresses remain blocked. Response bodies are not downloaded by the monitor.

Redirect cookies are held only in memory for the duration of one service check. Standard domain, path, and Secure-cookie rules apply, and cookie count, value size, and the resulting request header are bounded. Cookie values are neither logged nor stored. This allows local services that set a short-lived state cookie before redirecting to their final page to be monitored without creating a persistent browser-like session.

When a new service is saved, Pi.Alert immediately performs one synchronous check with the same hardened transport used by the periodic monitor. The initial HTTP status, latency and resolved target address are stored with the service. An unreachable target is still stored with status 0 and the offline latency marker so it can recover during a later periodic scan.

For HTTPS services, the certificate subject, issuer, validity start and validity end are captured from the final pinned TLS connection and stored during the initial insert. Self-signed and otherwise privately issued certificates are supported; the monitor records their metadata but does not require a trusted CA chain. The initial SSL change flag is 0, because no previous certificate exists for comparison. HTTP services use empty SSL fields.

The monitor stores the configured URL, final HTTP status, first status in a redirect chain, redirect count or failure note, total response latency, selected target IP, scan time, and HTTPS certificate metadata. Status, latency, IP, and certificate changes continue to feed the service history, journal, and notification workflow. Redirect diagnostics contain only bounded per-hop status, host/path, and target-IP information; URL query values and cookie values are redacted. Response bodies, form data, and persistent session data are not collected.

Failures are classified as invalid URL, DNS resolution failure, connection failure, TLS failure, network-policy block, redirect loop, or redirect-limit exhaustion. Only a network-policy violation is described as blocked. A valid but currently unreachable service can still be saved with status 0 and will be checked again by the periodic monitor.