linux_course_doc/modules/resources/exercise_pihole.md

# Setting up a pihole at home

What you'll need to get started:

* a raspberry pi
* a USB power supply 
* an SD card you can erase
* a keyboard
* an HDMI cable

## Your current situation

Your current situation looks probably *very* similar to the image below.
You have some sort of router/modem/switch/wirelessAP combination box sitting somewhere in your house.
To this device you have your PC's, printer, phone's connected either with a cable or over WiFi.

![without pihole](./network_home_without_pihole.png)

I advise you to take some notes on your network settings *before* starting to mess around.
Your `nameserver` is probably the IP address of your router and the `DHCP` server for both your wired LAN and wireless WLAN is probably the same IP address.
This means your *bbox* does a few different things:

* it's a modem that gives you a public IP address (from your ISP)
* it does NAT so that your LAN devices can access the internet
* it has a builtin DHCP and DNS server
* it creates a wireless access point so you can connect your phone
* it has a builtin hardware switch so you can connect multiple PC's

As you found out during our exercises, a Linux machine can do all of these things if you configure it properly.
We'll try and replace two, or for the brave ones three, of those *features* with a raspberry pi.
This will be done **step by step** but it's worth pointing out that a basic pihole installation is not invasive at all.
You won't break the internet by just installing the pihole package on your raspberry pi.
Throughout the full installation it is however possible you'll have some downtime.
If there are people in your household depending on the internet to work it might be best to schedule your installation with them.

## Hardware installation

It's probably easiest, and recommended, to do the installation with the raspberry pi connected to your network over Ethernet.
You can perform the installation over `ssh` or with a screen and keyboard connected, it's fully your choice.
You don't need an extra LAN adaptor, just plugging in the raspberry pi into the switch suffices.
Once plugged in your network layout will look similar to the image below.

![with raspberry pi](./network_home_with_pihole.png)

I recommend you start from a fresh Raspberry PI OS installation, either with or without desktop environment.
The raspberry pi should receive an IP address from your *bbox* and you should be able to `ping` devices in your LAN and out on the internet.

## Installing pihole

I won't explain this as it's part of the exercise but there are a lot of tutorials around.
First you should **only** use the DNS feature of the pihole.
This is completely **non invasive** to your network, nor towards the other computers in your home network.
Check the installation by logging into the web interface of your fresh pihole install!

## Testing the DNS aspect of the pihole

Your pihole is now a DNS server!
You can try it out by changing the DNS settings of a PC that's connected to your network.
Depending on your OS it will be done in a different way.
On Linux you'll find the `nameserver` you're using in `/etc/resolv.conf`.
If you did it right, you should see a client connected in the web interface of the pihole.
Try to go to some websites you know have a lot of advertisements and see if the pihole blocks them properly.

## Time to take over the DHCP role

The pihole can also be in charge of the IP addresses on your LAN.
This is the **invasive** part of the setup.
First you should turn off the DHCP server that is currently running on you network.
As mentioned before, this is *probably* your *bbox*.
Log into it and figure our how to deactive it.
Once this is done you can enable the DHCP server on the pihole.
This is done via the web interface.
Try disconnecting and reconnecting a PC from the network and see if it comes up in the leases list.
If it does, bravo!

## Undoing your installation

If you want to revert back to your original network layout the main thing you have to do is turn the DHCP server in your *bbox* back on.
Do keep in mind you can't have two DHCP servers on your network.
You can either turn off the raspberry pi completely or just stop the pihole service via `systemctl`.
Try to disconnect and reconnect one PC first to see if it get's back the normal settings from before.
If it does you successfully removed the pihole from your network!

## For the brave

The raspberry pi has a builtin WiFi adapter you can use to create your own WLAN network.
You can either have the clients join in the same range as your LAN network, or create a secondary subnet.
If you opt for the latter you'll have to tweak you DHCP settings a bit.
The package that turns your pi into a wireless access point is called [hostapd](https://en.wikipedia.org/wiki/Hostapd) and you can find heaps of [tutorials](https://www.raspberrypi.org/documentation/configuration/wireless/access-point-routed.md) online.

## For the super brave

We'll set up a VPN in an upcoming class but the pihole is often used together with [pivpn](https://pivpn.io/).
If you decide to try this out keep in mind that you'll have to add a port forward from your router to the pi and that this **will expose** the VPN service to the internet!
There is nothing inherently *wrong* with that but you'll see hacking attempts almost immediately.
**Use good passwords or preferably encryption keys.**