Pi-hole stats can be accessed via a standard Unix socket (
var/run/pihole/FTL.sock), a telnet-like connection (TCP socket on port
4711) as well as indirectly via the Web API (
admin/api.php), and command line (
pihole -c -j). You can out find more details below.
Command line arguments¶
debug- Don't go into daemon mode (stay in foreground) + more verbose logging
FTLand process everything, but shut down immediately afterwards
version- Don't start
FTL, show only version
tag- Don't start
FTL, show only git tag
branch- Don't start
FTL, show only git branch
FTLwas compiled from
-f- Don't go into background (daemon mode)
-h- Don't start
FTL, show help
dnsmasq-test- Test resolver config file syntax
--will be passed as options to the internal resolver
Command line arguments can be arbitrarily combined, e.g.
pihole-FTL debug test
/var/run/pihole-FTL.portfile containing port on which
Domain lists format¶
Since Pi-hole v4.0, we use a simpler domain list format for the two important block list files
black.list. In contrast to the traditional HOSTS format (which caused a lot of overhead), the domain list format is the minimal possible solution for saving memory while still using plain text lists for your convenience. When FTLDNS imports these two files, they are walked by our improved list parser speeding up the loading of block lists significantly. Regardless which blocking mode (
NXDOMAIN) is selected, FTLDNS will always load the lists into its internal hashed cache to be able to determine the blocking status within a few milliseconds, even when you're using huge blocking lists on low-end devices. With everything we do, we design FTLDNS for maximum efficiency also on low-performance devices.
Capabilities (POSIX 1003.1e, capabilities(7)) provide fine-grained control over superuser permissions, allowing use of the
root user to be avoided.
For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: privileged processes (superuser or
root), and unprivileged processes. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and group permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes (xattr(7)) in the
security namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and ReiserFS.
For your safety and comfort,
pihole-FTL is run by the entirely unprivileged user
dnsmasq is running as
root process, we designed
pihole-FTL to be run by the entirely unprivileged user
pihole. As a consequence,
pihole-FTL will not be able to access the files of any other user on this system or mess around with your system's configuration.
However, this also implies that FTLDNS cannot bind to ports 53 (DNS) among some other necessary capabilities related to DHCP services. To establish a strong security model, we explicitly grant the
pihole-FTL process additional capabilities so that
pihole-FTL (but no other processes which may be started by
pihole) can bind to port 53, etc., without giving any additional permissions to the
We specifically add the following capabilities to
CAP_NET_BIND_SERVICE: Allows FTLDNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53)
CAP_NET_RAW: use raw and packet sockets (we need a RAW socket for handling DHCPv6 requests)
CAP_NET_ADMIN: modify routing tables and other network-related operations (to allow for handling DHCP requests)
Users that cannot use Linux capabilites for various reasons (lacking kernel or file system support) can modify the startup scripts of
pihole-FTL to ensure the daemon is started as
root. However, be aware of that you do so on your own risk (although we don't expect problems to arise).