Pi hole and macvlan doc (#241)

docs/README.md

@@ -81,6 +81,8 @@ You're done! Now just click App Templates and deploy applications!
 |[Install and setup instructions for the WireGuard VPN Server](https://github.com/novaspirit/pi-hosted/blob/master/docs/wireguard-install.md) |
 |[WORDPRESS + SSL SETUP](https://github.com/novaspirit/pi-hosted/blob/master/docs/wordpress_installation.md) |
 |[Install and Setup Instructions for the Throttled Script](https://github.com/novaspirit/pi-hosted/blob/master/docs/throttled.md) |
+|[Install and Setup Pi-Hole for Network-Wide Ad Block](https://github.com/novaspirit/pi-hosted/blob/master/docs/pi-hole.md) |
+|[Attach a container directly to local network (macvlan)](https://github.com/novaspirit/pi-hosted/blob/master/docs/macvlan_setup.md) |
 
 =======
 

docs/macvlan_setup.md

@@ -0,0 +1,200 @@
+# Attach a container directly to local network
+
+Sometimes it's required, or better, to connect a docker directly to your local network, so it have an IP given by your router (or your [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol) server).
+
+We can do so setting up a **macvlan** network in Portainer. It will allow a docker on that _lan_ to connect directly to your local network.
+
+
+## Preparation
+
+### What is required
+
+- Local IP network using [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) notation, [see below a simple explanation](#simple-cidr-explanation).
+- Your Router IP (or gateway)
+- A range of IPs not used by your router DHCP server
+- The interface used by the Raspberry Pi for internet
+- Modify Raspberry pi `/etc/network/interfaces` to add a custom route
+
+
+### Simple CIDR explanation
+
+CIDR is a compact representation of an IP address and its associated network mask, that will define the IP range available for a given subnet.
+
+An IPv4 address have a total of **32 bits** that we normally split in **4** groups of **8 bits**. The CIDR notation will define how many bits (from left to right) can't be changed. Let's see an example:
+
+Normally, our router will haven an IP like `192.168.0.1` and a mask of `255.255.255.0`. This means that the last group can have any number from `0` to `255`. As we can see, the last group can be changed within our subnet to any number, but all others has to be kept the same. This means that **3** groups of **8 bits** each have to be fixed, given a total of 24 bits fixed. The CIDR for this network will be `192.168.0.1/24`.
+
+Standard CIDR notations:
+
+|  IP START   |      IP END     |     MASK      | CIDR |
+|:-----------:|:---------------:|:-------------:|:----:|
+| 192.168.0.0 |  192.168.0.255  | 255.255.255.0 |  24  |
+| 192.168.0.0 | 192.168.255.255 |  255.255.0.0  |  16  |
+|   10.0.0.0  | 10.255.255.255  |   255.0.0.0   |   8  |
+
+The CIDR can also be used to identify a group of IPs within a subnet, for example: `192.168.0.8/29` will indicate an IP range from `192.168.0.8` to `192.168.0.15`. See table below to understand how many IPs you can have for each CIDR (up to 24):
+
+| CIDR | IPs | STARTS AT |
+|:----:|:---:|:----------|
+|  32  |  1  | Any IP (means a unique IP) |
+|  31  |  2  | Any even IP |
+|  30  |  4  | 0 , 4 , 8 , 12 , 16 , 20 , 24 , 28 , 32 , 36 , 40 , 44 , 48 , 52 , 56 , 60 , 64 , 68 , 72 , 76 , 80 , 84 , 88 , 92 , 96 , 100 , 104 , 108 , 112 , 116 , 120 , 124 , 128 , 132 , 136 , 140 , 144 , 148 , 152 , 156 , 160 , 164 , 168 , 172 , 176 , 180 , 184 , 188 , 192 , 196 , 200 , 204 , 208 , 212 , 216 , 220 , 224 , 228 , 232 , 236 , 240 , 244 , 248 , 252 |
+|  29  |  8  | 0 , 8 , 16 , 24 , 32 , 40 , 48 , 56 , 64 , 72 , 80 , 88 , 96 , 104 , 112 , 120 , 128 , 136 , 144 , 152 , 160 , 168 , 176 , 184 , 192 , 200 , 208 , 216 , 224 , 232 , 240 , 248 |
+|  28  | 16  | 0, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240 |
+|  27  | 32  | 0, 32, 64, 96, 128, 160, 192, 224 |
+|  26  | 64  | 0, 64, 128, 192 |
+|  25  | 128 | 0, 128 |
+|  24  | 256 | 0 |
+
+You can use a calculator [like this one](https://subnetcalculator.info/CidrCalculator) to help you with.
+
+
+### Local IP network in CIDR notation
+
+Connect to your raspberry pi via **ssh** (or directly) and type:
+
+```bash
+ip a
+```
+
+It will give you something similar to this:
+
+```text
+1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
+    link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
+    inet 127.0.0.1/8 scope host lo
+       valid_lft forever preferred_lft forever
+2: eth0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc mq state UP group default qlen 1000
+    link/ether aa:aa:aa:aa:aa:aa brd ff:ff:ff:ff:ff:ff
+    inet 192.168.0.70/24 brd 192.168.0.255 scope global eth0
+       valid_lft forever preferred_lft forever
+```
+
+Skip the interface `lo` as this will only point to your local machine and look for an `inet` value. In my case it is `192.168.0.70/24` and it is already in CIDR notation. Also, take note at the interface name which is the word just after the index (in this case `eth0`). If you have dockers running, you should get a bunch of `veth*` and `br-*` interfaces as well, you can ignore them. The interface will most likely be `eth0` for wired connection and `wlan0` for WiFi connection.
+
+
+### Finding the DHCP range used by your router
+
+As there are many routers with many different interfaces, I can't tell you how you will do it exactly. Normally you will find under **DHCP Settings** or **DHCP Server**, you need to search for **Start IP Address** and **End IP Address** or **Limit**. This will tell you which IPs your router is controlling.
+
+This is important as we need to configure our Portainer to lan to a range that is not used by our router, to avoid any conflict (we don't want them to give same IP to different devices).
+
+Once this is all done, we can start our implementation.
+
+
+## Configuring Portainer
+
+Within your local environment go to **Networks** and click in `Add network`.
+
+![](images/macvlan_NetworkList.png)
+
+In order to create a `macvlan` network, we need to networks, one for **Configuration** and other for **Creation**. It's a bit confusing, but that's how it is.
+
+
+### Configuration network
+
+First we will setup the **Configuration** network.
+
+![](images/macvlan_Configuration.png)
+
+Define a name (here I'm calling `macvlan_background`), in **Driver** select `macvlan`, make sure **Configuration** box is selected and enter you **Network Interface** name on **Parent network card** (in this case `eth0`.
+
+Next we will define our network **Subnet**, if your CIDR is 24 you can leave the last number `0`, in my case `192.168.0.0/24`. For **Gateway** enter your router IP address (here `192.168.0.1`.
+
+**IP range** box is where you will define the IP range your dockers may have, this should not conflict with your router DHCP server. In my case, my router DHCP server starts at `100` and finishes at `150`, so I can select any IP that doesn't clash with it. I will select the range `192.168.0.16` up to `192.168.0.31` which gives me **16** IPs to use. This represents CIDR 28 (see table above). In that instance, my **IP range** will be `192.168.0.16/28`. Pay attention at the starting IP, each CIDR code can start only at specifics IPs, so check table above.
+
+We will click in the button **add excluded IP** to add at least one IP, which I will use the last one on the group (`31` in this case). This IP will be used by the Raspberry Pi itself, as it needs an IP within this network to be able to communicate with the dockers. I've used `rpi_mcvlan=192.168.0.31/32`, the first part including the `=` is optional, the `/32` indicates that I just want to exclude that specific IP address and not a range (again using CIDR notation).
+
+We could have used `192.168.0.0/28` and excluded `192.168.0.15/32`. Note that we don't need to exclude the router's IP, however, any other address that you've defined as static on your router needs to be excluded here.
+
+I'm not configuring IPv6 in this tutorial, so I'll leave it blank.
+
+After that, you can click in **Create the network**.
+
+
+### Creation network
+
+Click again in **Add network** so we can create the Creation network.
+
+![](images/macvlan_Creation.png)
+
+Define a name (here I'm using `ExternalNetwork`), this is the network that you will attach your dockers to.
+
+Now select **Creation** box and select `macvlan_background` on **Configuration** drop-down menu.
+
+Enable **Enable manual container attachment** so we can add containers to this network manually.
+
+This is all for the creation network, just click in **Create the network**.
+
+
+## Connect a docker to this network
+
+I'll use as an example the Pi-Hole docker, but it could have been any one. Just be careful with **Stacks** as they have their own networks, _as I haven't tested it yet, I'm leaving it out of this tutorial for now._
+
+Go to your **Containers** and select the container you want to change. Once you've opened it, scroll all the way to the end that you will see **Connected networks** section.
+
+![](images/macvlan_JoinNetwork.png)
+
+Select `ExternalNetwork` for **Join a network** and click in **Join network**. If everything worked, you should see a local IP as shown on the image above.
+
+At this point, you can attach your dockers to this network and it will get an external IP address, however, the Raspberry Pi will not be able to connect to your docker, so we need to fix it.
+
+
+## Configuring Raspberry Pi to connect to macvlan network
+
+To connect your Raspberry Pi to your docker using macvlan, you need to add a new interface. This is done modifying the file `/etc/network/interfaces`.
+
+You will need to get the range of IPs that we want to route using CIDR. The easiest way of doing it, is using a [tool like this](https://ip2cidr.com/). This range should include all IPs that a docker should have, but not the IP that the Raspberry Pi will get. In our case, the range will be from `192.168.0.16` to `192.168.0.30` as IP `31` will be used by the Raspberry Pi.
+
+This range is represented by:
+
+```text
+192.168.0.16/29
+192.168.0.24/30
+192.168.0.28/31
+192.168.0.30/32
+```
+
+With that in hand, you can modify `/etc/network/interfaces` using any editor of your choice. If you are using WiFi, you need to add the following lines after the WiFi section, if you're using Ethernet, then add after Ethernet.
+
+```text
+    post-up ip link add macvlan-lan link eth0 type macvlan mode bridge
+    post-up ip addr add 192.168.0.31/32 dev macvlan-lan
+    post-up ip link set macvlan-lan up
+    post-up ip route add 192.168.0.16/29 dev macvlan-lan
+    post-up ip route add 192.168.0.24/30 dev macvlan-lan
+    post-up ip route add 192.168.0.28/31 dev macvlan-lan
+    post-up ip route add 192.168.0.30/32 dev macvlan-lan
+```
+
+You can change `macvlan-lan` name to anything you like, change `eth0` to the interface you're using and adjust all IPs accordingly. My file looks like this:
+
+```text
+iface eth0 inet static
+    address 192.168.0.70
+    netmask 255.255.255.0
+    gateway 192.168.0.1
+    #dns-nameservers 9.9.9.9 149.112.112.112
+
+    post-up ip link add macvlan-lan link eth0 type macvlan mode bridge
+    post-up ip addr add 192.168.0.31/32 dev macvlan-lan
+    post-up ip link set macvlan-lan up
+    post-up ip route add 192.168.0.16/29 dev macvlan-lan
+    post-up ip route add 192.168.0.24/30 dev macvlan-lan
+    post-up ip route add 192.168.0.28/31 dev macvlan-lan
+    post-up ip route add 192.168.0.30/32 dev macvlan-lan
+```
+
+For this configuration to apply, you need to reboot your Raspberry Pi. If you don't want to reboot, you can run the commands on your terminal without `post-up` part and using `sudo`, like this:
+
+```bash
+sudo ip link add macvlan-lan link eth0 type macvlan mode bridge
+sudo ip addr add 192.168.0.31/32 dev macvlan-lan
+sudo ip link set macvlan-lan up
+sudo ip route add 192.168.0.16/29 dev macvlan-lan
+sudo ip route add 192.168.0.24/30 dev macvlan-lan
+sudo ip route add 192.168.0.28/31 dev macvlan-lan
+sudo ip route add 192.168.0.30/32 dev macvlan-lan
+```
+
+Now it's all set. Your docker have an Local IP address and your Raspberry Pi can communicate to it.

docs/pi-hole.md

@@ -0,0 +1,117 @@
+# Install and setup instructions for Pi-Hole DNS Ad Blocker
+
+## Introduction
+
+[Pi-Hole](https://pi-hole.net/) is a network-wide **Ad Blocking** based on [DNS](https://en.wikipedia.org/wiki/Domain_Name_System) filter. It can also act as a [DHCP](https://en.wikipedia.org/wiki/Dynamic_Host_Configuration_Protocol) server _(not covered in this Doc)_ in case you need.
+
+![](https://i0.wp.com/pi-hole.net/wp-content/uploads/2018/12/dashboard.png?zoom=1.75&w=3840&ssl=1)
+
+There is 3 template options available:
+
+![](images/pi-hole_Template-Options.png)
+
+- **[Pi-Hole](#pi-hole-installation)**: It's a docker with Pi-Hole only
+- **[Pi-Hole DoH/DoT](#pi-hole-dohdot-installation)**: Docker built with both [DoH](https://en.wikipedia.org/wiki/DNS_over_HTTPS) (DNS over HTTPS) and [DoT](https://en.wikipedia.org/wiki/DNS_over_TLS) (DNS over TLS). _[Documentation In-Progress]_
+- **[Pi-Hole-Unbound](#pi-hole-unbound-installation)**: Docker built with [Unbound](https://nlnetlabs.nl/projects/unbound/about/) software integrated for self-hosted DNS server.
+
+## Pi-Hole Installation
+
+![](images/pi-hole_VanilaDeploy.png)
+
+Pi-Hole only default configuration from App Template are good and no action is required. Just click in deploy.
+
+It will map ports:
+
+- **53** -> For DNS queries (TCP/UDP)
+- **67** -> For DHCP server (UDP)
+- **1010** -> For Web interface HTTP (accessed with `http://<Raspberry IP>:1010/admin`)
+- **4443** -> For Web interface HTTPS (accessed with `https://<Raspberry IP>:4443/admin`)
+
+It will map:
+
+- **Configuration folder**: `/portainer/Files/AppData/Config/PiHole`
+- **DNS Settings**: `/portainer/Files/AppData/Config/PiHole/DNS`
+
+Once deployed go to [Post Installation](#post-installation) section.
+
+## Pi-Hole DoH/DoT Installation
+
+![](images/pi-hole_DoHDoTDeploy.png)
+
+It follows all the same configuration and ports as the [standard installation](#pi-hole-installation) and no further configuration is required. It uses a different mapped folder:
+
+- **Configuration folder**: `/portainer/Files/AppData/Config/PiHole_DoH-DoT`
+- **DNS Settings**: `/portainer/Files/AppData/Config/PiHole_DoH-DoT/DNS`
+
+Once deployed go to [Post Installation](#post-installation) section.
+
+## Pi-Hole-Unbound Installation
+
+![](images/pi-hole_UnboundDeploy.png)
+
+To install Pi-Hole with Unbound option, the following settings needs to be set:
+
+- **ServerIP** -> This is the IP of your Raspberry Pi, so docker can configure the DNS server properly
+- **TZ** -> Time zone setting so all logs are written in the correct time
+- **DNSSEC** -> Option to enable or disable [DNSSEC](https://en.wikipedia.org/wiki/Domain_Name_System_Security_Extensions), default configuration is Enabled.
+
+By default only ports **53** (DNS), **1010** (HTTP Web Interface), **4443** (HTTPS Web Interface) are opened.
+
+You can open the following ports for extra functionalities:
+
+- **22/TCP** -> Enable SSH connection to the docker _(not recommended)_
+- **67/UDP** -> Open port for DHCP Server
+
+To open extra ports, click in `Show advanced options` just above `Deploy the container` button and then click in `map additional port`. Enter Host Port first then Container Port after and select the protocol. The ports described above are for Container Port, you can use the same number or a different one on the host (although it's best to keep port 67 for DHCP).
+
+![](images/pi-hole_Ports.png)
+
+Once all variables are set and extra ports (if required) opened, deployed the container and go to [Post Installation](#post-installation) section.
+
+## Post Installation
+
+### Admin Password
+
+Once deployed, open the container logs, disable `Auto-refresh logs` so you can scroll freely and look for `Assigning random password: XXXXXXXX` to get the Admin password.
+
+![](images/pi-hole_LogsPassword.png)
+
+You can set a new password opening the Console through Portainer and typing `pihole -a -p` and enter the password when requested.
+
+You can find more commands to run [here](https://docs.pi-hole.net/core/pihole-command/).
+
+With the admin password, go to `http://<Raspberry IP>:1010/admin` to access Pi-Hole web interface and log in.
+
+### Setting Mainstream DNS
+
+Go to `Settings` and select `DNS` on top.
+
+![](images/pi-hole_SettingsDNS.png)
+
+On the left hand side you can select anyone of the know DNS providers or insert a custom one on the right hand side (_**Note: if you are using Unbound, the custom DNS is already configured properly**_).
+
+You can also set `Use Conditionnal Forwarding` in order for the Pi-Hole to ask your DHCP server the host name of the local IPs. For this to work, define your local network [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) (I've used 192.168.0.0/16 that covers all possible subnets within 192.168.x.x range), then insert the IP of your DHCP server (normally your router) and optionally a local domain name.
+
+![](images/pi-hole_SettingsDNS_CF.png)
+
+If you're having loop issues with your router, then you might want to disable this option.
+
+### Point your router or device to Pi-Hole
+
+As each router is different to configure, I'm not going to detail here how it's done. However, you can point your router DNS to Pi-Hole IP (Raspberry IP) and it will use it as the main DNS, blocking any request included on it's blacklist.
+
+Optionally, you can set each device to use a custom DNS and insert the IP of your Raspberry.
+
+You can also refer to [pi-hole router setup documentation](https://docs.pi-hole.net/routers/fritzbox/) for more information.
+
+### Adding more Ad lists
+
+You can add more lists through `Group Management` -> `Adlists`. Then just add the list you want to use.
+
+You can visit [The Big Blocklist Collection](https://firebog.net/) if you want to add more.
+
+## Configure Pi-Hole to get IP from the router
+
+Configuring Pi-Hole to have an IP given by the router is not required, but it can help depending on the configuration you use on your router. If you want to force any device to use Pi-Hole as a DNS server even if they directly define a different one, having an IP different from the Raspberry helps on the configuration.
+
+[See macvlan setup.](macvlan_setup.md)