From 3ea5a985cf346ef890258d77cb5723d0cdd06cf3 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Sat, 18 Feb 2023 13:48:37 +0100 Subject: [PATCH] Restructure settings page into individual smaller files. The massive file grew beyond all bounds and was rather unmaintainable. The new structure has a number of benefits, most importantly it's a lot more repsonsive as we do not have to fire a ton of individual AJAX queries to populate all tabs but only need to source what is actually displayed on the page we are showing here Signed-off-by: DL6ER --- scripts/pi-hole/js/footer.js | 42 + scripts/pi-hole/js/settings-advanced.js | 30 +- scripts/pi-hole/js/settings-dhcp.js | 23 +- scripts/pi-hole/js/settings-dns.js | 28 +- scripts/pi-hole/js/settings-system.js | 9 +- scripts/pi-hole/js/settings.js | 78 +- scripts/pi-hole/php/header_authenticated.php | 19 + scripts/pi-hole/php/sidebar.php | 47 +- settings-advanced.php | 24 + settings-dhcp.php | 201 +++++ settings-dns.php | 245 ++++++ settings-system.php | 351 ++++++++ settings.php | 858 ------------------- 13 files changed, 1012 insertions(+), 943 deletions(-) create mode 100644 settings-advanced.php create mode 100644 settings-dhcp.php create mode 100644 settings-dns.php create mode 100644 settings-system.php delete mode 100644 settings.php diff --git a/scripts/pi-hole/js/footer.js b/scripts/pi-hole/js/footer.js index 69cb7b8f..b814f1ff 100644 --- a/scripts/pi-hole/js/footer.js +++ b/scripts/pi-hole/js/footer.js @@ -187,6 +187,10 @@ function updateFtlInfo() { $("#sysinfo-cpu-ftl").text("(" + ftl["%cpu"].toFixed(1) + "% used by FTL)"); $("#sysinfo-ram-ftl").text("(" + ftl["%mem"].toFixed(1) + "% used by FTL)"); $("#sysinfo-pid-ftl").text(ftl.pid); + var startdate = moment() + .subtract(ftl.uptime, "milliseconds") + .format("dddd, MMMM Do YYYY, HH:mm:ss"); + $("#sysinfo-uptime-ftl").text(startdate); $("#sysinfo-privacy_level").text(ftl.privacy_level); $("#sysinfo-ftl-overlay").hide(); // Update every 120 seconds @@ -517,3 +521,41 @@ $("#pihole-disable-custom").on("click", function (e) { custVal = $("#btnMins").hasClass("active") ? custVal * 60 : custVal; piholeChange("disable", custVal); }); + +function initSettingsLevel() { + // Restore settings level from local storage (if available) or default to 0 + var level = localStorage.getItem("settings-level"); + if (level === null) { + level = "0"; + } + + // Set the settings level + $("#settings-level").val(level); + applySettingsLevel(level); +} + +function applySettingsLevel(level) { + if (level === "2") { + $(".settings-level-0").show(); + $(".settings-level-1").show(); + $(".settings-level-2").show(); + } else if (level === "1") { + $(".settings-level-0").show(); + $(".settings-level-1").show(); + $(".settings-level-2").hide(); + } else { + $(".settings-level-0").show(); + $(".settings-level-1").hide(); + $(".settings-level-2").hide(); + } +} + +$("#settings-level").on("change", function () { + var level = $(this).val(); + applySettingsLevel(level); + localStorage.setItem("settings-level", level); +}); + +$(function () { + initSettingsLevel(); +}); diff --git a/scripts/pi-hole/js/settings-advanced.js b/scripts/pi-hole/js/settings-advanced.js index 5607cb71..042ddf8b 100644 --- a/scripts/pi-hole/js/settings-advanced.js +++ b/scripts/pi-hole/js/settings-advanced.js @@ -5,7 +5,7 @@ * This file is copyright under the latest version of the EUPL. * Please see LICENSE file for your rights under this license. */ -/* global utils:false, apiFailure: false, applyCheckboxRadioStyle: false, fillDNSupstreams: false */ +/* global utils:false, apiFailure: false, applyCheckboxRadioStyle: false */ /* exported createDynamicConfigTabs */ function addAllowedValues(allowed) { @@ -34,20 +34,6 @@ function generateRow(topic, key, value) { return; } - // Select listening mode radio button - var escapedKey = key.replace(/\./g, "\\."); - if (value.type === "enum (string)") { - $("#" + escapedKey + "-" + value.value).trigger("click"); - } else if (value.type === "boolean") { - // Select checkboxes (if available) - $("#" + escapedKey).prop("checked", value.value); - } else if ( - ["string", "IPv4 address", "IPv6 address", "integer", "unsigned integer"].includes(value.type) - ) { - // Set input field values (if available) - $("#" + escapedKey).val(value.value); - } - // else: we have a setting we can display var box = '
' + @@ -238,21 +224,11 @@ function generateRow(topic, key, value) { elem.append(box); } -function fillDHCPhosts(data) { - $("#dhcp-hosts").val(data.value.join("\n")); -} - -// eslint-disable-next-line no-unused-vars function createDynamicConfigTabs() { $.ajax({ url: "/api/config?detailed=true", }) .done(function (data) { - // Initialize the DNS upstreams - fillDNSupstreams(data.config.dns.upstreams, data.dns_servers); - - fillDHCPhosts(data.config.dhcp.hosts); - // Create the content for the advanced dynamic config topics Object.keys(data.topics).forEach(function (n) { var topic = data.topics[n]; @@ -297,3 +273,7 @@ function createDynamicConfigTabs() { apiFailure(data); }); } + +$(document).ready(function () { + createDynamicConfigTabs(); +}); diff --git a/scripts/pi-hole/js/settings-dhcp.js b/scripts/pi-hole/js/settings-dhcp.js index 88b2173f..db741960 100644 --- a/scripts/pi-hole/js/settings-dhcp.js +++ b/scripts/pi-hole/js/settings-dhcp.js @@ -5,7 +5,7 @@ * This file is copyright under the latest version of the EUPL. * Please see LICENSE file for your rights under this license. */ -/* global utils:false */ +/* global utils:false, setConfigValues: false, apiFailure: false */ var dhcpLeaesTable = null; @@ -204,3 +204,24 @@ function delLease(ip) { console.log(exception); // eslint-disable-line no-console }); } + +function fillDHCPhosts(data) { + $("#dhcp-hosts").val(data.value.join("\n")); +} + +function processDHCPConfig() { + $.ajax({ + url: "/api/config/dhcp?detailed=true", + }) + .done(function (data) { + fillDHCPhosts(data.config.dhcp.hosts); + setConfigValues("dhcp", "dhcp", data.config.dhcp); + }) + .fail(function (data) { + apiFailure(data); + }); +} + +$(document).ready(function () { + processDHCPConfig(); +}); diff --git a/scripts/pi-hole/js/settings-dns.js b/scripts/pi-hole/js/settings-dns.js index e4f3606e..01eed719 100644 --- a/scripts/pi-hole/js/settings-dns.js +++ b/scripts/pi-hole/js/settings-dns.js @@ -5,7 +5,7 @@ * This file is copyright under the latest version of the EUPL. * Please see LICENSE file for your rights under this license. */ -/* exported fillDNSupstreams */ +/* global applyCheckboxRadioStyle:false, setConfigValues: false, apiFailure: false */ // Remove an element from an array (inline) function removeFromArray(arr, what) { @@ -17,7 +17,6 @@ function removeFromArray(arr, what) { } } -// eslint-disable-next-line no-unused-vars function fillDNSupstreams(value, servers) { var i = 0; var customServers = value.value.length; @@ -81,11 +80,36 @@ function fillDNSupstreams(value, servers) { // Initialize textfield updateDNSserversTextfield(value.value, customServers); + + // Hide the loading animation + $("#dns-upstreams-overlay").hide(); + + // Apply styling to the new checkboxes + applyCheckboxRadioStyle(); } +// Update the textfield with all (incl. custom) upstream servers function updateDNSserversTextfield(upstreams, customServers) { $("#DNSupstreamsTextfield").val(upstreams.join("\n")); $("#custom-servers-title").text( "(" + customServers + " custom server" + (customServers === 1 ? "" : "s") + " enabled)" ); } + +function processDNSConfig() { + $.ajax({ + url: "/api/config/dns?detailed=true", // We need the detailed output to get the DNS server list + }) + .done(function (data) { + // Initialize the DNS upstreams + fillDNSupstreams(data.config.dns.upstreams, data.dns_servers); + setConfigValues("dns", "dns", data.config.dns); + }) + .fail(function (data) { + apiFailure(data); + }); +} + +$(document).ready(function () { + processDNSConfig(); +}); diff --git a/scripts/pi-hole/js/settings-system.js b/scripts/pi-hole/js/settings-system.js index ea1ab501..d8fd7719 100644 --- a/scripts/pi-hole/js/settings-system.js +++ b/scripts/pi-hole/js/settings-system.js @@ -9,7 +9,7 @@ /* exported updateHostInfo, updateCacheInfo */ var hostinfoTimer = null; -// eslint-disable-next-line no-unused-vars + function updateHostInfo() { $.ajax({ url: "/api/info/host", @@ -59,7 +59,7 @@ function setMetrics(data, prefix) { } var metricsTimer = null; -// eslint-disable-next-line no-unused-vars + function updateMetrics() { $.ajax({ url: "/api/info/metrics", @@ -178,3 +178,8 @@ $(".confirm-disablelogging-noflush").confirm({ cancelButtonClass: "btn-success", dialogClass: "modal-dialog", }); + +$(function () { + updateHostInfo(); + updateMetrics(); +}); diff --git a/scripts/pi-hole/js/settings.js b/scripts/pi-hole/js/settings.js index 5be7fda0..b67ab21c 100644 --- a/scripts/pi-hole/js/settings.js +++ b/scripts/pi-hole/js/settings.js @@ -5,49 +5,6 @@ * This file is copyright under the latest version of the EUPL. * Please see LICENSE file for your rights under this license. */ -/* global updateHostInfo:false, updateMetrics:false, createDynamicConfigTabs:false */ - -$(function () { - updateHostInfo(); - updateMetrics(); - createDynamicConfigTabs(); -}); - -// Change "?tab=" parameter in URL for save and reload -$(".nav-tabs a").on("shown.bs.tab", function (e) { - var tab = e.target.hash.substring(1); - window.history.pushState("", "", "?tab=" + tab); - window.scrollTo(0, 0); -}); - -function initSettingsLevel() { - // Restore settings level from local storage (if available) or default to 0 - var level = localStorage.getItem("settings-level"); - if (level === null) { - level = "0"; - } - - // Set the settings level - $("#settings-level").val(level); - applySettingsLevel(level); -} - -function applySettingsLevel(level) { - if (level === "2") { - $(".settings-level-0").show(); - $(".settings-level-1").show(); - $(".settings-level-2").show(); - } else if (level === "1") { - $(".settings-level-0").show(); - $(".settings-level-1").show(); - $(".settings-level-2").hide(); - } else { - $(".settings-level-0").show(); - $(".settings-level-1").hide(); - $(".settings-level-2").hide(); - } -} - // Handle hiding of alerts $(function () { $("[data-hide]").on("click", function () { @@ -55,12 +12,31 @@ $(function () { .closest("." + $(this).attr("data-hide")) .hide(); }); - - $("#settings-level").on("change", function () { - var level = $(this).val(); - applySettingsLevel(level); - localStorage.setItem("settings-level", level); - }); - - initSettingsLevel(); }); + +// Globally available function to set config values +// eslint-disable-next-line no-unused-vars +function setConfigValues(topic, key, value) { + // If the value is an object, we need to recurse + if (!("description" in value)) { + Object.keys(value).forEach(function (subkey) { + var subvalue = value[subkey]; + setConfigValues(topic, key + "." + subkey, subvalue); + }); + return; + } + + // else: we have a setting we can set + var escapedKey = key.replace(/\./g, "\\."); + if (value.type === "enum (string)") { + $("#" + escapedKey + "-" + value.value).trigger("click"); + } else if (value.type === "boolean") { + // Select checkboxes (if available) + $("#" + escapedKey).prop("checked", value.value); + } else if ( + ["string", "IPv4 address", "IPv6 address", "integer", "unsigned integer"].includes(value.type) + ) { + // Set input field values (if available) + $("#" + escapedKey).val(value.value); + } +} diff --git a/scripts/pi-hole/php/header_authenticated.php b/scripts/pi-hole/php/header_authenticated.php index 98805870..2678ae29 100644 --- a/scripts/pi-hole/php/header_authenticated.php +++ b/scripts/pi-hole/php/header_authenticated.php @@ -9,6 +9,14 @@ */ require 'header.php'; +// Function to check string starting +// with given substring +function startsWith($string, $startString) +{ + $len = strlen($startString); + + return substr($string, 0, $len) === $startString; +} ?> @@ -54,6 +62,17 @@ require 'header.php';
    + +
  • +

    + Settings level: +

    +
    • +
-
  • - - Settings +
  • + + Settings + + + +
    • diff --git a/settings-advanced.php b/settings-advanced.php new file mode 100644 index 00000000..76cf46f7 --- /dev/null +++ b/settings-advanced.php @@ -0,0 +1,24 @@ + +
    + +
    + +
    +
    + + + + diff --git a/settings-dhcp.php b/settings-dhcp.php new file mode 100644 index 00000000..f7d36747 --- /dev/null +++ b/settings-dhcp.php @@ -0,0 +1,201 @@ + +
    + +
    +
    +
    +

    DHCP Settings

    +
    +
    +
    +
    +
    +

    Make sure your router's DHCP server is disabled when using the Pi-hole DHCP server!

    +
    +
    + +
    +
    +
    +
    +
    From
    + +
    +
    +
    +
    +
    +
    +
    To
    + +
    +
    +
    +
    + +
    +
    +
    Router
    + +
    +
    +
    +
    +
     
    +

    Enable this option to enable IPv6 support for the Pi-hole DHCP server. This will allow the Pi-hole to hand out IPv6 addresses to clients and also provide IPv6 router advertisements (RA) to clients. This option is only useful if the Pi-hole is configured with an IPv6 address.

    +
    +
    +
    +
    +
    +
    +
    +
    +

    Advanced DHCP Settings

    +
    +
    +
    +
    + +
    +
    +
    Domain
    + +
    +
    +

    The DNS domains for the DHCP server. If no domain is specified, then any DHCP hostname with a domain part (i.e., with a period) will be disallowed. If a domain is specified, then hostnames with a domain parts matching the domain here are allowed. In addition, when a suffix is set then hostnames without a domain part have the suffix added as an optional domain part.

    +
    +
    + +
    +
    +
    Lease time
    + +
    +
    +

    The lease time can be in seconds, minutes (e.g., "45m"), hours (e.g., "1h"), days (like "2d"), or even weeks ("1w"). You may also use "infinite" as string but be aware of the drawbacks: assigned addresses are will only be made available again after the lease time has passed or when leases are manually deleted below.

    +
    +
    +
     
    +

    The DHCPv4 rapid commit option allows the Pi-hole DHCP server to assign an IP address to a client right away. This can noteably speed up the address assignment process and you will notice, e.g., faster WiFi joins in your network. This option should only be enabled if the Pi-hole DHCP server is the only DHCP server in your network.

    +
    +
    +
    +
    +
    +
    + + +
    +
    +
    +
    +

    Currently active DHCP leases

    +
    +
    +
    +
    + + + + + + + + + + + + + + +
    IP addressHostnameMAC addressExpirationClient ID
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Static DHCP configuration  

    +
    +
    +
    +
    +

    Specify per host parameters for the DHCP server. This allows a machine with a particular hardware address to be always allocated the same hostname, IP address and lease time. A hostname specified like this overrides any supplied by the DHCP client on the machine. It is also allowable to omit the hardware address and include the hostname, in which case the IP address and lease times will apply to any machine claiming that name.

    +
      +

    Each entry should be on a separate line, and should be of the form:

    + 
    [<hwaddr>][,id:<client_id>|*][,set:<tag>][,tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
    +

    Only one entry per MAC address is allowed.

    +
    +
    +

    Examples: +

      + 
    • 00:20:e0:3b:13:af,192.168.0.123
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the address 192.168.0.123
       
      • + 
    • 00:20:e0:3b:13:af,laptop
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the name laptop
       
      • + 
    • 00:20:e0:3b:13:af,192.168.0.123,laptop,infinite
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the address 192.168.0.123, the name laptop, and an infinite DHCP lease
       
      • +
    +

    +
    +
    +
    +
    +

    Advanced description

    +
    + +
    +
    +
    +
      +
    • Addresses allocated like this are not constrained to be in the DHCP range specified above but they must be in the same subnet. For subnets which don't need a pool of dynamically allocated addresses, you can set a one-address range above and specify only static leases here.
      • +
    • It is allowed to use client identifiers (called client DUID in IPv6-land) rather than hardware addresses to identify hosts by prefixing with id:. Thus lines like id:01:02:03:04,..... refer to the host with client identifier 01:02:03:04. It is also allowed to specify the client ID as text, like this: id:clientidastext,.....
      • +
    • A single line may contain an IPv4 address or one or more IPv6 addresses, or both. IPv6 addresses must be bracketed by square brackets thus: laptop,[1234::56] IPv6 addresses may contain only the host-identifier part: laptop,[::56] in which case they act as wildcards in constructed DHCP ranges, with the appropriate network part inserted. For IPv6, an address may include a prefix length: laptop,[1234:50/126] which (in this case) specifies four addresses, 1234::50 to 1234::53. This (an the ability to specify multiple addresses) is useful when a host presents either a consistent name or hardware-ID, but varying DUIDs, since it allows dnsmasq to honour the static address allocation but assign a different adddress for each DUID. This typically occurs when chain netbooting, as each stage of the chain gets in turn allocates an address.
      • + +
    • For DHCPv4, the special option id:* means "ignore any client-id and use MAC addresses only." This is useful when a client presents a client-id sometimes but not others.
      • +
    • If a name appears in /etc/hosts, the associated address can be allocated to a DHCP lease, but only if a separate line specifying the name also exists. Only one hostname can be given per line, but aliases are possible by using CNAMEs. Note that /etc/hosts is NOT used when the DNS server side of dnsmasq is disabled by setting the DNS server port to zero.
      • +
    • More than one line can be associated (by name, hardware address or UID) with a host. Which one is used (and therefore which address is allocated by DHCP and appears in the DNS) depends on the subnet on which the host last obtained a DHCP lease: the line with an address within the subnet is used. If more than one address is within the subnet, the result is undefined. A corollary to this is that the name associated with a host defined here does not appear in the DNS until the host obtains a DHCP lease.
      • +
    • The special keyword ignore tells Pi-hole to never offer a DHCP lease to a machine. The machine can be specified by hardware address, client ID or hostname, for instance 00:20:e0:3b:13:af,ignore. This is useful when there is another DHCP server on the network which should be used by some machines.
      • +
    • The set:<tag> construct sets the tag whenever this line is in use. This can be used to selectively send DHCP options just for this host. More than one tag can be set per line directive (but not in other places where "set:<tag>" is allowed). When a host matches any directive (or one implied by /etc/ethers) then the special tag "known"" is set. This allows Pi-hole to be configured to ignore requests from unknown machines using a custom config option dhcp-ignore=tag:!known in your own config file. If the host matches only a directive which cannot be used because it specifies an address on different subnet, the tag "known-othernet" is set.
      • +
    • The tag:<tag> construct filters which directives are used; more than one can be provided, in this case the request must match all of them. Tagged directives are used in preference to untagged ones. Note that one of <hwaddr>;, <client_id>; or <hostname>; still needs to be specified (can be a wildcard).
      • +
    • Ethernet addresses (but not client-ids) may have wildcard bytes, so for example 00:20:e0:3b:13:*,ignore will cause Pi-hole to ignore a range of hardware addresses.
      • +
    • Hardware addresses normally match any network (ARP) type, but it is possible to restrict them to a single ARP type by preceding them with the ARP-type (in HEX) and "-". so the line 06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring hardware address, since the ARP-address type for token ring is 6.
      • +
    • As a special case, in DHCPv4, it is possible to include more than one hardware address. eg: 11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2. This allows an IP address to be associated with multiple hardware addresses, and gives Pi-hole permission to abandon a DHCP lease to one of the hardware addresses when another one asks for a lease. Beware that this is a dangerous thing to do, it will only work reliably if only one of the hardware addresses is active at any time and there is no way for dnsmasq to enforce this. It is, for instance, useful to allocate a stable IP address to a laptop which has both wired and wireless interfaces.
      • +
    +
    +
    +
    +
    +
    +
    + +
    +
    + + + + diff --git a/settings-dns.php b/settings-dns.php new file mode 100644 index 00000000..7b41de88 --- /dev/null +++ b/settings-dns.php @@ -0,0 +1,245 @@ + +
    +
    +
    +
    +

    Upstream DNS Servers

    +
    +
    +
    +
    + + + + + + + + + + +
    IPv4IPv6Name
    +

    ECS (Extended Client Subnet) defines a mechanism for recursive resolvers to send partial client IP address information to authoritative DNS name servers. Content Delivery Networks (CDNs) and latency-sensitive services use this to give geo-located responses when responding to name lookups coming through public DNS resolvers. Note that ECS may result in reduced privacy.

    +
    +
    +
    +
    +

    Custom DNS servers

    +
    + +
    +
    +
    +

    The following list contains all DNS servers selected above. Furthermore, you can add your own custom DNS servers here. The expected format is one server per line in form of IP#port, where the port is optional. If given, it has to be separated by a hash # from the address (e.g. 127.0.0.1#5335 for a local unbound istance running on port 5335). The port defaults to 53 if omitted.

    + +
    +
    +
    +
    +
    + +
    +
    +
    +
    +
    +

    Conditional forwarding  

    +
    +
    +
    +
    +

    If not configured as your DHCP server, Pi-hole typically won't be able to + determine the names of devices on your local network. As a + result, tables such as Top Clients will only show IP addresses.

    +

    One solution for this is to configure Pi-hole to forward these + requests to your DHCP server (most likely your router), but only for devices on your + home network. To configure this we will need to know the IP + address of your DHCP server and which addresses belong to your local network. + Exemplary input is given below as placeholder in the text boxes (if empty).

    +

    If your local network spans 192.168.0.1 - 192.168.0.255, then you will have to input + 192.168.0.0/24. If your local network is 192.168.47.1 - 192.168.47.255, it will + be 192.168.47.0/24 and similar. If your network is larger, the CIDR has to be + different, for instance a range of 10.8.0.1 - 10.8.255.255 results in 10.8.0.0/16, + whereas an even wider network of 10.0.0.1 - 10.255.255.255 results in 10.0.0.0/8. + Setting up IPv6 ranges is exactly similar to setting up IPv4 here and fully supported. + Feel free to reach out to us on our + Discourse forum + in case you need any assistance setting up local host name resolution for your particular system.

    +

    You can also specify a local domain name (like fritz.box) to ensure queries to + devices ending in your local domain name will not leave your network, however, this is optional. + The local domain name must match the domain name specified + in your DHCP server for this to work. You can likely find it within the DHCP settings.

    +

    Enabling Conditional Forwarding will also forward all hostnames (i.e., non-FQDNs) to the router + when "Never forward non-FQDNs" is not enabled.

    +
    +
    + + +
    +
    + + + + + + + + + + + + + + + +
    Local network in CIDR notationIP address of your DHCP server (router)Local domain name (optional)
    + + + + + +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +
    +

    Interface settings  

    +
    +
    +
    +
    +
    +
    +

    Recommended setting

    +
    + + +
    +
    +
    +

    Potentially dangerous options

    Make sure your Pi-hole is properly firewalled! +
    + + +
    +
    + + +
    +
    + + +
    +

    These options are dangerous on devices + directly connected to the Internet such as cloud instances and are only safe if your + Pi-hole is properly firewalled. In a typical at-home setup where your Pi-hole is + located within your local network (and you have not forwarded port 53 + in your router!) they are safe to use.

    +
    +
    +

    See our documentation for further technical details.

    +
    +
    +
    +
    +
    +
    +

    Advanced DNS settings

    +
    +
    +
    +
    +
    + + +

    Tells Pi-hole to never forward A or AAAA queries for plain + names, without dots or domain parts, to upstream nameservers. If + the name is not known from /etc/hosts or DHCP then a "not found" + answer is returned.
    + If Conditional Forwarding is enabled, unticking this box may cause a partial + DNS loop under certain circumstances (e.g. if a client would send TLD DNSSEC queries).

    +
    +
    +
    + + +

    All reverse lookups for private IP ranges (i.e., 192.168.0.x/24, etc.) + which are not found in /etc/hosts or the DHCP leases are answered + with "no such domain" rather than being forwarded upstream. The set + of prefixes affected is the list given in RFC6303.

    +

    Important: Enabling these two options may increase your privacy, + but may also prevent you from being able to access + local hostnames if the Pi-hole is not used as DHCP server.

    +
    +
    +
    + + +

    Validate DNS replies and cache DNSSEC data. When forwarding DNS + queries, Pi-hole requests the DNSSEC records needed to validate + the replies. If a domain fails validation or the upstream does not + support DNSSEC, this setting can cause issues resolving domains. + Use an upstream DNS server which supports DNSSEC when activating DNSSEC. Note that + the size of your log might increase significantly + when enabling DNSSEC. A DNSSEC resolver test can be found + here.

    +
    +
    +
    +
    +
    +
    +
    +

    Rate-limiting  

    +
    +
    +
    +
    +

    Block clients making more than queries within + seconds.

    +

    When a client makes too many queries in too short time, it + gets rate-limited. Rate-limited queries are answered with a + REFUSED reply and not further processed by FTL + and prevent Pi-holes getting overwhelmed by rogue clients. + It is important to note that rate-limiting is happening on a + per-client basis. Other clients can continue to use FTL while + rate-limited clients are short-circuited at the same time.

    +

    Rate-limiting may be disabled altogether by setting both + values to zero. See + our documentation + for further details.

    +
    +
    +
    +
    +
    +
    + +
    +
    +
    + + + + diff --git a/settings-system.php b/settings-system.php new file mode 100644 index 00000000..5440ba8c --- /dev/null +++ b/settings-system.php @@ -0,0 +1,351 @@ + +
    +
    +
    +
    +

    System Information

    +
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Hostname:
    CPU:
    RAM: +
    Swap:
    Kernel:
    Uptime:
    FTL:PID ?, last restart was on
    +
    +
    +
    +
    + +
    +
    +
    +
    +

    DHCP server metrics

    +
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + DHCPDISCOVER: +  
    + DHCPOFFER: +  
    + DHCPREQUEST: +  
    + DHCPACK: +  
    + DHCPNAK: +  
    + DHCPDECLINE: +  
    + DHCPINFORM: +  
    + DHCPRELEASE: +  
    + DHCPNOANSWER: +  
    + BOOTP: +  
    + PXE: +  
    + Allocated / pruned IPv4 leases: +   / +   +
    + Allocated / pruned IPv6 leases: +   / +   +
    +
    +
    +
    +
    + +
    +
    +
    +
    +
    +
    +

    DNS cache metrics

    +
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + +
    + DNS cache size: +  
    + DNS cache insertions: +  
    + DNS cache evictions: +  
    + DNS cache expiries: +  
    + Immortal DNS cache entries: +  
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + Valid A records in cache: +  
    + Valid AAAA records in cache: +  
    + Valid CNAME records in cache: +  
    + Valid SRV records in cache: +  
    + Valid DS records in cache: +  
    + Valid DNSKEY records in cache: +  
    + Other valid records in cache: +  
    + See also our DNS cache documentation. +
    +
    +
    +
    + +
    +
    +
    +
    +

    DNS reply metrics

    +
    +
    +
    +
    + + + + + + + + + + + + + + + + + + + + + + + +
    + Local/cache replies: +  
    + Forwarded queries: +  
    + Cache optimizer replies: +  
    + Unanswered queries: +  
    + Authoritative replies: +  
    +
    +
    +
    +
    + +
    +
    +
    +
    +
    +
    +

    Actions  

    +
    +
    +
    +
    + + + + + +
    + +
    + +
    + +
    + +
    +
    + +
    + +
    + +
    + +
    + +
    +
    +
    +
    +
    +
    + + + + + diff --git a/settings.php b/settings.php deleted file mode 100644 index 61f1e61d..00000000 --- a/settings.php +++ /dev/null @@ -1,858 +0,0 @@ - -
    -
    -
    - - -
    - -
    -
    -
    -
    -
    -

    System Information

    -
    -
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Hostname:
    CPU:
    Used memory: -
    Used swap:
    Kernel:
    Uptime:
    -
    -
    -
    -
    - -
    -
    -
    -
    -

    DHCP server metrics

    -
    -
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - DHCPDISCOVER: -  
    - DHCPOFFER: -  
    - DHCPREQUEST: -  
    - DHCPACK: -  
    - DHCPNAK: -  
    - DHCPDECLINE: -  
    - DHCPINFORM: -  
    - DHCPRELEASE: -  
    - DHCPNOANSWER: -  
    - BOOTP: -  
    - PXE: -  
    - Allocated / pruned IPv4 leases: -   / -   -
    - Allocated / pruned IPv6 leases: -   / -   -
    -
    -
    -
    -
    - -
    -
    -
    -
    -

    FTL Information

    -
    -
    -
    -
    - - - - - - - - - - - -
    FTL's PID:
    Privacy level:
    -
    -
    -
    -
    - -
    -
    -
    -
    -
    -
    -

    DNS cache metrics

    -
    -
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - -
    - DNS cache size: -  
    - DNS cache insertions: -  
    - DNS cache evictions: -  
    - DNS cache expiries: -  
    - Immortal DNS cache entries: -  
    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - Valid A records in cache: -  
    - Valid AAAA records in cache: -  
    - Valid CNAME records in cache: -  
    - Valid SRV records in cache: -  
    - Valid DS records in cache: -  
    - Valid DNSKEY records in cache: -  
    - Other valid records in cache: -  
    - See also our DNS cache documentation. -
    -
    -
    -
    - -
    -
    -
    -
    -

    DNS reply metrics

    -
    -
    -
    -
    - - - - - - - - - - - - - - - - - - - - - - - -
    - Local replies: -  
    - Forwarded queries: -  
    - Unanswered queries: -  
    - Cache optimizer replies: -  
    - Authoritative replies: -  
    -
    -
    -
    -
    - -
    -
    -
    -
    -
    -
    -

    Actions  

    -
    -
    -
    -
    - - - - - -
    - -
    - -
    - -
    - -
    -
    - -
    - -
    - -
    - -
    - -
    -
    -
    -
    -
    -
    -
    - -
    -
    -
    -
    -
    -

    Upstream DNS Servers

    -
    -
    -
    -
    - - - - - - - - - - -
    IPv4IPv6Name
    -

    ECS (Extended Client Subnet) defines a mechanism for recursive resolvers to send partial client IP address information to authoritative DNS name servers. Content Delivery Networks (CDNs) and latency-sensitive services use this to give geo-located responses when responding to name lookups coming through public DNS resolvers. Note that ECS may result in reduced privacy.

    -
    -
    -
    -
    -

    Custom DNS servers

    -
    - -
    -
    -
    -

    The following list contains all DNS servers selected above. Furthermore, you can add your own custom DNS servers here. The expected format is one server per line in form of IP#port, where the port is optional. If given, it has to be separated by a hash # from the address (e.g. 127.0.0.1#5335 for a local unbound istance running on port 5335). The port defaults to 53 if omitted.

    - -
    -
    -
    -
    -
    -
    -
    -
    -

    Conditional forwarding  

    -
    -
    -
    -
    -

    If not configured as your DHCP server, Pi-hole typically won't be able to - determine the names of devices on your local network. As a - result, tables such as Top Clients will only show IP addresses.

    -

    One solution for this is to configure Pi-hole to forward these - requests to your DHCP server (most likely your router), but only for devices on your - home network. To configure this we will need to know the IP - address of your DHCP server and which addresses belong to your local network. - Exemplary input is given below as placeholder in the text boxes (if empty).

    -

    If your local network spans 192.168.0.1 - 192.168.0.255, then you will have to input - 192.168.0.0/24. If your local network is 192.168.47.1 - 192.168.47.255, it will - be 192.168.47.0/24 and similar. If your network is larger, the CIDR has to be - different, for instance a range of 10.8.0.1 - 10.8.255.255 results in 10.8.0.0/16, - whereas an even wider network of 10.0.0.1 - 10.255.255.255 results in 10.0.0.0/8. - Setting up IPv6 ranges is exactly similar to setting up IPv4 here and fully supported. - Feel free to reach out to us on our - Discourse forum - in case you need any assistance setting up local host name resolution for your particular system.

    -

    You can also specify a local domain name (like fritz.box) to ensure queries to - devices ending in your local domain name will not leave your network, however, this is optional. - The local domain name must match the domain name specified - in your DHCP server for this to work. You can likely find it within the DHCP settings.

    -

    Enabling Conditional Forwarding will also forward all hostnames (i.e., non-FQDNs) to the router - when "Never forward non-FQDNs" is not enabled.

    -
    -
    - - -
    -
    - - - - - - - - - - - - - - - -
    Local network in CIDR notationIP address of your DHCP server (router)Local domain name (optional)
    - - - - - -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -
    -

    Interface settings  

    -
    -
    -
    -
    -
    -
    -

    Recommended setting

    -
    - - -
    -
    -
    -

    Potentially dangerous options

    Make sure your Pi-hole is properly firewalled! -
    - - -
    -
    - - -
    -
    - - -
    -

    These options are dangerous on devices - directly connected to the Internet such as cloud instances and are only safe if your - Pi-hole is properly firewalled. In a typical at-home setup where your Pi-hole is - located within your local network (and you have not forwarded port 53 - in your router!) they are safe to use.

    -
    -
    -

    See our documentation for further technical details.

    -
    -
    -
    -
    -
    -
    -

    Advanced DNS settings

    -
    -
    -
    -
    -
    - - -

    Tells Pi-hole to never forward A or AAAA queries for plain - names, without dots or domain parts, to upstream nameservers. If - the name is not known from /etc/hosts or DHCP then a "not found" - answer is returned.
    - If Conditional Forwarding is enabled, unticking this box may cause a partial - DNS loop under certain circumstances (e.g. if a client would send TLD DNSSEC queries).

    -
    -
    -
    - - -

    All reverse lookups for private IP ranges (i.e., 192.168.0.x/24, etc.) - which are not found in /etc/hosts or the DHCP leases are answered - with "no such domain" rather than being forwarded upstream. The set - of prefixes affected is the list given in RFC6303.

    -

    Important: Enabling these two options may increase your privacy, - but may also prevent you from being able to access - local hostnames if the Pi-hole is not used as DHCP server.

    -
    -
    -
    - - -

    Validate DNS replies and cache DNSSEC data. When forwarding DNS - queries, Pi-hole requests the DNSSEC records needed to validate - the replies. If a domain fails validation or the upstream does not - support DNSSEC, this setting can cause issues resolving domains. - Use an upstream DNS server which supports DNSSEC when activating DNSSEC. Note that - the size of your log might increase significantly - when enabling DNSSEC. A DNSSEC resolver test can be found - here.

    -
    -
    -
    -
    -
    -
    -
    -

    Rate-limiting  

    -
    -
    -
    -
    -

    Block clients making more than queries within - seconds.

    -

    When a client makes too many queries in too short time, it - gets rate-limited. Rate-limited queries are answered with a - REFUSED reply and not further processed by FTL - and prevent Pi-holes getting overwhelmed by rogue clients. - It is important to note that rate-limiting is happening on a - per-client basis. Other clients can continue to use FTL while - rate-limited clients are short-circuited at the same time.

    -

    Rate-limiting may be disabled altogether by setting both - values to zero. See - our documentation - for further details.

    -
    -
    -
    -
    -
    -
    - -
    -
    -
    - -
    -
    - -
    -
    -
    -

    DHCP Settings

    -
    -
    -
    -
    -
    -

    Make sure your router's DHCP server is disabled when using the Pi-hole DHCP server!

    -
    -
    - -
    -
    -
    -
    -
    From
    - -
    -
    -
    -
    -
    -
    -
    To
    - -
    -
    -
    -
    - -
    -
    -
    Router
    - -
    -
    -
    -
    -
     
    -

    Enable this option to enable IPv6 support for the Pi-hole DHCP server. This will allow the Pi-hole to hand out IPv6 addresses to clients and also provide IPv6 router advertisements (RA) to clients. This option is only useful if the Pi-hole is configured with an IPv6 address.

    -
    -
    -
    -
    -
    -
    -
    -
    -

    Advanced DHCP Settings

    -
    -
    -
    -
    - -
    -
    -
    Domain
    - -
    -
    -

    The DNS domains for the DHCP server. If no domain is specified, then any DHCP hostname with a domain part (i.e., with a period) will be disallowed. If a domain is specified, then hostnames with a domain parts matching the domain here are allowed. In addition, when a suffix is set then hostnames without a domain part have the suffix added as an optional domain part.

    -
    -
    - -
    -
    -
    Lease time
    - -
    -
    -

    The lease time can be in seconds, minutes (e.g., "45m"), hours (e.g., "1h"), days (like "2d"), or even weeks ("1w"). You may also use "infinite" as string but be aware of the drawbacks: assigned addresses are will only be made available again after the lease time has passed or when leases are manually deleted below.

    -
    -
    -
     
    -

    The DHCPv4 rapid commit option allows the Pi-hole DHCP server to assign an IP address to a client right away. This can noteably speed up the address assignment process and you will notice, e.g., faster WiFi joins in your network. This option should only be enabled if the Pi-hole DHCP server is the only DHCP server in your network.

    -
    -
    -
    -
    -
    -
    - - -
    -
    -
    -
    -

    Currently active DHCP leases

    -
    -
    -
    -
    - - - - - - - - - - - - - - -
    IP addressHostnameMAC addressExpirationClient ID
    -
    -
    -
    -
    -
    -
    -
    -
    -

    Static DHCP configuration  

    -
    -
    -
    -
    -

    Specify per host parameters for the DHCP server. This allows a machine with a particular hardware address to be always allocated the same hostname, IP address and lease time. A hostname specified like this overrides any supplied by the DHCP client on the machine. It is also allowable to omit the hardware address and include the hostname, in which case the IP address and lease times will apply to any machine claiming that name.

    -
      -

    Each entry should be on a separate line, and should be of the form:

    - 
    [<hwaddr>][,id:<client_id>|*][,set:<tag>][,tag:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
    -

    Only one entry per MAC address is allowed.

    -
    -
    -

    Examples: -

      - 
    • 00:20:e0:3b:13:af,192.168.0.123
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the address 192.168.0.123
       
      • - 
    • 00:20:e0:3b:13:af,laptop
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the name laptop
       
      • - 
    • 00:20:e0:3b:13:af,192.168.0.123,laptop,infinite
      tells Pi-hole to give the machine with hardware address 00:20:e0:3b:13:af the address 192.168.0.123, the name laptop, and an infinite DHCP lease
       
      • -
    -

    -
    -
    -
    -
    -

    Advanced description

    -
    - -
    -
    -
    -
      -
    • Addresses allocated like this are not constrained to be in the DHCP range specified above but they must be in the same subnet. For subnets which don't need a pool of dynamically allocated addresses, you can set a one-address range above and specify only static leases here.
      • -
    • It is allowed to use client identifiers (called client DUID in IPv6-land) rather than hardware addresses to identify hosts by prefixing with id:. Thus lines like id:01:02:03:04,..... refer to the host with client identifier 01:02:03:04. It is also allowed to specify the client ID as text, like this: id:clientidastext,.....
      • -
    • A single line may contain an IPv4 address or one or more IPv6 addresses, or both. IPv6 addresses must be bracketed by square brackets thus: laptop,[1234::56] IPv6 addresses may contain only the host-identifier part: laptop,[::56] in which case they act as wildcards in constructed DHCP ranges, with the appropriate network part inserted. For IPv6, an address may include a prefix length: laptop,[1234:50/126] which (in this case) specifies four addresses, 1234::50 to 1234::53. This (an the ability to specify multiple addresses) is useful when a host presents either a consistent name or hardware-ID, but varying DUIDs, since it allows dnsmasq to honour the static address allocation but assign a different adddress for each DUID. This typically occurs when chain netbooting, as each stage of the chain gets in turn allocates an address.
      • - -
    • For DHCPv4, the special option id:* means "ignore any client-id and use MAC addresses only." This is useful when a client presents a client-id sometimes but not others.
      • -
    • If a name appears in /etc/hosts, the associated address can be allocated to a DHCP lease, but only if a separate line specifying the name also exists. Only one hostname can be given per line, but aliases are possible by using CNAMEs. Note that /etc/hosts is NOT used when the DNS server side of dnsmasq is disabled by setting the DNS server port to zero.
      • -
    • More than one line can be associated (by name, hardware address or UID) with a host. Which one is used (and therefore which address is allocated by DHCP and appears in the DNS) depends on the subnet on which the host last obtained a DHCP lease: the line with an address within the subnet is used. If more than one address is within the subnet, the result is undefined. A corollary to this is that the name associated with a host defined here does not appear in the DNS until the host obtains a DHCP lease.
      • -
    • The special keyword ignore tells Pi-hole to never offer a DHCP lease to a machine. The machine can be specified by hardware address, client ID or hostname, for instance 00:20:e0:3b:13:af,ignore. This is useful when there is another DHCP server on the network which should be used by some machines.
      • -
    • The set:<tag> construct sets the tag whenever this line is in use. This can be used to selectively send DHCP options just for this host. More than one tag can be set per line directive (but not in other places where "set:<tag>" is allowed). When a host matches any directive (or one implied by /etc/ethers) then the special tag "known"" is set. This allows Pi-hole to be configured to ignore requests from unknown machines using a custom config option dhcp-ignore=tag:!known in your own config file. If the host matches only a directive which cannot be used because it specifies an address on different subnet, the tag "known-othernet" is set.
      • -
    • The tag:<tag> construct filters which directives are used; more than one can be provided, in this case the request must match all of them. Tagged directives are used in preference to untagged ones. Note that one of <hwaddr>;, <client_id>; or <hostname>; still needs to be specified (can be a wildcard).
      • -
    • Ethernet addresses (but not client-ids) may have wildcard bytes, so for example 00:20:e0:3b:13:*,ignore will cause Pi-hole to ignore a range of hardware addresses.
      • -
    • Hardware addresses normally match any network (ARP) type, but it is possible to restrict them to a single ARP type by preceding them with the ARP-type (in HEX) and "-". so the line 06-00:20:e0:3b:13:af,1.2.3.4 will only match a Token-Ring hardware address, since the ARP-address type for token ring is 6.
      • -
    • As a special case, in DHCPv4, it is possible to include more than one hardware address. eg: 11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2. This allows an IP address to be associated with multiple hardware addresses, and gives Pi-hole permission to abandon a DHCP lease to one of the hardware addresses when another one asks for a lease. Beware that this is a dangerous thing to do, it will only work reliably if only one of the hardware addresses is active at any time and there is no way for dnsmasq to enforce this. It is, for instance, useful to allocate a stable IP address to a laptop which has both wired and wireless interfaces.
      • -
    -
    -
    -
    -
    -
    -
    - -
    -
    -
    - -
    -
    - -
    -
    - -
    -
    - -
    - -
    -
    -
    - -
    -
    -
    -
    -
    -
    - - - - - - - - - -