🥧 Prepares Pi-hole on a virtual machine (VM) via Vagrant and Ansible.
The VM will appear on your network as a local machine, providing Pi-hole's DNS services to other machines on the network, without the need for a dedicated physical box.
The VM also has its own hostname on the local network (pihole.local
) for easy access to Pi-hole's web interface.
Make sure you have the following dependencies installed beforehand:
These should be available via your bog-standard package manager (eg: APT on Ubuntu, Homebrew on the Mac).
-
Clone this repository.
-
Switch to the repository directory.
-
In the directory, run:
vagrant up
-
Vagrant will prompt you to choose an interface to bridge to the local network. In general, choose the ethernet connection if the host machine is wired, but WiFi is fine to. For example:
==> pihole: Available bridged network interfaces: 1) enp0s25 2) br-5a8f6827ab14 3) docker0 4) br-4ec60aaeb8fe ==> pihole: When choosing an interface, it is usually the one that is ==> pihole: being used to connect to the internet. pihole: Which interface should the network bridge to? 1
-
Allow Vagrant to finish provisioning the VM. If successful, the last lines displayed will look like these:
PLAY [Next steps] ********************* TASK [debug] ************************** ok: [pihole] => { "msg": "Pi-hole is ready for installation. Please continue with the manual installer as per the README.md file." } PLAY RECAP **************************** pihole : ok=9 changed=5 unreachable=0 failed=0
-
The VM should now be running, but you need to manually run the Pi-hole installer as it requires user interaction. Still within the directory of the checked out repository, run:
$ vagrant ssh
This will bring you into the virtual machine. Now switch to the root user:
vagrant@pihole:~$ sudo su - root
As root, switch to the installation directory and run the installer:
root@pihole:~# cd Pi-hole/automated\ install/ root@pihole:~/Pi-hole/automated install# bash install.sh
-
Follow the standard installation instructions. Ensure that you choose to install the web interface.
Once the installation is completed, you can drop out of the VM's SSH session.
-
Confirm access to Pi-hole's web interface by visiting
http://pihole.local
in the web browser of any machine on the network. -
Continue to follow the setup instructions from the Pi-hole website by configuring your router to use the new DNS server.
-
Always set up a secondary DNS server in your router, so there's something to fall back on if Pi-hole is failing for some reason. E.g.: 1.1.1.1.
-
Test whether machines on your local network are using Pi-hole for DNS lookup using the
dig
command on any external website, for example:dig heliomass.com
The output will let you know which DNS server was used. If you don't see the one on your local network, it means the router fell back on the secondary DNS server and Pi-hole isn't working as expected.
-
When I set this up on my own network, I found the DNS server was running on the other network interface in the VM. If you're unable to hit the DNS server, this could be the problem. Fixing it was a multi-step process:
-
Go to
http://pihole.local
in a web browser. Sign into the site (if you don't know the password, see the next tip) -
Navigate to "Settings" on the left-hand navigation, and then "DNS" on the top navigation.
-
Under "Interface listening behavior", select "Listen on all interfaces" and then scroll down click "Save" at the bottom of the page.
-
Go back to the VM and run
ifconfig
, eg:$ vagrant ssh Welcome to Ubuntu 18.04.2 LTS (GNU/Linux 4.15.0-50-generic x86_64) * Documentation: https://help.ubuntu.com * Management: https://landscape.canonical.com * Support: https://ubuntu.com/advantage System information as of Wed May 22 01:53:34 UTC 2019 System load: 0.0 Processes: 106 Usage of /: 12.9% of 9.63GB Users logged in: 0 Memory usage: 23% IP address for enp0s3: 10.0.2.15 Swap usage: 0% IP address for enp0s8: 10.0.1.35 * Canonical Livepatch is available for installation. - Reduce system reboots and improve kernel security. Activate at: https://ubuntu.com/livepatch 0 packages can be updated. 0 updates are security updates. Last login: Mon May 20 16:33:32 2019 from 10.0.2.2 vagrant@pihole:~$ ifconfig enp0s3: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500 inet 10.0.2.15 netmask 255.255.255.0 broadcast 10.0.2.255 inet6 fe80::86:97ff:fe5e:6688 prefixlen 64 scopeid 0x20<link> ether 02:86:97:5e:66:88 txqueuelen 1000 (Ethernet) RX packets 58571 bytes 56159998 (56.1 MB) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 24167 bytes 2078775 (2.0 MB) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 enp0s8: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500 inet 10.0.1.35 netmask 255.255.255.0 broadcast 10.0.1.255 inet6 fe80::a00:27ff:fe56:e9b9 prefixlen 64 scopeid 0x20<link> ether 08:00:27:56:e9:b9 txqueuelen 1000 (Ethernet) RX packets 146286 bytes 33301222 (33.3 MB) RX errors 0 dropped 555 overruns 0 frame 0 TX packets 32111 bytes 8248790 (8.2 MB) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 lo: flags=73<UP,LOOPBACK,RUNNING> mtu 65536 inet 127.0.0.1 netmask 255.0.0.0 inet6 ::1 prefixlen 128 scopeid 0x10<host> loop txqueuelen 1000 (Local Loopback) RX packets 16099 bytes 1129836 (1.1 MB) RX errors 0 dropped 0 overruns 0 frame 0 TX packets 16099 bytes 1129836 (1.1 MB) TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0
One of the interfaces will have a different IP address to the one Pi-hole tells you the DNS is running on. Use this address (but be aware that the network could reassign a different IP if the router is restarted)
-
-
If you forget the admin password, reset from within the VM using
pihole -a -p
. For example$ vagrant ssh vagrant@pihole:~$ sudo su - root root@pihole:~# pihole -a -p Enter New Password (Blank for no password):
-
Once the VM is set up, treat it like a regular Ubuntu VM. I.e., check packages are up to date, etc, to keep the system secure.
You can keep Pi-hole itself up to date by periodically running
pihole -up
as the root user. -
You can stop the VM with
vagrant halt
, and restart it again withvagrant up
. If you need to provision it from scratch, destroy the VM withvagrant destroy
.
- It would be nice to fully automate the install. The Pi-hole installer unofficially supports this, and Ansible can be made to prompt the user in advance for various options.
- It would also be nice to have an Ansible playbook for updating the OS and Pi-hole.
Read more about this project on my blog.