diff --git a/docs/ftldns/configfile.md b/docs/ftldns/configfile.md index 205faf6..3b59853 100755 --- a/docs/ftldns/configfile.md +++ b/docs/ftldns/configfile.md @@ -93,7 +93,7 @@ host name for another IP address (e.g., a DHCP server managed IPv4 address). In this case, we use the host name associated to the other address as this is the same device. -#### `REFRESH_HOSTNAMES=IPV4|ALL|NONE` (PR [#953](https://github.com/pi-hole/FTL/pull/953)) {#refresh_hostnames data-toc-label='Refresh hostnames'} +#### `REFRESH_HOSTNAMES=IPV4|ALL|UNKNOWN|NONE` (PR [#953](https://github.com/pi-hole/FTL/pull/953)) {#refresh_hostnames data-toc-label='Refresh hostnames'} With this option, you can change how (and if) hourly PTR requests are made to check for changes in client and upstream server hostnames. The following options are available: @@ -101,6 +101,8 @@ With this option, you can change how (and if) hourly PTR requests are made to ch This is the new default since Pi-hole FTL v5.3.2. It should resolve issues with more and more very short-lived PE IPv6 addresses coming up in a lot of networks. - `REFRESH_HOSTNAMES=ALL` - Do the hourly PTR lookups for all addresses This is the same as what we're doing with FTL v5.3(.1). This can create a lot of PTR queries for those with many IPv6 addresses in their networks. +- `REFRESH_HOSTNAMES=UNKNOWN` - Only resolve unknown hostnames + Already existing hostnames are never refreshedi, i.e., there will be no PTR queries made for clients where hostnames are known. This also means that known hostnames will not be updated once known. - `REFRESH_HOSTNAMES=NONE` - Don't do any hourly PTR lookups This means we look host names up exactly once (when we first see a client) and never again. You may miss future changes of host names. diff --git a/docs/ftldns/signals.md b/docs/ftldns/signals.md new file mode 100644 index 0000000..d9f6123 --- /dev/null +++ b/docs/ftldns/signals.md @@ -0,0 +1,78 @@ +You can influence FTL by sending signals to the process. There are various signals supported to trigger specific actions, described below. + +# Reload everything using `SIGHUP` + +When FTL receives a `SIGHUP`, it clears the entire DNS cache, and then + +- Re-loads + - `/etc/hosts`, + - `/etc/ethers`, and + - any file given by + - `dhcp-hostsfile`, + - `dhcp-optsfile`, + - `dhcp-hostsdir` (files in `dhcp-hostsdir` are also re-read on change, without the need to send a signal), + - `dhcp-optsdir` (files in `dhcp-optsdir` are also re-read on change, without the need to send a signal), + - `addn-hosts`, or + - `hostsdir`. +- The DHCP lease change script is called for all existing DHCP leases. +- If `no-poll` is set, FTL also re-reads `/etc/resolv.conf`. +- The config file specified by `servers-file` is re-read. + **Note:** No other `dnsmasq` config files are re-read. + +- The FTL database connection (`/etc/pihole/pihole-FTL.db`) is re-opened. +- The privacy level is re-read from `pihole-FTL.conf` (`PRIVACY_LEVEL`). +- The blocking status is re-read from `setupVars.conf` (`BLOCKING_ENABLED`). +- The debug settings are re-read from `pihole-FTL.conf` (`DEBUG_*`). +- The gravity database connection (`/etc/pihole/gravity.db`) is re-opened. +- The number of blocked domains is updated. +- All regular expression (RegEx) filters in `gravity.db` are re-read and pre-compiled for fast execution later on. +- The blocking cache (storing if a domain has already been analyzed and what the result was) is cleared. +- If `DEBUG_CAPS` is enabled, the current set of available capabilities is logged. + +# Real-time (RT) signals + +While `SIGHUP` updates/flushes almost everything, such a massive operation is often not necessary. Hence, we added several small real-time signals available for fine-grained control of what FTL does. When you see `SIGHUP` as a "big gun", the real-time signals are rather the "scalpel" to serve rather specific needs. + +Real-time signals are not guaranteed to have the same number on all operating systems. FTL will adapt accordingly. For the signals described below, we will always specify them with the real-time signal ID and the *typical* signal number in parentheses. + +Real-time signal can always be executed relative to the first (= minimum) real-time signal just like (for real-time signal 0): + +``` bash +sudo pkill -SIGRTMIN+0 pihole-FTL +``` + +## Real-time signal 0 (SIG34) + +This signal does: + +- The gravity database connection (`/etc/pihole/gravity.db`) is re-opened. +- The number of blocked domains is updated. +- All regular expression (RegEx) filters in `gravity.db` are re-read and pre-compiled for fast execution later on. +- The blocking cache (storing if a domain has already been analyzed and what the result was) is cleared. +- The privacy level is re-read from `pihole-FTL.conf` (`PRIVACY_LEVEL`). + +The most important difference to `SIGHUP` is that the DNS cache itself is **not** flushed. Merely the blocking cache (storing if a domain has already been analyzed and what the result was) is cleared. + +This is the preferred signal to be used after manipulating the `gravity.db` database manually as it reloads only what is needed in this case. + +## Real-time signal 1 (SIG35) + +*Reserved* - Currently ignored + +## Real-time signal 2 (SIG36) + +*Reserved* - Used for internal signaling that a fork or thread crashed and needs to inform the main process to shut down, storing the last (valid) queries still into the long-term database. + +## Real-time signal 3 (SIG37) + +Reimport alias-clients from the database and recompute affected client statistics. + +## Real-time signal 4 (SIG38) + +Re-resolve all clients and forward destination hostnames. This forces refreshing hostnames as in that the usual "resolve only recently active clients" condition is ignored. The re-resolution adheres to the specified `REFRESH_HOSTNAMES` config option meaning that this option may not try to resolve all hostnames. + +## Real-time signal 5 (SIG39) + +Re-parse ARP/neighbour-cache now to update the Network table now + +{!abbreviations.md!} diff --git a/mkdocs.yml b/mkdocs.yml index ce1f242..2c9952e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -84,6 +84,7 @@ nav: - "Tutorial": ftldns/regex/tutorial.md - 'Privacy levels': ftldns/privacylevels.md - 'Telnet API': ftldns/telnet-api.md + - 'Signals': 'ftldns/signals.md' - 'Compatibility': ftldns/compatibility.md - 'Install from source': ftldns/compile.md - 'Debugging FTLDNS': ftldns/debugging.md