pi-hole/manpages/pihole-FTL.conf.5

.TH "pihole-FTL.conf" "5" "pihole-FTL.conf" "pihole-FTL.conf" "November 2020"
.SH "NAME"

pihole-FTL.conf - FTL's config file
.br
.SH "DESCRIPTION"

/etc/pihole/pihole-FTL.conf will be read by \fBpihole-FTL(8)\fR on startup.
.br
For each setting the option shown first is the default.
.br

\fBBLOCKINGMODE=IP|IP-AAAA-NODATA|NODATA|NXDOMAIN|NULL\fR
.br
    How should FTL reply to blocked queries?

    IP             - Pi-hole's IPs for blocked domains

    IP-AAAA-NODATA - Pi-hole's IP + NODATA-IPv6 for blocked domains

    NODATA         - Using NODATA for blocked domains

    NXDOMAIN       - NXDOMAIN for blocked domains

    NULL           - Null IPs for blocked domains
.br

\fBCNAME_DEEP_INSPECT=true|false\fR
.br
    Use this option to disable deep CNAME inspection. This might be beneficial for very low-end devices.
.br

\fBBLOCK_ESNI=true|false\fR
.br
    Block requests to _esni.* sub-domains.
.br

\fBMAXLOGAGE=24.0\fR
.br
    Up to how many hours of queries should be imported from the database and logs?
.br
    Maximum is 744 (31 days)
.br

\fBPRIVACYLEVEL=0|1|2|3|4\fR
.br
    Privacy level used to collect Pi-hole statistics.
.br
    0 - show everything
.br
    1 - hide domains
.br
    2 - hide domains and clients
.br
    3 - anonymous mode (hide everything)
.br
    4 - disable all statistics
.br

\fBIGNORE_LOCALHOST=no|yes\fR
.br
    Should FTL ignore queries coming from the local machine?
.br

\fBAAAA_QUERY_ANALYSIS=yes|no\fR
.br
    Should FTL analyze AAAA queries?
.br

\fBANALYZE_ONLY_A_AND_AAAA=false|true\fR
.br
    Should FTL only analyze A and AAAA queries?
.br

\fBSOCKET_LISTENING=localonly|all\fR
.br
    Listen only for local socket connections on the API port or permit all connections.
.br

\fBFTLPORT=4711\fR
.br
    On which port should FTL be listening?
.br

\fBRESOLVE_IPV6=yes|no\fR
.br
    Should FTL try to resolve IPv6 addresses to hostnames?
.br

\fBRESOLVE_IPV4=yes|no\fR
.br
    Should FTL try to resolve IPv4 addresses to hostnames?
.br

\fBDELAY_STARTUP=0\fR
.br
    Time in seconds (between 0 and 300) to delay FTL startup.
.br

\fBNICE=-10\fR
.br
    Set the niceness of the Pi-hole FTL process.
.br
    Can be disabled altogether by setting a value of -999.
.br

\fBNAMES_FROM_NETDB=true|false\fR
.br
    Control whether FTL should use a fallback option and try to obtain client names from checking the network table.
.br
    E.g. IPv6 clients without a hostname will be compared via MAC address to known clients.
.br

\fB\fBREFRESH_HOSTNAMES=IPV4|ALL|NONE\fR
.br
    Change how (and if) hourly PTR requests are made to check for changes in client and upstream server hostnames:
.br
    IPV4 - Do the hourly PTR lookups only for IPv4 addresses resolving issues in networks with many short-lived PE IPv6 addresses.
.br
    ALL  - Do the hourly PTR lookups for all addresses. This can create a lot of PTR queries in networks with many IPv6 addresses.
.br
    NONE - Don't do hourly PTR lookups. Look up hostnames once (when first seeing a client) and never again. Future hostname changes may be missed.
.br

\fBMAXNETAGE=365\fR
.br
    IP addresses (and associated host names) older than the specified number of days are removed.
.br
    This avoids dead entries in the network overview table.
.br

\fBEDNS0_ECS=true|false\fR
.br
    Should we overwrite the query source when client information is provided through EDNS0 client subnet (ECS) information?
.br

\fBPARSE_ARP_CACHE=true|false\fR
.br
    Parse ARP cache to fill network overview table.
.br

\fBDBIMPORT=yes|no\fR
.br
    Should FTL load information from the database on startup to be aware of the most recent history?
.br

\fBMAXDBDAYS=365\fR
.br
    How long should queries be stored in the database? Setting this to 0 disables the database
.br

\fBDBINTERVAL=1.0\fR
.br
    How often do we store queries in FTL's database [minutes]?
.br
    Accepts value between 0.1 (6 sec) and 1440 (1 day)
.br

\fBDBFILE=/etc/pihole/pihole-FTL.db\fR
.br
    Specify path and filename of FTL's SQLite long-term database.
.br
    Setting this to DBFILE= disables the database altogether
.br

\fBLOGFILE=/var/log/pihole-FTL.log\fR
.br
    The location of FTL's log file.
.br

\fBPIDFILE=/run/pihole-FTL.pid\fR
.br
    The file which contains the PID of FTL's main process.
.br

\fBPORTFILE=/run/pihole-FTL.port\fR
.br
    Specify path and filename where the FTL process will write its API port number.
.br

\fBSOCKETFILE=/run/pihole/FTL.sock\fR
.br
    The file containing the socket FTL's API is listening on.
.br

\fBSETUPVARSFILE=/etc/pihole/setupVars.conf\fR
.br
    The config file of Pi-hole containing, e.g., the current blocking status (do not change).
.br

\fBMACVENDORDB=/etc/pihole/macvendor.db\fR
.br
    The database containing MAC -> Vendor information for the network table.
.br

\fBGRAVITYDB=/etc/pihole/gravity.db\fR
.br
    Specify path and filename of FTL's SQLite3 gravity database. This database contains all domains relevant for Pi-hole's DNS blocking.
.br

\fBDEBUG_ALL=false|true\fR
.br
    Enable all debug flags. If this is set to true, all other debug config options are ignored.
.br

\fBDEBUG_DATABASE=false|true\fR
.br
    Print debugging information about database actions such as SQL statements and performance.
.br

\fBDEBUG_NETWORKING=false|true\fR
.br
    Prints a list of the detected network interfaces on the startup of FTL.
.br

\fBDEBUG_LOCKS=false|true\fR
.br
    Print information about shared memory locks.
.br
    Messages will be generated when waiting, obtaining, and releasing a lock.
.br

\fBDEBUG_QUERIES=false|true\fR
.br
    Print extensive DNS query information (domains, types, replies, etc.).
.br

\fBDEBUG_FLAGS=false|true\fR
.br
    Print flags of queries received by the DNS hooks.
.br
    Only effective when \fBDEBUG_QUERIES\fR is enabled as well.

\fBDEBUG_SHMEM=false|true\fR
.br
    Print information about shared memory buffers.
.br
    Messages are either about creating or enlarging shmem objects or string injections.
.br

\fBDEBUG_GC=false|true\fR
.br
    Print information about garbage collection (GC):
.br
    What is to be removed, how many have been removed and how long did GC take.
.br

\fBDEBUG_ARP=false|true\fR
.br
    Print information about ARP table processing:
.br
    How long did parsing take, whether read MAC addresses are valid, and if the macvendor.db file exists.
.br

\fBDEBUG_REGEX=false|true\fR
.br
    Controls if FTL should print extended details about regex matching.
.br

\fBDEBUG_API=false|true\fR
.br
    Print extra debugging information during telnet API calls.
.br
    Currently only used to send extra information when getting all queries.
.br

\fBDEBUG_OVERTIME=false|true\fR
.br
    Print information about overTime memory operations, such as initializing or moving overTime slots.
.br

\fBDEBUG_EXTBLOCKED=false|true\fR
.br
    Print information about why FTL decided that certain queries were recognized as being externally blocked.
.br

\fBDEBUG_CAPS=false|true\fR
.br
    Print information about POSIX capabilities granted to the FTL process.
.br
    The current capabilities are printed on receipt of SIGHUP i.e. after executing `killall -HUP pihole-FTL`.
.br

\fBDEBUG_DNSMASQ_LINES=false|true\fR
.br
    Print file and line causing a dnsmasq event into FTL's log files.
.br
    This is handy to implement additional hooks missing from FTL.
.br

\fBDEBUG_VECTORS=false|true\fR
.br
    FTL uses dynamically allocated vectors for various tasks.
.br
    This config option enables extensive debugging information such as information about allocation, referencing, deletion, and appending.
.br

\fBDEBUG_RESOLVER=false|true\fR
.br
    Extensive information about hostname resolution like which DNS servers are used in the first and second hostname resolving tries.
.br

.SH "SEE ALSO"

\fBpihole\fR(8), \fBpihole-FTL\fR(8)
.br
.SH "COLOPHON"

Pi-hole : The Faster-Than-Light (FTL) Engine is a lightweight, purpose-built daemon used to provide statistics needed for the Pi-hole Web Interface, and its API can be easily integrated into your own projects. Although it is an optional component of the Pi-hole ecosystem, it will be installed by default to provide statistics. As the name implies, FTL does its work \fIvery quickly\fR!
.br

Get sucked into the latest news and community activity by entering Pi-hole's orbit. Information about Pi-hole, and the latest version of the software can be found at https://pi-hole.net
.br