The pihole command

Pi-hole makes use of many commands, and here we will break down those required to administer the program via the command-line Interface.

Index	Invocation
Core Script	pihole
Web Script	pihole -a

---

Pi-hole Core

Feature	Invocation
Core	pihole
Whitelisting, Blacklisting and Regex	pihole -w, pihole -b, pihole -regex, pihole -wild
Debugger	pihole debug
Log Flush	pihole flush
Reconfigure	pihole reconfigure
Tail	pihole tail
Admin	pihole -a
Chronometer	pihole chronometer
Gravity	pihole updateGravity
Logging	pihole logging
Query	pihole query
Update	pihole updatePihole
Version	pihole version
Uninstall	pihole uninstall
Status	pihole status
Enable & Disable	pihole enable
Restart DNS	pihole restartdns
Checkout	pihole checkout

Core Script

Help Command	pihole --help
Script Location	/usr/local/bin/pihole
Example Usage	pihole -b advertiser.example.com

The core script of Pi-hole provides the ability to tie many DNS related functions into a simple and user-friendly management system, so that one may easily block unwanted content such as advertisements. For both the Command-line Interface (CLI) and Web Interface, we achieve this through the pihole command (this helps minimize code duplication, and allows users to read exactly what's happening using bash scripting). This "wrapper" elevates the current user (whether it be your own user account, or www-data) using sudo, but restricts the elevation to solely what can be called through the wrapper.

Whitelisting, Blacklisting and Regex

Help Command	pihole -w --help, pihole -b --help, pihole -regex --help, pihole -wild --help
Script Location	/opt/pihole/list.sh
Example Usage	pihole -regex '^example.com$' '.*\.example2.net'

Administrators need to be able to manually add and remove domains for various purposes, and these commands serve that purpose.

See Regex Blocking for more information about using Regex.

Basic Script Process:

• Each domain is validated using regex (except when using -regex), to ensure invalid domains and IDNs are not added
• A whitelisted domain gets added or removed from /etc/pihole/whitelist.txt
• A blacklisted domain gets added or removed from /etc/pihole/blacklist.txt
  • On either list type, gravity.sh is then called to consolidate an updated copy of gravity.list, and the DNS server is reloaded
• A regex blacklisted domain gets added or removed from /etc/pihole/regex.list
• A wildcard domain gets converted into regex and added or removed from /etc/pihole/regex.list
  • For both regex-based commands, gravity.sh is then called to restart the DNS server

Debugger

Help Command	N/A
Script Location	/opt/pihole/piholeDebug.sh
Example Usage	pihole debug

The Pi-hole debugger will attempt to diagnose any issues, and link to an FAQ with instructions as to how an admin can rectify the issue. Once the debugger has finished, the admin has the option to upload the generated log to the Pi-hole developers, who can help with diagnosing and rectifying persistent issues.

Log Flush

Help Command	N/A
Script Location	/opt/pihole/piholeLogFlush.sh
Example Usage	pihole flush

When invoked manually, this command will allow you to empty Pi-hole's log, which is located at /var/log/pihole.log. The command also serves to rotate the log daily, if the logrotate application is installed.

Reconfigure

Help Command	N/A
Script Location	/etc/.pihole/automated install/basic-install.sh
Example Usage	pihole reconfigure

There are times where the administrator will need to repair or reconfigure the Pi-hole installation, which is performed via this command.

Basic Script Process:

• basic-install.sh will be run
  • Reconfigure will run through the first-time installation prompts, asking for upstream DNS provider, IP protocols, etc
  • Repair will retain your existing settings and will attempt to repair any scripts or dependencies as necessary
• The rest of basic-install.sh will then run as appropriate

Tail

Help Command	N/A
Script Location	/usr/local/bin/pihole
Example Usage	pihole tail

Since Pi-hole will log DNS queries by default, using this command to watch the log in real-time can be useful for debugging a problematic site, or even just for sheer curiosities sake.

Admin

Help Command	pihole -a --help
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a -p secretpassword

Detailed information on this is found here.

Chronometer

Help Command	pihole -c --help
Script Location	/opt/pihole/chronometer.sh
Example Usage	pihole -c -e

Chronometer is a console dashboard of real-time stats, which can be displayed via ssh or on an LCD screen attached directly to your hardware. The script is capable of detecting the size of your screen and adjusting output to try and best suit it.

_{Image courtesy of /u/super_nicktendo22}

Gravity

Help Command	N/A
Script Location	/opt/pihole/gravity.sh
Example Usage	pihole -g

Gravity is one of the most important scripts of Pi-hole. Its main purpose is to retrieve blocklists, and then consolidate them into one unique list for the built-in DNS server to use, but it also serves to complete the process of manual whitelisting, blacklisting and wildcard update. It is run automatically each week, but it can be invoked manually at any time.

Basic Script Process:

• It will determine Internet connectivity, and give time for dnsmasq to be resolvable on low-end systems if has just been restarted
• It extracts all URLs and domains from /etc/pihole/adlists.list
• It runs through each URL, downloading it if necessary
  • curl checks the servers Last-Modified header to ensure it is getting a newer version
• It will attempt to parse the file into a domains-only format if necessary
• Lists are merged, comments removed, sorted uniquely and stored as list.preEventHorizon
• Whitelisted entries within /etc/pihole/whitelist.txt are removed from list.preEventHorizon and saved into a temporary file
• Blacklisted, "localhost" and temporary file entries are added as separate .list files
• Gravity cleans up temporary content and reloads the DNS server

Logging

Help Command	pihole logging --help
Script Location	/usr/local/bin/pihole
Example Usage	pihole logging off

This command specifies whether the Pi-hole log should be used, by commenting out log-queries within /etc/dnsmasq.d/01-pihole.conf and flushing the log.

Query

Help Command	pihole query --help
Script Location	/usr/local/bin/pihole
Example Usage	pihole -q -exact -adlist example.domain.com

This command will query your whitelist, blacklist, wildcards and adlists for a specified domain.

Basic Script Process:

• User-specified options are handled
• Using idn, it will convert Internationalized domain names into punycode
• The whitelist and the blacklist are searched
• The possible wildcard matches are then searched (/etc/dnsmasq.d/03-pihole-wildcard.conf)
• The adlists are then searched (/etc/pihole/list.*.domains)
• Output is determined by the specified options, ensuring that a file name is only printed once

Update

Help Command	pihole update
Script Location	/opt/pihole/update.sh
Example Usage	pihole -up

Check Pi-hole Core, Web Interface and FTL repositories to determine what upgrades (if any) are required. It will then automatically update and reinstall if necessary.

Basic Script Process:

• Script determines if updates are available by querying GitHub
• Updated files are downloaded to the local filesystem using git
• basic-install.sh is run

Version

Help Command	pihole version
Script Location	/opt/pihole/version.sh
Example Usage	pihole -v -c

Shows installed versions of Pi-hole, Web Interface & FTL. It also provides options to configure which details will be printed, such as the current version, latest version, hash and subsystem.

Uninstall

Help Command	N/A
Script Location	/etc/.pihole/automated install/uninstall.sh
Example Usage	pihole uninstall

Uninstall Pi-hole from your system, giving the option to remove each dependency individually.

Status

Help Command	N/A
Script Location	/usr/local/bin/pihole
Example Usage	pihole status

Display the running status of Pi-hole's DNS and blocking services.

Enable & Disable

Help Command	pihole disable --help
Script Location	/usr/local/bin/pihole
Example Usage	pihole disable 5m

Toggle Pi-hole's ability to block unwanted domains. The disable option has the option to set a specified time before blocking is automatically re-enabled.

Restart DNS

Help Command	N/A
Script Location	/usr/local/bin/pihole
Example Usage	pihole restartdns

Restart Pi-hole's DNS service.

Checkout

Help Command	pihole checkout --help
Script Location	/opt/pihole/piholeCheckout.sh
Example Usage	pihole checkout dev

Switch Pi-hole subsystems to a different GitHub branch. An admin can specify repositories as well as branches.

---

Pi-hole Web

Feature	Invocation
Web Script	pihole -a
Password	pihole -a password
Temperature Unit	pihole -a celsius, pihole -a fahrenheit, pihole -a kelvin
Host Record	pihole -a hostrecord
Email Address	pihole -a email
Interface	pihole -a interface

Web Script

Help Command	pihole -a --help
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a -p secretpassword

Set options for the Web Interface. This script is used to tie in all Web Interface features which are not already covered by the Core Script.

Password

Help Command	N/A
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a -p secretpassword

Set the Web Interface password. Password can be entered as an option (e.g: pihole -a -p secretpassword), or separately as to not display on the screen (e.g: pihole -a -p).

Temperature Unit

Help Command	N/A
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a -c

Set the specified temperature unit as the preferred type. This preference will affect the Web Interface, as well as Chronometer.

Host Record

Help Command	pihole -a hostrecord --help
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a hostrecord home.domain.com 192.168.1.1

Add A & AAAA records to the DNS, to be associated with an IPv4/IPv6 address.

Email Address

Help Command	N/A
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a email admin@domain.com

Set an administrative contact address for the Block Page. This will create a hyperlink on the Block Page to the specified email address.

Interface

Help Command	pihole -a interface --help
Script Location	/opt/pihole/webpage.sh
Example Usage	pihole -a interface local

Specify interface listening behavior for dnsmasq. When using pihole -a interface all, please ensure you use a firewall to prevent your Pi-hole from becoming an unwitting host to DNS amplification attackers. You may want to consider running OpenVPN to grant your mobile devices access to the Pi-hole.

---

Last update: February 5, 2020