The pihole Command With Examples


#1

The pihole command lets you control, configure, and update your Pi-hole.

Autocomplete

Press tab after writing pihole to see the available options.

General Usage

Usage: pihole [options]
Example: 'pihole -w -h'
Add '-h' after specific commands for more information on usage

Whitelist/Blacklist Options:
  -w, whitelist       Whitelist domain(s)
  -b, blacklist       Blacklist domain(s)
  -wild, wildcard     Blacklist domain(s), and all its subdomains
                        Add '-h' for more info on whitelist/blacklist usage

Debugging Options:
  -d, debug           Start a debugging session
                        Add '-a' to enable automated debugging
  -f, flush           Flush the Pi-hole log
  -r, reconfigure     Reconfigure or Repair Pi-hole subsystems
  -t, tail            View the live output of the Pi-hole log

Options:
  -a, admin           Admin Console options
                        Add '-h' for more info on admin console usage
  -c, chronometer     Calculates stats and displays to an LCD
                        Add '-h' for more info on chronometer usage
  -g, updateGravity   Update the list of ad-serving domains
  -h, --help, help    Show this help dialog
  -l, logging         Specify whether the Pi-hole log should be used
                        Add '-h' for more info on logging usage
  -q, query           Query the adlists for a specified domain
                        Add '-h' for more info on query usage
  -up, updatePihole   Update Pi-hole subsystems
  -v, version         Show installed versions of Pi-hole, Admin Console & FTL
                        Add '-h' for more info on version usage
  uninstall           Uninstall Pi-hole from your system
  status              Display the running status of Pi-hole subsystems
  enable              Enable Pi-hole subsystems
  disable             Disable Pi-hole subsystems
                        Add '-h' for more info on disable usage
  restartdns          Restart Pi-hole subsystems
  checkout            Switch Pi-hole subsystems to a different Github branch
                        Add '-h' for more info on checkout usage

-a Usage

Usage: pihole -a [options]
Example: pihole -a -p password
Set options for the Admin Console

Options:
  -p, password        Set Admin Console password
  -c, celsius         Set Celsius as preferred temperature unit
  -f, fahrenheit      Set Fahrenheit as preferred temperature unit
  -k, kelvin          Set Kelvin as preferred temperature unit
  -r, hostrecord      Add a name to the DNS associated to an IPv4/IPv6 address
  -e, email           Set an administrative contact address for the Block Page
  -h, --help          Show this help dialog
  -i, interface       Specify dnsmasq's interface listening behavior
                        Add '-h' for more info on interface usage

Example Usage

Whitelist or Blacklist A Domain

-w Usage

Usage: pihole -w [options] <domain> <domain2 ...>
Example: 'pihole -w site.com', or 'pihole -w site1.com site2.com'
Whitelist one or more domains

Options:
  -d, --delmode       Remove domain(s) from the whitelist
  -nr, --noreload     Update whitelist without refreshing dnsmasq
  -q, --quiet         Make output less verbose
  -h, --help          Show this help dialog
  -l, --list          Display all your whitelisted domains
  --nuke              Removes all entries in a list

-b Usage

Usage: pihole -b [options] <domain> <domain2 ...>
Example: 'pihole -b site.com', or 'pihole -b site1.com site2.com'
Blacklist one or more domains

Options:
  -d, --delmode       Remove domain(s) from the blacklist
  -nr, --noreload     Update blacklist without refreshing dnsmasq
  -q, --quiet         Make output less verbose
  -h, --help          Show this help dialog
  -l, --list          Display all your blacklisted domains
  --nuke              Removes all entries in a list

This is one of the most common things you might do with the pihole command (see commonly whitelisted or blacklisted domains)

Whitelist Spotify

pihole -w spclient.wg.spotify.com

Blacklist Twitch (appending multiple domains to the command)

pihole -b api.mixpanel.com spade.twitch pubads.g.doubleclick.net sb.scorecardresearch.com

Wildcarding

Some ad networks have several subdomains that all server advertisements. Instead of blacklisting each one individually, you may want to block all of a subdomain to a certain point. As an example, pubnub.com has several subdomains:

ps-14.pubnub.com
ps-862.pubnub.com
ps-827.pubnub.com
ps-906.pubnub.com
ps-121.pubnub.com
ps-566.pubnub.com
ps-565.pubnub.com
ps-332.pubnub.com

Instead of blacklisting each one individually, you can pass the -wild flag to block the entire set of subdomains.

pihole -wild pubnub.com

will achieve the same effect.

You can also remove these wildcard entries with the -d flag

pihole -wild -d pubnub.com

Debug Your Pi-hole Install

Our debug script will run through some diagnostics and (optionally) automatically upload this log to our secure server. It will generate a unique token, which you can provide to the Pi-hole dev team if you need help.

pihole -d -a

if you don’t want the log to be uploaded automatically, just run

pihole -d

and the log will be saved locally.

Sending The Debug Token To The Development Team

If you choose to upload your debug log to our secure server, you will be given a random string of characters, which is your debug token. It will look something like this. When the command is finished running, you will see a message like this:

[?] Would you like to upload the log? [y/N] y
    * Using openssl for transmission.

***********************************
***********************************
[✓] Your debug token is: xamtybzux1  <-----provide us this
***********************************
***********************************

So when you contact us for help, you would provide us with the token xamtybzux1 and then we could look at your log file.

Flushing The Log File

Depending on your system and how heavily your Pi-hole is used, you may want to flush the log throughout the day. By default, the log if flushed at the end of the day via cron, but a very large log file can slow down the Web interface, so flushing it can be useful. Just run

pihole -f

NOTE: if you flush the log, some of the stats will not be processed by FTL and thus may not show up in long-term stats.

Tailing The Log File

Pi-hole logs DNS queries by default (this can be turned off when installing). Watching this log file in real-time can be useful for debugging a problematic site. You can also use it purely for curiosity. Since you will see domain queries come up in real-time you can see what is happening on your network.

pihole -t

will start the log rolling. Press Control + c to stop viewing the log.

Interpreting The Log

The log file can be a bit confusing, so take a look at this article to help understand what you are looking at.

Updating Pi-hole

pihole -up

will update your Pi-hole to the latest version.

Chronometer

This command will show you some real-time stats on the command line. It works if you have an LCD screen, but it also works over SSH if you just want to hop in and watch some formatted stats roll by (see also Logstalgia).

pihole -c

You will be presented with some ASCII text that auto-refreshes.

 Pi-hole Chronometer
 
 Press Ctrl-C to exit
 ——————————————————————————————————————————————————————————
  Hostname: debian (Debian Jessie 8)
    Uptime: 4 days, 23:54:43                                                                                                                                                  
 Task Load: 0.00 0.03 0.01     (Active: 1 of 31 tasks)
 CPU usage: 2%                 (2.4 GHz)
 RAM usage: 20%                (Used: 98 MB of 494 MB)
 HDD usage: 7%                 (Used: 1 GB of 20 GB)
  LAN addr: 138.197.94.47      (Gateway: 138.197.80.1)
   Pi-hole: Active             (Blocking: 106012 sites)
 Ads Today: 0%                 (Total: 4 of 4097)
Local Qrys: 81%                (2 DNS servers)
   Blocked: shs.grafixreview.com                                                                                                                                              
Top Advert: shs.grafixreview.com                                                                                                                                              
Top Domain: 220.ip-79-137-39.eu                                                                                                                                               
Top Client: localhost                        

Press Ctrl+C at anytime to stop the script.

Gravity

This command is crucial to Pi-hole as it downloads and processes ad block lists from several sources and combining them into a single gravity.list hosts file, which is used to block ads. Run it with

pihole -g

This will for a download of any updates from the third-party block lists that we source. By default, this command runs once a week via cron, so there’s no need to run it manually unless you want to get some updated lists or you run into a problem with the list.

Ad List Query

Usage: pihole -q [option] <domain>
Example: 'pihole -q -exact domain.com'
Query the adlists for a specified domain

Options:
  -adlist             Print the name of the block list URL
  -exact              Search the block lists for exact domain matches
  -all                Return all query matches within a block list
  -h, --help          Show this help dialog

This command is useful to find out what domain a list appears on. Since we don’t control what the third-parties put on the block lists, you may find that a domain you normally visit stops working. If this is the case, you could run

pihole -q somedomain.com

and it will return the list the domain was originally found on. This proved useful a while back when the Mahakala list was adding apple.com and microsoft.com to their block list.

Use can use the -exact flag to find an exact match, otherwise it will just search for your phrase, so

pihole -q hulu

will return any domain with hulu in it, and

pihole -q t2.hulu.com -exact

will only search for t2.hulu.com.

Enable/Disable Logging

Usage: pihole logging [options]
Example: 'pihole logging on'
Specify whether the Pi-hole log should be used

Options:
  on                  Enable the Pi-hole log at /var/log/pihole.log
  off                 Disable the Pi-hole log at /var/log/pihole.log

You can turn off logging:

pihole -l off

and turn it back on:

pihole -l on

This can be useful if you don’t want queries logged for a certain time.

Administer The Web Interface

You will mainly use this command to set or reset a password for the interface (a default password is generated at install), but you can also use it to adjust the temperature unit.

Set A Web Interface Password

pihole -a -p somepassword

will set a new password for your admin interface.

Adjust The Temperature Unit

You can also change the temperature unit to celsius:

pihole -a -c

fahrenheit:

pihole -a -f

or kelvins:

pihole -a -k

Change the listening interface

Usage: pihole -a -i [interface]
Example: 'pihole -a -i local'
Specify dnsmasq's network interface listening behavior

Interfaces:
  local               Listen on all interfaces, but only allow queries from
                      devices that are at most one hop away (local devices)
  single              Listen only on eth0 interface
  all                 Listen on all interfaces, permit all origins

Running

pihole -a -i local

Will set Pi-hole to listen on all interfaces, but allow only queries from devices that are at most one hop away (local devices). This is the default behavior, which also helps prevents open resolvers.

pihole -a -i single

Will tell Pi-hole to listen on a single interface (see PIHOLE_INTERFACE).
Finally,

pihole -a -i all

Will set Pi-hole to listen on all interfaces, while permitting all origins (requests from outside your network).

Host Records

Add a name to the DNS associated to an IPv4/IPv6 address

Options:
  ""                  Empty: Remove host record
  -h, --help          Show this help dialog

This flag lets you assign a name to an IP address. This is useful for recognizing clients in the query log.

pihole -a myrouter home.domain.com 192.168.1.1

Administrator Email

Usage: pihole -a email <address>
Set an administrative contact address for the Block Page

Options:
  ""                  Empty: Remove admin contact
  -h, --help          Show this help dialog

This flag allows you to set an email address that appears in the block page. This is useful in large environments when an end-user comes across a blocked site and wants to contact someone for more information.

Just enter an email address as an argument:

pihole -a -e admin@address.com

Uninstall Pi-hole

You can uninstall Pi-hole by running

pihole uninstall

You will have the option to choose which packages will be removed in case you use them for other services on your machine.

Enabling Or Disabling Pi-hole

pihole enable

You can disable Pi-hole using

pihole disable

but you can also pass a time argument to disable Pi-hole for a certain amount of time:

pihole disable 10m

will disable Pi-hole for 10 minutes. Please note that you may not see the effects unless you flush your cache. You can use m for minutes or s for seconds.

pihole disable 60s

will disable Pi-hole for sixty seconds.

Checking If Blocking Is Enabled

You can check the current status of Pi-hole using

pihole status

Restart DNS

You can restart the DNS server with

pihole restartdns

this will force a reload of dnsmasq at which time it will also reload the config file and the hosts file.

Versions

Usage: pihole -v [repo | option] [option]
Example: 'pihole -v -p -l'
Show Pi-hole, Admin Console & FTL versions

Repositories:
  -p, --pihole         Only retrieve info regarding Pi-hole repository
  -a, --admin          Only retrieve info regarding AdminLTE repository
  -f, --ftl            Only retrieve info regarding FTL repository
  
Options:
  -c, --current        Return the current version
  -l, --latest         Return the latest version
  --hash               Return the Github hash from your local repositories
  -h, --help           Show this help dialog

The version flag has a lot of options. As our software is broken out into three main pieces, there are versions for each.

Checkout different branches of the project

WARNING: the development branch is not considered stable for general use. We regularly push changes to it so don’t be surprised if something is broken. If you do find an issue in development open an issue on GitHub so we can take a look.

You can checkout what’s happening in our development environment by using this command. Under the hood, it’s just running a series of git commands, but you’ll probably find this more convenient.

In most cases, you will want to check out both the Core code and the Web code, as the two often are dependent on one another. To checkout development branches on both repos, use:

pihole checkout dev

To return to the stable to codebase, just run:

pihole checkout master

Finally, if you deep into the code, you may want to check out a branch other than development. Just use;

pihole checkout core somebranch

to checkout just the core code, or

pihole checkout web somebranch

for the Web code.


How do I determine what domain an ad is coming from?
Pi-hole™ 3.0 Is Here Featuring Our New FTL Engine
What files does Pi-hole use?
Suggestion: List all commands for pi-hole in the FAQ
How do I set or reset the Web interface Password?
What's your development setup?
The Pi-hole™ Swag Store Is Now Open
Pi-hole 3.0.1 Fixes And Tweaks
How do I troubleshoot problems with my Pi-hole?
Pi: DNS Resolution is not available after update to 3.2
IPv4 gateway OpenVZ
Doubleclick.net and wildcard
Why is a default gateway important for Pi-hole?
Pi-hole v3.1 Has Been Released
Blocked although whitelisted and not found in blocklists
Pi-hole Will Be Participating In Hacktoberfest
Dnsmasq fails on Pi-hole 3.3
How do I watch and interpret the pihole.log file?
A Security Note About Your Pi-hole Logs
Adding a list of domains to white/blacklist through webgui
Pi-hole v3.2 Introduces Long-term Statistics, An Audit Log, Colours, and More!
#2