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

Pi-hole is a network-wide ad-blocking DNS server that is designed to be installed on a private network. It acts as a sinkhole, blocking advertisements from being downloaded, which can drastically improve network performance and user experience. The pihole command-line utility provides a comprehensive interface for managing and configuring Pi-hole functionalities. From updating the system to managing whitelists, the command makes controlling your network’s ad-blocking settings both intuitive and effective.

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

Code:

pihole status

Motivation:

It is crucial to routinely check the status of the Pi-hole daemon to ensure that it is running smoothly and efficiently blocking unwanted content. Regular status checks enable network administrators to swiftly identify and troubleshoot any issues in the DNS filtering process.

Explanation:

When you enter the pihole status command, no additional arguments are required. The command queries the current operational state of the Pi-hole daemon, reporting back whether the service is active and operational or if it has stopped and needs intervention.

Example Output:

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

Use case 2: Update Pi-hole and Gravity

Code:

pihole -up

Motivation:

Regular updates are essential to maintain the security and effectiveness of any software system. Updating Pi-hole ensures the system is protected with the latest security patches and performance enhancements. Additionally, updating Pi-hole’s Gravity list keeps the ad-blocking definitions current.

Explanation:

The -up flag in the pihole command instructs the system to update Pi-hole itself and its associated Gravity database. Gravity is a primary networking list that compiles known advertisement and tracking servers to be blocked by Pi-hole.

Example Output:

  [i] Checking for updates...
  [i] Pi-hole Core: update available
  [i] FTL: update available
  [✓] Everything is up-to-date!

Use case 3: Monitor detailed system status

Code:

pihole chronometer

Motivation:

For administrators who wish to monitor network performance in real-time, pihole chronometer offers a live dashboard displaying current system statistics. This feature is particularly useful for diagnosing performance issues or observing the effects of changes made to system settings.

Explanation:

The chronometer argument opens a dynamic interface displaying real-time data such as DNS queries, CPU load, memory usage, and network status. It does not require further arguments, instantly providing insights into system conditions and traffic flow.

Example Output:

  ---= pihole chronometer v2.0 =---
  [✓] Pi-hole blocking is enabled
  [i] Pi-hole Processes:
       - DNS: running
       - Blocking: enabled
  [i] Network:
       - IPv4: 192.168.1.5/24
       - IPv6: Not configured
  [i] Clients:
       - 15 clients served
  [i] Blocking:
       - Domains on Blocklist: 89,345
       - Queries Blocked: 120,456

Use case 4: Start or stop the daemon

Code:

pihole enable|disable

Motivation:

There are occasions when you’d need to temporarily disable ad-blocking—such as accessing certain websites that require ad interaction for full functionality, or during troubleshooting. Conversely, re-enabling blocking is crucial once those tasks are complete to maintain network security and performance.

Explanation:

The enable or disable flags control the activation state of the Pi-hole blocking services. Using enable activates the blocking functionality, while disable turns it off temporarily. Both commands are direct and do not require further input from the user.

Example Output (after disable):

  [i] Pi-hole blocking will be disabled for 5 minutes

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

Code:

pihole restartdns

Motivation:

Restarting the DNS service might become necessary following configuration changes or when the service becomes unresponsive. pihole restartdns allows you to refresh the DNS service without needing to reboot the entire server, saving time and avoiding wider network disruption.

Explanation:

The command restartdns specifically targets the DNS service component of Pi-hole, restarting the service alone to apply any recent changes or clear potential hiccups in performance.

Example Output:

  [✓] Restarting DNS service
  [✓] DNS service is running

Use case 6: Whitelist or blacklist a domain

Code:

pihole whitelist|blacklist example.com

Motivation:

Customizing the domain access list ensures that the network filters the correct content to the users’ specifications. Whether it’s whitelisting a frequently accessed domain that is incorrectly blocked or blacklisting a new unwanted domain, these actions precisely control web accessibility.

Explanation:

The whitelist or blacklist commands accept a domain name as an argument (e.g., example.com). whitelist removes that domain from the blocklist, allowing access, while blacklist adds the domain to the list that Pi-hole blocks.

Example Output (whitelist example.com):

  [i] Adding example.com to whitelist...
  [✓] example.com successfully added to whitelist

Use case 7: Search the lists for a domain

Code:

pihole query example.com

Motivation:

Quickly determining if a particular domain is blocked can assist in diagnosing access issues. Searching the lists provides visibility into how Pi-hole is handling specific URLs, permitting you to make informed adjustments to the whitelist and blacklist.

Explanation:

The query command requires a domain name argument to search through Pi-hole’s blocklists and whitelists, determining its status relative to the filtering functions.

Example Output:

  [i] Target: example.com
  Results:
    - example.com is on the blacklist

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

Code:

pihole tail

Motivation:

Monitoring a real-time log of DNS queries can provide valuable insights into the network activity, revealing which domains are frequently accessed and potentially identifying misuse or unusual behavior. This allows network managers to address performance or security concerns promptly.

Explanation:

By executing the tail command, you initiate a live view of DNS queries passing through the Pi-hole. The command does not need any arguments and provides ongoing live updates without additional user interaction.

Example Output:

  Jul 15 10:02:03 dnsmasq[1234]: query[A] example.com from 192.168.1.101
  Jul 15 10:02:03 dnsmasq[1234]: forwarded example.com to 8.8.8.8

Conclusion:

Understanding and utilizing the pihole command unlocks the full potential of Pi-hole’s capabilities for maintaining an ad-free, secure, and efficient network. With easy access to regular updates, status checks, and configurational adjustments, the command-line interface provides administrators with the tools necessary to tailor and optimize their network’s behavior based on real-time data and personal needs. Each example provided illustrates how versatile the Pi-hole utility is, catering to different diagnostic, administrative, and customization requirements through a straightforward command structure.