How to use the command 'pihole' (with examples)

The ‘pihole’ command is a terminal interface for the Pi-hole ad-blocking DNS server. It allows users to manage and monitor the Pi-hole server directly from the command line. This article will walk through several useful use cases of the ‘pihole’ command and provide examples of each.

Use case 1: Check the Pi-hole daemon’s status

Code:

pihole status

Motivation: Checking the Pi-hole daemon’s status is essential for troubleshooting and monitoring the server’s health. It provides information on whether the daemon is running properly or encountering any issues.

Explanation: The ‘status’ argument is used with the ‘pihole’ command to check the Pi-hole daemon’s status. It provides information on whether the Pi-hole daemon is running or not.

Example output:

[✓] Daemon is running

Use case 2: Update Pi-hole and Gravity

Code:

pihole -up

Motivation: Regularly updating Pi-hole and its gravity list is crucial to ensure optimal ad-blocking and security. This use case allows users to easily update Pi-hole and its gravity list.

Explanation: The ‘-up’ argument is used with the ‘pihole’ command to update Pi-hole and its gravity list. It fetches the latest updates and applies them to the Pi-hole server.

Example output:

[i] Pi-hole version is up to date (Core: x.x.x)
[i] Everything is up to date

Use case 3: Monitor detailed system status

Code:

pihole chronometer

Motivation: Monitoring the detailed system status of Pi-hole provides valuable insights into the server’s performance, including DNS queries, blocked queries, and more. It helps in identifying any unusual activity or potential issues.

Explanation: The ‘chronometer’ argument is used with the ‘pihole’ command to monitor the detailed system status of Pi-hole. It displays real-time statistics of DNS queries, blocked queries, and other relevant information.

Example output:

Pi-hole chronometer
-------------------

Query types:
------------

Queries answered by Blacklist: 12345
Queries answered by Pi-hole: 56789
...

Top Domains:
------------

google.com: 1234
facebook.com: 567
...

Top Advertisers:
----------------

advertiser1.com: 1234
advertiser2.com: 567
...

Use case 4: Start or stop the daemon

Code:

pihole enable    # Start the daemon
pihole disable   # Stop the daemon

Motivation: Starting or stopping the Pi-hole daemon is necessary when actively using or temporarily disabling the ad-blocking functionality. This use case allows users to easily control the daemon.

Explanation: The ’enable’ and ‘disable’ arguments are used with the ‘pihole’ command to start or stop the Pi-hole daemon, respectively. Starting the daemon enables ad-blocking, while stopping it disables the ad-blocking functionality.

Example output (for ’enable’):

[✓] Blocking Enabled

Example output (for ‘disable’):

[✗] Blocking Disabled

Use case 5: Restart the daemon (not the server itself)

Code:

pihole restartdns

Motivation: Restarting the Pi-hole daemon is sometimes required to apply changes or troubleshoot issues related to DNS resolution. This use case allows users to restart the daemon without restarting the entire server.

Explanation: The ‘restartdns’ argument is used with the ‘pihole’ command to restart the Pi-hole daemon, specifically resetting the DNS resolution. It helps apply changes and resolve potential DNS-related issues.

Example output:

[✓] Pi-hole DNS service is running
[✓] Pi-hole blocking is Enabled

Use case 6: Whitelist or blacklist a domain

Code:

pihole whitelist example.com    # Whitelist a domain
pihole blacklist example.com    # Blacklist a domain

Motivation: Whitelisting or blacklisting domains is necessary for allowing or blocking specific websites or ad servers on the Pi-hole server. This use case helps in customizing the ad-blocking behavior as per user preferences.

Explanation: The ‘whitelist’ and ‘blacklist’ arguments are used with the ‘pihole’ command to respectively whitelist or blacklist a domain on the Pi-hole server. Whitelisting allows ads to be displayed from a specific domain, while blacklisting blocks all ads from the designated domain.

Example output (for ‘whitelist’):

[i] The domain example.com was added to the whitelist

Example output (for ‘blacklist’):

[i] The domain example.com was added to the blacklist

Use case 7: Search the lists for a domain

Code:

pihole query example.com

Motivation: Searching the lists for a specific domain helps users identify whether it is blocked or allowed on the Pi-hole server. This use case provides information about a domain’s inclusion in the ad-blocking lists.

Explanation: The ‘query’ argument is used with the ‘pihole’ command to search the lists for a domain on the Pi-hole server. It returns information about the domain’s status in the ad-blocking lists.

Example output:

[✓] example.com is not blocked

Use case 8: Open a real-time log of connections

Code:

pihole tail

Motivation: Opening a real-time log of connections allows users to monitor the DNS queries and connections made through the Pi-hole server. It helps in identifying any suspicious or unwanted requests.

Explanation: The ’tail’ argument is used with the ‘pihole’ command to open a real-time log of connections on the Pi-hole server. It displays the latest DNS queries and connections in real-time.

Example output:

[2021-10-01 12:34:56]  12345: example1.com
[2021-10-01 12:34:57]  67890: example2.com
...

Conclusion:

The ‘pihole’ command provides a convenient way to manage and monitor the Pi-hole ad-blocking DNS server from the command line. The various use cases covered in this article showcase the versatility of the command, allowing users to check the daemon’s status, update Pi-hole, monitor system status, start or stop the daemon, restart the daemon, whitelist or blacklist domains, search the lists for a domain, and open a real-time log of connections. With these examples, users can effectively utilize the ‘pihole’ command to control and optimize their Pi-hole server.