Installing pi-hole on Ubuntu 18.04 LTS
In this guide, I will walkthrough how to install and test the pi-hole on Ubuntu and more specifically, Ubuntu Server. These same instructions may work on Ubuntu Desktop, but I strongly suggest Server. Why Ubuntu instead of a Raspberry Pi? I love Raspberry Pis and I probably own at least 10 of them. But sometimes I want to perform DNS blocking/blackholing and I either a) don’t have a Raspberry Pi in an environment or b) I have a virtual environment where I can add some robustness to the solution.
At the time of this writing, I should mention that pi-hole is currently *not* supported on Ubuntu 18.04 LTS. Instead, the project officially supports 16.04 LTS. So why install it on 18.04? Ubuntu 16.04 LTS will only receive updates/support until April 2021 unless you purchase extended security maintenance (ESM). I install systems with the intention to not make significant changes to them for some time and the end of life for 16.04 is less than that window of time. 😉
24July2018 – Originally posted
1Sept2018 – Added steps to fix 18.04.1
29Nov2018 – Verified as working
26Jan2019 – Verified as working on both 18.04 and 18.04.1
16Feb2019 – Verified on 18.04.2. Additional steps for 18.04.1 are not required.
5Apr2020 – Verified as working on 18.04.4. Added section on removing hosts-file.net
Why remove advertising?
Advertising is great because it pays content creators for their work. After all, even this site utilizes Google Ads. So why would I create a write-up on blocking ads? Because advertisements are known to carry malicious payloads and it’s impossible to distinguish what’s good and what’s bad. As a result, blocking advertising has become an absolute necessity for those who are security conscious. On a personal note, I’ll happily sacrifice some advertising income for the sake of readers/everyone improving their security! As many have figured out, a side benefit of blocking ads is a better user experience and a substantial drop in bandwidth usage. I’ve written several walkthroughs on how to block ads using different devices such as pfBlockerNG on pfSense. If you own a pfSense, I would strongly suggest using the aforementioned guide to create an experience very similar to the pi-hole. Using pfBlockerNG on pfSense has quite a few additional features such as IP blocking and quite honestly, there is no need to add yet another system to manage.
Installing Ubuntu server is ridiculously easy. Simply download the latest Ubuntu Server LTS ISO and install it as you would any standard OS. Note: There is a slight difference in the install steps if you are installing 18.04.1 LTS instead of 18.04 (even if 18.04 is upgraded to 18.04.1). I explain where the 2 install paths diverge in the Ubuntu 18.04.1 LTS section below. You can safely use the defaults throughout the installation, although I would install security updates automatically when given the option. You may also need to install SSH if that is how you plan to access and manage your server remotely (other than the web interface). If you are installing this in a virtual/VMware environment for a fairly small number of devices, I would recommend a 1GB of memory, 1 CPU core, and at least 30GB of hard drive. FWIW, the initial install of Ubuntu and pi-hole (before any logs) is under 5GB of disk space so 30GB should give you some room to grow. You could potentially require more resources if you have a lot of devices or those devices make a ton of DNS requests. That is something you will need to keep an eye on after you get it up and running!
|pi-hole Minimum Requirements|
|1 core||1 GB (or 2GB)||30 GB|
After your Ubuntu system finishes the install and reboots, login via an SSH terminal or from the console. You should be greeted with a welcome screen similar to the one below with the exception your package and security update counts may be different.
-- Welcome to Ubuntu 18.04 LTS * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage 113 packages can be updated. 51 updates are security updates. --
Once you are logged in and sitting at a terminal prompt, run package updates manually using the command below. Note the command will do the repository update, upgrade the packages, and then reboot in one fell swoop. Grab your favorite beverage and let that process run its course.
$ sudo apt-get update && sudo apt-get upgrade -y && sudo reboot
After the system updates and reboots, log back in via SSH or the console. As you will see on your own install, the packages and security updates should both be at zero (or really close).
-- Welcome to Ubuntu 18.04 LTS * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage 0 packages can be updated. 0 updates are security updates. --
Ubuntu 18.04.1 LTS only
There is a slight difference with the installed base packages between an Ubuntu 18.04 install upgraded to 18.04.1 and a straight 18.04.1 install. Interestingly enough, these additional steps are not necessary for 18.04.2 or later either. The package differences cause the 18.04.1 install to drop back down to a command line (as show below) during install of pi-hole.
The way to correct this issue is in the gray box below. Basically, you add ‘universe’ to the ‘bionic main’ repo line in the /etc/apt/sources.list using the sed command. You follow that with an apt-get update and then install the missing packages. Shout out to xkeyscore_ on Reddit for finding the missing dependencies.
Note: the instructions below are only for the 18.04.1 download. If you installed 18.04 and upgraded to 18.04.1, do NOT run the commands below or you will break your install!!! If you are running 18.04.2 or later, do NOT run these commands!
– /etc/apt/sources.list –
deb http://archive.ubuntu.com/ubuntu bionic main -> deb http://archive.ubuntu.com/ubuntu bionic main universe
$ sudo cp /etc/apt/sources.list /etc/apt/sources.list.orig $ sudo sed -i 's/bionic main/bionic main universe/g' /etc/apt/sources.list $ sudo apt-get update $ sudo apt-get --no-install-recommends install dialog dhcpcd5
If you’re unable to run the last command to install the packages, try the command below and then retry the one above. You do not need to run this command if your apt-get install ran correctly.
sudo dpkg --configure -a
Now it’s time to run the pi-hole install script so just copy/paste the command in the gray box below. Yes, it is a single-lined command. That said, this is extremely dangerous if you are unsure of the source. I would recommend taking a peek at the code before you run it. This is easily done considering the address simply re-directs to “basic-install.sh” script on a GitHub repo. If you can’t read code, that’s ok… At the very least, look at the repo and see if the script has changed recently. If it has, you might consider waiting a few days or at least snoop around some forums to make sure the changes were “expected.”
$ curl -sSL https://install.pi-hole.net | bash
Assuming you ran the command above as a standard user instead of root (or with sudo), you will get prompted for the user password again.
[✗] Root user check [i] Script called with non-root privileges The Pi-hole requires elevated privileges to install and run Please check the installer for any concerns regarding this requirement Make sure to download this script from a trusted source [✓] Sudo utility check [sudo] password for pihole: [✓] Root user check
For the most part, you can select the defaults or simply hit “Ok” on most of the screens, however, I want to highlight a few items/recommendations. First, the pi-hole project is donation-based. Be sure to visit their donation page and keep the project going!
During the install, the pi-hole points out it is currently using a DHCP address instead of a static IP address. As stated in the picture below, using a static IP address is highly, highly recommended. Don’t forget that in most cases, you do not want your new static IP address in your current DHCP range. Instead, assign your pi-hole an IP address outside of your current DHCP pool. For instance, if your DHCP pool is 192.168.1.100-192.168.1.200 then you could safely assign your pi-hole 192.168.1.2 (assuming that IP address wasn’t already used).
I was an early adopter of Quad9 and I’m still very bullish on them. I’ve written several articles about Quad9 and configuring it on numerous devices. Long story short, Quad9 provides another layer of protection and that’s a good thing! For that reason, I would suggest selecting ‘Quad9 (filtered + ECS)’ as the upstream DNS provider when asked during the pi-hole install.
If you are curious about the different Quad9 options available, here you go. ‘Quad9 (filtered, DNSSEC)’ means we want to block malicious domains and we are protecting against forged DNS records by using DNSSEC. This option is tied to the Quad9 namesake – 126.96.36.199. ‘Quad9 (unfiltered, no DNSSEC)’, which is actually 188.8.131.52, means that we will *not* block malicious domains and we will *not* use DNSSEC. Last, we have ‘Quad 9 (filtered + ECS)’. Filtered is familiar, but what is ECS? ECS, also known as EDNS client subnet, is generally used to help speed up data from content delivery networks. Although not stated in the pi-hole menu, this option is based on 184.108.40.206. According to Quad9, this IP address supports all of the above — DNS encryption, DNSSEC, EDNS Client Subnet, and blocking malicious domains.
When asked which blacklists to use, make sure you de-select ‘hosts-file.net’ or you will receive an error when it attempts to download the file (below). You’ll also receive several ongoing errors because the list is no longer supported. If you accidentally added it and now you’re getting errors, refer to the section below on Removing hosts-file.net (ad_servers.txt).
[i] Target: hosts-file.net (ad_servers.txt) [✗] Status: Not found [✗] List download failed: no cached list available
The install will download At the installation complete screen, you should take note of your IP address (if you changed it) and also the randomly generated password. Beware of ones that look like lowercase l’s and zeros that look like uppercase O’s. If you can copy and paste it, I would strongly suggest it to avoid issues logging in! You can change the pi-hole web password as described in the section below.
Change your pi-hole web password
Via the an SSH terminal or the console, type in “pihole -a -p” and hit enter. Type in your new password twice.
$ pihole -a -p Enter New Password (Blank for no password): Confirm Password: [✓] New password set
pi-hole web interface
The pi-hole has a very friendly web interface to manage your device. Using your web browser, go to http://<ip address>/admin and you should see a nice statistics screen as shown below. Click on ‘Login’ and either type in the password provided to you during install (or the password you changed to in the last section).
After you get some clients configured (described below), you can come back to the web admin interface and see how many domains are blocked along with quite a few other stats. The web interface is also where you can add other blacklists, whitelist domains, etc.
How it works – testing from the command line
The easiest way to test whether your pi-hole is going to work is via a command line. I would strongly recommend testing before making the DHCP server or client changes below!
We can use the nslookup command from any machine on the network. The format of the nslookup command is the same whether on Linux or Windows — nslookup <hostname to test> <IP address for your pi-hole>. In my test environment, the pi-hole is 192.168.1.2 and we are testing a well-known Yahoo advertising domain, analytics.yahoo.com. Instead of returning the actual IP address for analytics.yahoo.com, the pi-hole returns 0.0.0.0. This effectively blackholes the hostname via DNS so your system/browser is not able to access it. Note: the pi-hole used to use its own IP address, but this caused a slight timeout whereas 0.0.0.0 causes the connection to get dropped immediately.
C:\>nslookup analytics.yahoo.com 192.168.1.2 Server: pihole Address: 192.168.1.2 Name: analytics.yahoo.com Address: 0.0.0.0
If we test against a domain that is not blocked, then we receive the actual external IP addresses for the hostname as shown below.
C:\>nslookup walmart.com 192.168.1.2 Server: pihole Address: 192.168.1.2 Non-authoritative answer: Name: walmart.com Addresses: 220.127.116.11 18.104.22.168
Client configuration changes
This part of the walkthrough will vary wildly because it changes from one environment to the next. If you can make a change at whatever device or server is handing out DHCP addresses (as shown in the Linksys picture below), then you should absolutely make the change there.
Note: If your system already resolved a domain name, then you may need to clear your local DNS cache, your browser cache, or both. To clear your machine’s cache, from a command line on Windows, type in ‘ipconfig /flushdns’ and that should take care of it. You can run a similar command on a Linux system, although the commands can vary from one installation to the next. More often than not, simply restarting your network interface will work; on most distributions, ‘service networking restart’ or ‘systemctl restart network’ should take care of it for you. Each browser has a slightly different way to clear the cache, however, all of them allow you to pull a new version of the website if you hold down “Shift” while clicking on the refresh/reload button.
If you can’t make the change at the server or router/firewall for whatever reason, then you may need to make the change at each client. Changing each client is an issue if you have a number of IoT devices where you can’t even access the underlying configuration. If you have a number of devices, this would also be extremely cumbersome and quite honestly, it might be worth looking at swapping out equipment. Alternatively, you could also disable the current DHCP server entirely and instead enable the DHCP server on the pi-hole (also via the web interface). If you go the pi-hole DHCP server route, make sure you disable the other DHCP server so you don’t have two servers on the same network.
If the client is the route you want to go and I haven’t talked you out of it… On Windows, go to control panel and drill into your network adapter settings as shown below.
Testing By Browsing
So what does the finished product look like? On many sites like YouTube, you’ll see empty space or a gray box where an ad normally would have been. A browser add-on like uBlock Origin (discussed below) further cleans this up by removing the gray box entirely and it also provides some secondary protections. If you visit Yahoo.com (why? seriously, find a new news site), our pi-hole configuration eliminates the wasteland of ads that you normally see as well (red box below). Many sites will look similar to this with vast regions of white space where ads normally would show and don’t be surprised to find ads intermingled with news on many sites. <- In advertising, it’s all about improving that click through ratio (CTR)!
Removing host-file.net (ad_servers.txt)
Host-file.net appears to be gone for good despite its popularity. Malwarebytes, in their infinite wisdom have discontinued its support. Meanwhile, they are continuing to dissolve any shred of value their brand has/had. At any rate, to remove the hosts-file.net from your blocklists, log into your pi-hole, then go to Settings -> Blocklists. De-select the checkbox next to hosts-file.net and then click ‘Save and Update’.
Browser side blocking – Ublock Origin
I constantly preach defense-in-depth and this is no different. Aside from using pi-hole or other DNS blackholing defenses, I would also strongly suggest using uBlock Origin on all of your browsers. uBlock Origin exists for Chrome, Firefox, etc. so there really isn’t a reason not to have it! While nothing is foolproof, it is another fantastic addition to your overall security.
Dallas Haselhorst has worked as an IT and information security consultant for over 20 years. During that time, he has owned his own businesses and worked with companies in numerous industries. Dallas holds several industry certifications and when not working or tinkering in tech, he may be found attempting to mold his daughters into card carrying nerds and organizing BSidesKC.
41 thoughts on “Installing pi-hole on Ubuntu 18.04 LTS”
hi, in my case, after “curl -sSL https://install.pi-hole.net | bash” a box appears as ‘installing packages” and shows as “100%” just in second, but no more activities even after 48 hours. Thanks for your post.
We had a similar discussion briefly on the pi-hole subreddit as well. I’ve been unable to reproduce the issues described on any of my installs/environments. You might be able to resolve your particular issue by following the instructions below. If that works, let me know and I’ll update the guide. Thanks!
Excellent, worked just as PnP after I followed your reply.
FYI: It stopped working few hours after installation like “Total queries” was rising but “Queries Blocked” stopped counting and all clients were receiving advertising as usual. Rebooting the “system” & “dnsmasq” and other things didn’t solve problem but “Update Gravity” fixed everything back to its normal function.
Thank you very much
No problem! I’ll add that fix to the walkthrough. Thanks for letting me know!
Hi. I’m running ubuntu 18.04 and I already tried the solution to add univers to my sources.list, even if it was already there.
I still have the issue: the installation stops at 100% and get back to the command line.
I alread have apache running and if I point my browser to /var/www/html/admin/index.php the web console shows up, but with some errors at the top of the page:
Warning: parse_ini_file(/etc/pihole/setupVars.conf): failed to open stream: No such file or directory in /var/www/html/admin/scripts/pi-hole/php/password.php on line 15
Warning: parse_ini_file(/etc/pihole/setupVars.conf): failed to open stream: No such file or directory in /var/www/html/admin/scripts/pi-hole/php/auth.php on line 26
I suppose because I never got to the password screen that should appear at the end of the installation.
If I try to launch the command to change the password I get a message taht pinhole is not installed on my computer.
I went back through the instructions on a fresh install of 18.04.1 and I didn’t see the issue you are describing. I’m going to try another with 18.04 (non-point release) as the base. Someone else just posted they would recommend ‘apt-get install gamin’ to fix lighthttpd issues. I ran it on my fresh install and it stated it was already installed. Please report back what you find so I can update the guide if necessary. Thanks!
$ sudo apt-get install gamin
Reading package lists… Done
Building dependency tree
Reading state information… Done
gamin is already the newest version (0.1.10-5build1).
gamin set to manually installed.
0 upgraded, 0 newly installed, 0 to remove and 2 not upgraded.
Hey if i have set up this in AWS how do i get my network to connect through it
Your server should listen on the standard port and you can verify this with netstat. From there, simply point your endpoint/firewall to the IP address of the server. You can test this via nslookup before making the switch. The other thing I would stress is limiting your DNS listener to certain IPs or networks and not opening it to the entire world. 😉
Cant connect to the webinterface:
“Parse error: syntax error, unexpected ‘[‘ in /var/www/admin/scripts/pi-hole/php/auth.php on line 27”
I just installed Proxmox on a new server so I went through the instructions again to make sure nothing changed. My install worked perfectly on the latest version of 18.04.1 LTS. Can you verify the sources.list file now has ‘universe’ appended to the ‘bionic main’ line? Also note that if the last command in the list of 4 (in the gray box) doesn’t work, I would recommend running ‘sudo dkpg –configure -a’ to see if that clears up any issues. Good luck!
On the server I use, there are a lot of application already installed. I setup the server as a NAS.
Is these instruction working on a server what already is installed. I’m scared that this setup will remove a lot of settings. Am I right?
This installs a fair number of packages and there is a high probability the package versions could conflict. Personally, I would *not* recommend installing this onto an already running server. Instead, I would spin up a new VM or opt for the Raspberry Pi approach. Hope this helps!
Thank you. I gonna think about your recommendation and search for another solution.
You made a wise choice. It would have likely caused headaches both now and in the future. 😉
Hello, I have a small Dell Optiplex desktop, if Ubuntu linux installs, then I should be good for with the Pi-Hole install.
Yes, although I would prob grab a Raspberry Pi to save a little electricity. 😉
Thanks for the reply, Raspberry Pi 3 B+ on order. Running great on a HP Elitedesk 800 SFF. The instructions was spot on, shared your site friends.
Fantastic! So happy to hear it helped you out!
Hello, great article!
Only one thing. I was wondering what is the difference between set up a pi-hole machine in the network or configure directly the router with, let´s say, the 22.214.171.124 DNS.
Is there any difference?
Thanks in advance.
A pi-hole blocks tons of advertising/malvertising that Quad9 does not. The nice thing about pi-hole (or pfBlockerNG if I have a pfSense) is that you have the control, i.e. you can get fairly aggressive with blocking and using different lists. Meanwhile, Quad9 only blocks the worst of the worst. Hope that helps!
Of course it helps,
Thank you very much!!
Thanks to your tips about the installation in Ubuntu, it works ! 🙂
Great! Thanks for the feedback!
If lighttpd does not work
apt-get install gamin
Thanks for the recommendation! I just replied to Manuel who saw issues with lighthttpd. I’m going to re-run the setup on a handful of 18.04 point releases to make sure there aren’t any inconsistencies. Much appreciated!
Will this tutorial work for Ubuntu 18.04.02 LTS?
18.04.2 LTS was delayed in its release and it should instead release sometime this week. I’ll test it sometime after it becomes available. If you get a chance to test before I do, let me know and I’ll update the guide. Thanks!
The following command contains both a typo as well as incorrect syntax:
‘sudo dkpg –configure -a’
The correct command should be:
‘sudo dpkg –configure -a’
Good catch on the typo! The syntax is correct when you copy/paste, but it appears as one dash because of the default font. I separated it out as preformatted text instead so it now looks correct in case anyone is typing it. Thanks for the feedback!
Hey, gonna try this soon, just for confirmation: can I redirect the web to another port? Can I setup pihole with dnssec?
DNSSEC is not enabled by default, however, you can enable it in the web interface. Simply go to Settings -> DNS -> Use DNSSEC. I’m a little uncertain on your port request… I’m assuming you are referring the default web admin port. Changing the default web admin port is accomplished by modifying the server.port variable in your /etc/lighttpd/lighttpd.conf and restarting lighttpd. I would obviously recommend making a copy of the file before editing too. 😉 Good luck!
Quick follow up to say thanks again for for the write up. Wanted to post a small bit of advice to others following the guide. When you said take the defaults for the server load, that indeed is what you want to do. I initially inadvertently selected the first snapshot on the installation list and then ended up with several additional services enabled causing all sorts of small issues related to misc items attempting to start up that normally would not (Kubernetes and etcd to name a couple). Blew away the instance and did as you said and took ONLY the defaults and now no problems. 18.04.2 LTS is a go for me. Thanks again!
I’m a noob. Trying to learn Linux as well as block ads.
I did everything according to your page.
Running: Ubuntu 18.04.3 LTS
Ran nslookup yahoo.com 192.168.0.15
Response: ;; connection timed out; no servers could be reached
What do I need to do?
Aaron, sorry I’m just getting back to you. Were you able to figure it out?
Hey Dallas! Great write up.
I’m struggling a bit with the nslookup portion. My pi hole is set with a static ip of 192.168.1.1 and I get the following output when I run nslookup to the analytics.yahoo.com.
nslookup analytics.yahoo.com 192.168.1.1
The address is set to 0.0.0.0 which I’m assuming is the default route to my ISP or the internet? I can still seed adverts on websites so I’m confused on what’s actually happening. I should mention that I’m running it through VMware Fusion software on my laptop. I will eventually get a raspberry pi to run it but wanted to see how well it worked.
Hey Ben! Thanks for the feedback and sorry I’m just getting back to you. I’m guessing you got your answer, but in case you didn’t. Apparently pi-hole changed this behavior at some point. 0.0.0.0 is preferred IP to use because it will drop the client immediately whereas 127.0.0.1 (or the actual pi-hole IP) would cause a slight delay. My guess is that you were still seeing the ads because a) your operating system or browser had cached the DNS results or b) you had not yet changed the DNS in your firewall or on your local machine. I did make the necessary changes in the guide as well.
Thanks, very well done guide, and even updated!!!
In my installation the machine (LXC) had a DHCP and in the /etc/resolv.conf the IP of the DNS resolver proposed by the DHCP remained there, I had to modify it with 127.0.0.1
Thanks Andrea! I don’t know if I’m following you… So your container was using DHCP and received incorrect DNS servers from it? If so, once you move out of the testing phase, I would suggest changing your DHCP server so it hands out the appropriate settings automatically and you don’t have to override individual DHCP/DNS settings. Hope this helps!
After a while I’m back to report that I finnaly was able to install pi-hole following your instructions.
Don’t know what changed, but it went easy.
Now I have another question: my pi-hole is on an ubuntu machine. My NAS serve as DHCP and in its setup I use the ubuntu machine IP as DNS, so every client gets its IP fron the NAS and it gets pi-hole as DNS, am I right?
But what about the ubuntu machine where pi-hole is installed?
In the pi-hole web interface under Tools->network I get a list of all the devices that are using pi-hole and I get the pi-hole itself IP listed as not using.
How should it looks the network configuration on the ubuntu machine where I run it?
Manuel, using your NAS for DHCP and the pi-hole as the DNS server for that DHCP is perfectly fine. Your primary concern in that situation is that there is one and only one DHCP server on the network. At some point, it might not hurt to switch DHCP functionality to the pi-hole, but it’s not entirely necessary. Nice work!