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
developmentopen 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.