Skip to content

Configuration

You can create a file /etc/pihole/pihole-FTL.conf that will be read by FTLDNS on startup.

Possible settings (the option shown first is the default):


DNS settings

BLOCKINGMODE=NULL|IP-NODATA-AAAA|IP|NXDOMAIN

How should FTL reply to blocked queries?
More details

CNAME_DEEP_INSPECT=true|false (PR #663)

Use this option to disable deep CNAME inspection. This might be beneficial for very low-end devices

BLOCK_ESNI=true|false (PR #733)

Encrypted Server Name Indication (ESNI) is certainly a good step into the right direction to enhance privacy on the web. It prevents on-path observers, including ISPs, coffee shop owners and firewalls, from intercepting the TLS Server Name Indication (SNI) extension by encrypting it. This prevents the SNI from being used to determine which websites users are visiting.

ESNI will obviously cause issues for pixelserv-tls which will be unable to generate matching certificates on-the-fly when it cannot read the SNI. Cloudflare and Firefox are already enabling ESNI. According to the IEFT draft (link above), we can easily restore piselserv-tls's operation by replying NXDOMAIN to _esni. subdomains of blocked domains as this mimics a "not configured for this domain" behavior.

EDNS0_ECS=true|false (PR #851)

Should we overwrite the query source when client information is provided through EDNS0 client subnet (ECS) information? This allows Pi-hole to obtain client IPs even if they are hidden behind the NAT of a router.

This feature has been requested and discussed on Discourse where further information how to use it can be found.

RATE_LIMIT=1000/60 (PR #1052)

Control FTL's query rate-limiting. Rate-limited queries are answered with a REFUSED reply and not further processed by FTL.

The default settings for FTL's rate-limiting are to permit no more than 1000 queries in 60 seconds. Both numbers can be customized independently. 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.

For this setting, both numbers, the maximum number of queries within a given time, and the length of the time interval (seconds) have to be specified. For instance, if you want to set a rate limit of 1 query per hour, the option should look like RATE_LIMIT=1/3600.

Rate-limiting may be disabled altogether by setting RATE_LIMIT=0/0 (this results in the same behavior as before FTL v5.7).

REPLY_ADDR4= (unset by default, PR #965)

FTL determines the address of the interface a query arrived on. We then use this IP address when replying to queries with an A record (IPv4 address). This setting can be used to ensure a fixed, rather than the dynamically obtained, address is used.

This applies to the following cases:

  • IP blocking mode is used and this query is to be blocked
  • A regular expression with the ;reply=IP regex extension is used
  • Pi-hole responds to one of the following names
    • pi.hole
    • <the device's hostname>
    • pi.hole.<local domain>
    • <the device's hostname>.<local domain>

REPLY_ADDR6= (unset by default, PR #965)

FTL determines the address of the interface a query arrived on. We then use this IP address when replying to queries with an AAAA record (IPv6 address). This setting can be used to ensure a fixed, rather than the dynamically obtained, address is used. See REPLY_ADDR4 for details about when this setting is used.

REPLY_WHEN_BUSY=ALLOW|DROP|BLOCK|REFUSE (PR #1156)

When the gravity database is locked/busy, how should Pi-hole handle queries?

  • ALLOW - allow all queries when the database is busy
  • BLOCK - block all queries when the database is busy. This uses the configured BLOCKINGMODE (default NULL)
  • REFUSE - refuse all queries which arrive while the database is busy
  • DROP - just drop the queries, i.e., never reply to them at all.

Despite REFUSE sounding similar to DROP, it turned out that many clients will just immediately retry, causing up to several thousands of queries per second. This does not happen in DROP mode.

MOZILLA_CANARY=true|false (PR #1148)

Should Pi-hole always replies with NXDOMAIN to A and AAAA queries of use-application-dns.net to disable Firefox automatic DNS-over-HTTP? This is following the recommendation on https://support.mozilla.org/en-US/kb/configuring-networks-disable-dns-over-https

BLOCK_TTL=2 (PR #1173)

FTL's internal TTL to be handed out for blocked queries. This settings allows users to select a value different from the dnsmasq config option local-ttl. This seems useful in context of locally used hostnames that are known to stay constant over long times (printers, etc.).

Note that large values may render whitelisting ineffective due to client-side caching of blocked queries.

BLOCK_ICLOUD_PR=true|false (PR #1171)

Should Pi-hole always replies with NXDOMAIN to A and AAAA queries of mask.icloud.com and mask-h2.icloud.com to disable Apple's iCloud Private Relay to prevent Apple devices from bypassing Pi-hole? This is following the recommendation on https://developer.apple.com/support/prepare-your-network-for-icloud-private-relay


Statistics settings

MAXLOGAGE=24.0

Up to how many hours of queries should be imported from the database and logs? Values greater than the hard-coded maximum of 24h need a locally compiled FTL with a changed compile-time value.

PRIVACYLEVEL=0|1|2|3

Which privacy level is used?
More details

IGNORE_LOCALHOST=no|yes

Should FTL ignore queries coming from the local machine?

AAAA_QUERY_ANALYSIS=yes|no

Should FTL analyze AAAA queries? The DNS server will handle AAAA queries the same way, regardless of this setting. All this does is ignoring AAAA queries when computing the statistics of Pi-hole. This setting is considered obsolete and will be removed in a future version.

ANALYZE_ONLY_A_AND_AAAA=false|true

Should FTL only analyze A and AAAA queries?

SHOW_DNSSEC=true|false

Should FTL analyze and include automatically generated DNSSEC queries in the Query Log?


Other settings

SOCKET_LISTENING=localonly|all

Listen only for local socket connections or permit all connections

FTLPORT=4711

On which port should FTL be listening?

RESOLVE_IPV6=yes|no

Should FTL try to resolve IPv6 addresses to hostnames?

RESOLVE_IPV4=yes|no

Should FTL try to resolve IPv4 addresses to hostnames?

PIHOLE_PTR=PI.HOLE|HOSTNAME|NONE (PR #1111, #1164)

Controls whether and how FTL will reply with for address for which a local interface exists. Valid options are:

  • PI.HOLE (the default) respond with pi.hole
  • HOSTNAME serve the machine's global hostname
  • HOSTNAMEFQDN serve the machine's global hostname as fully qualified domain by adding the local suffix. See note below.
  • NONE Pi-hole will not respond automatically on PTR requests to local interface addresses. Ensure pi.hole and/or hostname records exist elsewhere.

Note about HOSTNAMEFQDN: If no local suffix has been defined, FTL appends the local domain .no_fqdn_available. In this case you should either add domain=whatever.com to a custom config file inside /etc/dnsmasq.d/ (to set whatever.com as local domain) or use domain=# which will try to derive the local domain from /etc/resolv.conf (or whatever is set with resolv-file, when multiple search directives exist, the first one is used).

DELAY_STARTUP=0 (PR #716)

In certain configurations, you may want FTL to wait a given amount of time before trying to start the DNS revolver. This is typically found when network interfaces appear only late during system startup and the interface startup priorities are configured incorrectly. This setting takes any integer value between 0 and 300 seconds.

NICE=-10 (PR #798)

Can be used to change the niceness of Pi-hole FTL. Defaults to -10 and can be disabled altogether by setting a value of -999.

The nice value is an attribute that can be used to influence the CPU scheduler to favor or disfavor a process in scheduling decisions. The range of the nice value varies across UNIX systems. On modern Linux, the range is -20 (high priority = not very nice to other processes) to +19 (low priority).

MAXNETAGE=[MAXDBDAYS] (PR #871)

IP addresses (and associated host names) older than the specified number of days are removed to avoid dead entries in the network overview table. This setting defaults to the same value as MAXDBDAYS above but can be changed independently if needed.

NAMES_FROM_NETDB=true|false (PR #784)

Control whether FTL should use the fallback option to try to obtain client names from checking the network table. This behavior can be disabled with this option

Assume an IPv6 client without a host names. However, the network table knows - though the client's MAC address - that this is the same device where we have a 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|UNKNOWN|NONE (PR #953)

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:

  • REFRESH_HOSTNAMES=IPV4 - Do the hourly PTR lookups only for IPv4 addresses 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 refreshed, 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.

PARSE_ARP_CACHE=true|false (PR #445)

This setting can be used to disable ARP cache processing. When disabled, client identification and the network table will stop working reliably.


Long-term database settings

Further details concerning the database

DBIMPORT=yes|no

Should FTL load information from the database on startup to be aware of the most recent history?

MAXDBDAYS=365

How long should queries be stored in the database? Setting this to 0 disables the database

DBINTERVAL=1.0

How often do we store queries in FTL's database [minutes]?

DBFILE=/etc/pihole/pihole-FTL.db

Specify the path and filename of FTL's SQLite3 long-term database. Setting this to DBFILE= disables the database altogether


File options

LOGFILE=/var/log/pihole-FTL.log

The location of FTL's log file. If you want to move the log file to a different place, also consider this FAQ article.

PIDFILE=/run/pihole-FTL.pid

The file which contains the PID of FTL's main process.

PORTFILE=/run/pihole-FTL.port

The file containing the port FTL's API is listening on.

SOCKETFILE=/run/pihole/FTL.sock

The file containing the socket FTL's API is listening on.

SETUPVARSFILE=/etc/pihole/setupVars.conf

The config file of Pi-hole containing, e.g., the current blocking status (do not change).

MACVENDORDB=/etc/pihole/macvendor.db

The database containing MAC -> Vendor information for the network table.

GRAVITYDB=/etc/pihole/gravity.db

Specify path and filename of FTL's SQLite3 gravity database. This database contains all domains relevant for Pi-hole's DNS blocking


Debugging options

DEBUG_ALL=false|true

Enable all debug flags. If this is set to true, all other debug config options are ignored.

DEBUG_DATABASE=false|true

Print debugging information about database actions. This prints performed SQL statements as well as some general information such as the time it took to store the queries and how many have been saved to the database.

DEBUG_NETWORKING=false|true

Prints a list of the detected interfaces on the startup of pihole-FTL. Also, prints whether these interfaces are IPv4 or IPv6 interfaces.

DEBUG_EDNS0=false|true

Print debugging information about received EDNS(0) data.

DEBUG_LOCKS=false|true

Print information about shared memory locks. Messages will be generated when waiting, obtaining, and releasing a lock.

DEBUG_QUERIES=false|true

Print extensive query information (domains, types, replies, etc.). This has always been part of the legacy debug mode of pihole-FTL.

DEBUG_FLAGS=false|true

Print flags of queries received by the DNS hooks. Only effective when DEBUG_QUERIES is enabled as well.

DEBUG_SHMEM=false|true

Print information about shared memory buffers. Messages are either about creating or enlarging shmem objects or string injections.

DEBUG_GC=false|true

Print information about garbage collection (GC): What is to be removed, how many have been removed and how long did GC take.

DEBUG_ARP=false|true

Print information about ARP table processing: How long did parsing take, whether read MAC addresses are valid, and if the macvendor.db file exists.

DEBUG_REGEX=false|true

Controls if FTLDNS should print extended details about regex matching into pihole-FTL.log.

More details

DEBUG_API=false|true

Print extra debugging information during telnet API calls. Currently only used to send extra information when getting all queries.

DEBUG_OVERTIME=false|true

Print information about overTime memory operations, such as initializing or moving overTime slots.

DEBUG_STATUS=false|true

Print information about status changes for individual queries. This can be useful to identify unexpected unknown queries.

DEBUG_CAPS=false|true

Print information about capabilities granted to the pihole-FTL process. The current capabilities are printed on receipt of SIGHUP, i.e., the current set of capabilities can be queried without restarting pihole-FTL (by setting DEBUG_CAPS=true and thereafter sending killall -HUP pihole-FTL).

DEBUG_DNSMASQ_LINES=false|true

Print file and line causing a dnsmasq event into FTL's log files. This is handy to implement additional hooks missing from FTL.

DEBUG_VECTORS=false|true (PR #725)

FTL uses dynamically allocated vectors for various tasks. This config option enables extensive debugging information such as information about allocation, referencing, deletion, and appending.

DEBUG_RESOLVER=false|true (PR #728)

Extensive information about hostname resolution like which DNS servers are used in the first and second hostname resolving tries (only affecting internally generated PTR queries).

DEBUG_EDNS0=false|true (PR #851)

Verbose logging during EDNS(0) header analysis.

DEBUG_CLIENTS=false|true (PR #762)

Log various important client events such as change of interface (e.g., client switching from WiFi to wired or VPN connection), as well as extensive reporting about how clients were assigned to its groups.

DEBUG_ALIASCLIENTS=false|true (PR #880)

Log information related to alias-client processing.

DEBUG_EVENTS=false|true (PR #881)

Log information regarding FTL's embedded event handling queue.

DEBUG_HELPER=false|true (PR #914)

Log information about script helpers, e.g., due to dhcp-script.

ADDR2LINE=true|false (PR #774)

Should FTL translate its own stack addresses into code lines during the bug backtrace? This improves the analysis of crashed significantly. It is recommended to leave the option enabled. This option should only be disabled when addr2line is known to not be working correctly on the machine because, in this case, the malfunctioning addr2line can prevent from generating any backtrace at all.

DEBUG_EXTRA=false|true (PR #994)

Temporary flag that may print additional information. This debug flag is meant to be used whenever needed for temporary investigations. The logged content may change without further notice at any time.


Last update: October 26, 2021
Back to top