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

Statistics settings

MAXLOGAGE=24.0

Up to how many hours of queries should be imported from the database and logs? Maximum is 24.0


PRIVACYLEVEL=0|1|2|3|4

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

Allow FTL to analyze AAAA queries from pihole.log?


ANALYZE_ONLY_A_AND_AAAA=false|true

Should FTL only analyze A and AAAA queries?

Socket settings

SOCKET_LISTENING=localonly|all

Listen only for local socket connections or permit all connections


FTLPORT=4711

On which port should FTL be listening?

Host name resolution

RESOLVE_IPV6=yes|no

Should FTL try to resolve IPv6 addresses to host names?


RESOLVE_IPV4=yes|no

Should FTL try to resolve IPv4 addresses to host names?

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 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

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

PIDFILE=/var/run/pihole-FTL.pid

File which contains the PID of FTL's main process.

PORTFILE=/var/run/pihole-FTL.port

File containing the port FTL's API is listening on.

SOCKETFILE=/var/run/pihole/FTL.sock

File containing the socket FTL's API is listening on.

SETUPVARSFILE=/etc/pihole/setupVars.conf

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

AUDITLISTFILE=/etc/pihole/auditlog.list

List containing the audited domains.

MACVENDORDB=/etc/pihole/macvendor.db

Database containing MAC -> Vendor information for the network table.

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 startup of pihole-FTL. Also prints whether these interfaces are IPv4 or IPv6 interfaces.


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.
Due to legacy reasons, we also support the following setting to be used for enabling the same functionality:
REGEX_DEBUGMODE=false|true Note that if one of them is set to true, the other one cannot be used to disable this setting again.
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_EXTBLOCKED=false|true

Print information about why FTL decided that certain queries were recognized as being externally blocked.


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).