2020-12-10 21:58:07 +00:00
.TH "pihole-FTL.conf" "5" "pihole-FTL.conf" "pihole-FTL.conf" "November 2020"
2018-06-03 12:15:26 +00:00
.SH "NAME"
pihole-FTL.conf - FTL's config file
.br
.SH "DESCRIPTION"
/etc/pihole/pihole-FTL.conf will be read by \fB pihole-FTL(8)\fR on startup.
.br
2020-12-10 21:58:07 +00:00
For each setting the option shown first is the default.
.br
2018-06-03 12:15:26 +00:00
2020-12-10 21:58:07 +00:00
\fB BLOCKINGMODE=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
\fB CNAME_DEEP_INSPECT=true|false\fR
.br
Use this option to disable deep CNAME inspection. This might be beneficial for very low-end devices.
.br
\fB BLOCK_ESNI=true|false\fR
.br
Block requests to _esni.* sub-domains.
.br
\fB MAXLOGAGE=24.0\fR
.br
Up to how many hours of queries should be imported from the database and logs?
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
Maximum is 744 (31 days)
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB PRIVACYLEVEL=0|1|2|3|4\fR
.br
Privacy level used to collect Pi-hole statistics.
.br
0 - show everything
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
1 - hide domains
.br
2 - hide domains and clients
.br
3 - anonymous mode (hide everything)
.br
4 - disable all statistics
.br
\fB IGNORE_LOCALHOST=no|yes\fR
.br
Should FTL ignore queries coming from the local machine?
2018-06-03 12:15:26 +00:00
.br
2018-06-03 23:54:53 +00:00
\fB AAAA_QUERY_ANALYSIS=yes|no\fR
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
Should FTL analyze AAAA queries?
.br
\fB ANALYZE_ONLY_A_AND_AAAA=false|true\fR
.br
Should FTL only analyze A and AAAA queries?
.br
\fB SOCKET_LISTENING=localonly|all\fR
.br
Listen only for local socket connections on the API port or permit all connections.
.br
\fB FTLPORT=4711\fR
.br
On which port should FTL be listening?
2018-06-03 12:15:26 +00:00
.br
2018-06-03 23:54:53 +00:00
\fB RESOLVE_IPV6=yes|no\fR
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
Should FTL try to resolve IPv6 addresses to hostnames?
2018-06-03 12:15:26 +00:00
.br
2018-06-03 23:54:53 +00:00
\fB RESOLVE_IPV4=yes|no\fR
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
Should FTL try to resolve IPv4 addresses to hostnames?
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB DELAY_STARTUP=0\fR
.br
Time in seconds (between 0 and 300) to delay FTL startup.
.br
\fB NICE=-10\fR
.br
Set the niceness of the Pi-hole FTL process.
.br
Can be disabled altogether by setting a value of -999.
.br
\fB NAMES_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 \fB REFRESH_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
\fB MAXNETAGE=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
\fB EDNS0_ECS=true|false\fR
.br
Should we overwrite the query source when client information is provided through EDNS0 client subnet (ECS) information?
.br
\fB PARSE_ARP_CACHE=true|false\fR
.br
Parse ARP cache to fill network overview table.
.br
\fB DBIMPORT=yes|no\fR
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
Should FTL load information from the database on startup to be aware of the most recent history?
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB MAXDBDAYS=365\fR
.br
How long should queries be stored in the database? Setting this to 0 disables the database
2018-06-03 12:15:26 +00:00
.br
2018-06-03 23:54:53 +00:00
\fB DBINTERVAL=1.0\fR
2018-06-03 12:15:26 +00:00
.br
How often do we store queries in FTL's database [minutes]?
.br
2020-12-10 21:58:07 +00:00
Accepts value between 0.1 (6 sec) and 1440 (1 day)
.br
2018-06-03 12:15:26 +00:00
2018-06-03 23:54:53 +00:00
\fB DBFILE=/etc/pihole/pihole-FTL.db\fR
2018-06-03 12:15:26 +00:00
.br
Specify path and filename of FTL's SQLite long-term database.
.br
Setting this to DBFILE= disables the database altogether
.br
2020-12-10 21:58:07 +00:00
\fB LOGFILE=/var/log/pihole-FTL.log\fR
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
The location of FTL's log file.
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB PIDFILE=/run/pihole-FTL.pid\fR
.br
The file which contains the PID of FTL's main process.
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB PORTFILE=/run/pihole-FTL.port\fR
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
Specify path and filename where the FTL process will write its API port number.
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB SOCKETFILE=/run/pihole/FTL.sock\fR
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
The file containing the socket FTL's API is listening on.
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB SETUPVARSFILE=/etc/pihole/setupVars.conf\fR
2018-06-05 00:25:51 +00:00
.br
2020-12-10 21:58:07 +00:00
The config file of Pi-hole containing, e.g., the current blocking status (do not change).
2018-06-05 00:25:51 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB MACVENDORDB=/etc/pihole/macvendor.db\fR
2018-06-05 00:25:51 +00:00
.br
2020-12-10 21:58:07 +00:00
The database containing MAC -> Vendor information for the network table.
2018-12-10 15:18:25 +00:00
.br
2018-06-03 23:54:53 +00:00
2020-12-10 21:58:07 +00:00
\fB GRAVITYDB=/etc/pihole/gravity.db\fR
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
Specify path and filename of FTL's SQLite3 gravity database. This database contains all domains relevant for Pi-hole's DNS blocking.
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB DEBUG_ALL=false|true\fR
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
Enable all debug flags. If this is set to true, all other debug config options are ignored.
.br
\fB DEBUG_DATABASE=false|true\fR
.br
Print debugging information about database actions such as SQL statements and performance.
.br
\fB DEBUG_NETWORKING=false|true\fR
.br
Prints a list of the detected network interfaces on the startup of FTL.
2018-06-03 23:54:53 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB DEBUG_LOCKS=false|true\fR
.br
Print information about shared memory locks.
.br
Messages will be generated when waiting, obtaining, and releasing a lock.
.br
\fB DEBUG_QUERIES=false|true\fR
.br
Print extensive DNS query information (domains, types, replies, etc.).
.br
\fB DEBUG_FLAGS=false|true\fR
.br
Print flags of queries received by the DNS hooks.
.br
Only effective when \fB DEBUG_QUERIES\fR is enabled as well.
\fB DEBUG_SHMEM=false|true\fR
.br
Print information about shared memory buffers.
.br
Messages are either about creating or enlarging shmem objects or string injections.
2018-06-03 12:15:26 +00:00
.br
2020-12-10 21:58:07 +00:00
\fB DEBUG_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
\fB DEBUG_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
\fB DEBUG_REGEX=false|true\fR
.br
Controls if FTL should print extended details about regex matching.
.br
\fB DEBUG_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
\fB DEBUG_OVERTIME=false|true\fR
.br
Print information about overTime memory operations, such as initializing or moving overTime slots.
.br
\fB DEBUG_EXTBLOCKED=false|true\fR
.br
Print information about why FTL decided that certain queries were recognized as being externally blocked.
.br
\fB DEBUG_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
\fB DEBUG_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
\fB DEBUG_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
\fB DEBUG_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
2018-06-03 12:15:26 +00:00
.SH "SEE ALSO"
\fB pihole\fR (8), \fB pihole-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 \fI very 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