LinuxCommandLibrary

pihole

Manage Pi-hole DNS ad-blocking system

TLDR

Check Pi-hole's status

$ pihole status
copy

Update Pi-hole and Gravity
$ sudo pihole [[-up|updatePihole]]
copy

Start or stop the daemon
$ pihole [enable|disable]
copy

Update the lists and flush the cache without restarting the DNS server
$ pihole reloaddns
copy

Update the list of ad-serving domains
$ pihole [[-g|updateGravity]]
copy

Allow or deny the specified domain
$ pihole [allow|deny] [example.com]
copy

Search the lists for a domain
$ pihole [[-q|query]] [example.com]
copy

Open a real-time log of connections
$ pihole [[-t|tail]]
copy

SYNOPSIS

pihole [<global-options>] <command> [<command-arguments>]

PARAMETERS

-h, --help
    Displays help information for the main command or a specific subcommand.

-v, --version
    Shows the installed versions of Pi-hole core, web interface, and FTL components.

-d, --debug
    Initiates a Pi-hole debug session, collecting diagnostic information for troubleshooting.

status
    Shows the current operational status of the Pi-hole DNS blocker.

enable
    Activates Pi-hole's DNS blocking functionality.

disable [<time>]
    Deactivates Pi-hole's DNS blocking. An optional time (e.g., "10s", "5m", "2h") can be provided for temporary disabling.

whitelist <domain> [<comment>]
    Adds domains to the whitelist, allowing them to bypass Pi-hole's blocking. Use --del to remove.

blacklist <domain> [<comment>]
    Adds domains to the blacklist, ensuring they are blocked by Pi-hole. Use --del to remove.

updateGravity
    Downloads and updates the core ad-blocking lists (gravity database) from configured sources. This is a critical step for effective blocking.

restartdns
    Restarts the Pi-hole DNS resolver service (FTL).

flush [<options>]
    Clears Pi-hole's DNS cache (dns) or its query logs (logs), or both (all).

tail
    Displays the real-time stream of the Pi-hole FTL DNS query log.

updatePihole
    Updates the Pi-hole core software, web interface, and FTL components to their latest versions.

uninstall
    Removes the Pi-hole software from the system.

DESCRIPTION

Pi-hole is a popular, open-source Linux network-level advertisement and Internet tracker blocking application. It functions as a DNS sinkhole, intercepting DNS requests and blocking unwanted content for all devices connected to a network that uses Pi-hole as its DNS server.

The pihole command is the primary command-line interface for managing and interacting with your Pi-hole instance. It allows administrators to perform various tasks such as enabling or disabling blocking, adding domains to whitelist or blacklist, updating ad lists, viewing operational status, checking DNS query logs, and performing system-level updates for the Pi-hole software itself. This command consolidates many administrative functions, making it easy to control your network-wide ad blocking solution.

CAVEATS

The pihole command typically requires elevated privileges (sudo) for most operations as it interacts with system services and network configurations. It is designed to manage an already installed Pi-hole system and will not function without a prior installation. Incorrect usage, particularly with commands like updateGravity or flush, can temporarily disrupt network connectivity if the DNS service is affected. Being a network-level tool, its effectiveness depends on client devices on the network being configured to use Pi-hole as their DNS server.

WEB INTERFACE

Many of the administrative functions available via the pihole command-line tool can also be managed through Pi-hole's intuitive web interface, typically accessible at http://<Pi-hole-IP>/admin from a web browser on your network.

INSTALLATION

The pihole command itself is part of the Pi-hole software suite, which is commonly installed via a single command executed on a compatible Linux system: curl -sSL https://install.pi-hole.net | bash. This script handles all necessary dependencies and initial configuration.

HISTORY

Pi-hole was created by Jacob Salmela in 2015 as an open-source project designed to block ads on the network level. It quickly gained popularity as an effective, low-resource solution for ad-blocking across an entire network, often leveraging inexpensive hardware like the Raspberry Pi. The project has since grown into a robust, community-maintained ecosystem, with continuous development and feature additions, making it a widely adopted tool for network-wide ad and tracker blocking.

SEE ALSO

dnsmasq(8), systemctl(1), dig(1), nslookup(1)

Copied to clipboard