pihole [NethServer Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{page>stephdl_donate}}

===== Pihole (ads killer)=====
<wrap hi>Available for NS7</wrap>

Pi-hole is a Linux network-level advertisement and Internet tracker blocking application  which acts as a DNS sinkhole and optionally a DHCP server (even if it is workable, you could use the router of your network or the DHCP server of NethServer), intended for use on a private network. It is designed for use on embedded devices with network capability, such as the Raspberry Pi,but it can be used on other machines running Linux and cloud implementations.

Pi-hole has the ability to block traditional website advertisements as well as advertisements in unconventional places, such as smart TVs and mobile operating system advertisements.

nethserver-pihole relie on nethserver-docker, you will run a docker container either on the ''aeria'' network (experimental) on the ''macvlan'' network or on the ''aqua'' network (Recommended). You will just have to set in the DHCP server of your network that the DNS server is the IP of pihole (for ''aeria'' and ''macvlan'' network) or the NethServer (for ''aqua'' network)

====Maintainer====
Stephane de Labrusse at [[stephdl@de-labrusse.fr]]

====Installation====

1-You need to install my repository, [[:stephdl_repository|see how to do it]]

2-You can install pihole

  yum install nethserver-pihole --enablerepo=stephdl

===aqua===
if you have decided to use the ''aeria network'', please jump to the next [[pihole#aeria|chapter]]. If you want to use ''macvlan network'', please jump to the chapter [[pihole#macvlan|below]] 

''aqua'' is the network for all containers on NethServer, all containers can contact each others, the host can contact the container, it is fast and secure. You have no special network configuration to do but the hosts on your local network cannot contact directly the container of pihole. You have to set the DNS server of your host to the NethServer IP and set the container IP as the DNS server of your NethServer.

<WRAP center round tip 60%>
The aqua network got a cons, the DNS requests are seen from the NethServer, you cannot know which host is initiating the request 
</WRAP>

  * Go to the cockpit dashboard, set the IP of the primary DNS server to the IP ''172.28.45.1'' (default of the pihole container)
  * Once done we have to set the network of the pihole container, do: 

<file>
config setprop  docker piholeNetwork aqua
</file>
  * Then use NethServer as the DNS server of your network (by adding it manually in each host or by DHCP)

go to create the container, please jump to the next [[pihole#create_the_container|chapter]] 

===Macvlan===
if you have decided to use the ''aeria network'', please jump to the next [[pihole#aeria|chapter]] 

Macvlan is particuliar network, this is the documentation for explanation, please refer there to understand: https://github.com/NethServer/nethserver-docker/blob/master/README.rst#macvlan

<WRAP center round tip 60%>
You must have a bridge, here called ''br0'', if you have installed SAMBA AD, then it is already created. Else you can use the network panel to make it available.
</WRAP>


<file>
config setprop  docker macVlanGateway 192.168.1.1 macVlanLocalNetwork 192.168.1.0/24 macVlanNetwork 192.168.1.224/27 macVlanNic br0
signal-event nethserver-docker-update
</file>


- check macvlan is up : ''docker network ls''
- then assign ''macvlan'' to ''piholeNetwork'' and set the IP to ''piholeMacVlanIP'' (in macvlan range)


<file>
config setprop pihole piholeNetwork macvlan piholeMacVlanIP 192.168.1.234
</file>

go to create the container, please jump to the next [[pihole#create_the_container|chapter]] 

=== Aeria ===

if you have decided to use the ''macvlan network'' or ''aqua network'', please jump to the next [[pihole#create_the_container|chapter]] 

To create the AERIA network please review https://github.com/NethServer/nethserver-docker/blob/master/README.rst#aeria-network
<WRAP center round tip 60%>
You must have a bridge, here called ''br0'', if you have installed SAMBA AD, then it is already created. Else you can use the network panel to make it available.
</WRAP>


<file>
config setprop docker bridgeAeria br0
signal-event nethserver-docker-update
</file>

- check aeria is up : ''docker network ls''

- then assign ''aeria'' to piholeNetwork

''config setprop pihole piholeNetwork aeria''

go to create the container, please jump to the next [[pihole#create_the_container|chapter]] 

=== Create the container ===

review the pihole conf : ''config show pihole''


<file>
pihole=configuration
    DNS1=8.8.8.8    #upstream dns
    DNS2=8.8.4.4    #upstream dns
    mac=00:60:2f:0a:66:06    # once generated, it is static mac
    PhpMemoryLimit=512M
    password=admin  #web admin password
    piholeMacVlanIP=192.168.1.234
    piholeNetwork=macvlan
    timezone=UTC
</file>


- change the admin password (default is ''admin'')

By default the password is admin, you should change it obviously, once created with a password, you must destroy the container, change the password and create it again.

<file>
config setprop docker password azertyuiop
</file>


- Modify the upstream DNS of pihole following your needs (default is google DNS)

you can adjust to different DNS if you think they are faster or DNS with adult filtering if your want to protect your kids

as example I will use cleanbrowsing.org, decide what Family or Adult filter to use (https://cleanbrowsing.org/ip-address)

If you want to filter porn, set DNS1 and DNS2 to 


<file>
Family filter
    DNS1=185.228.168.168    #upstream dns
    DNS2=185.228.169.168    #upstream dns

Adult filter
    DNS1=185.228.168.10    #upstream dns
    DNS2=185.228.169.11    #upstream dns
</file>

set DNS1 and DNS2 accordingly

<file>
config setprop pihole DNS1 185.228.168.168 DNS2 185.228.169.168

</file>
or


<file>
config setprop pihole DNS1 185.228.168.10 DNS2 185.228.169.11
</file>

- trigger the event to create the container


<file>
signal-event nethserver-pihole-update
</file>

- The time depends of your internet bandwith

- check docker pihole is up : 

''docker ps''

''pihole status''

=== Modify the PHP CGI memory limit ===

The php memory limit for CGI is set to 512M, this should be good but when you browse the long-term data graphs you might need to increase it

<file>
config setprop pihole PhpMemoryLimit 1024M
signal-event nethserver-pihole-update
pihole upgrade
</file>
==== Documentation ====

Please RTFM: https://docs.pi-hole.net/

==== Where to start ====

  * for ''macvlan'' or ''aeria''
Once installed pihole is available at the ip of the container, to find it do ''pihole ip'' in the terminal, use the IP of the container in your browser, then log with the credential ''admin'' and the password set in the ''password'' esmith property

  * for ''aqua''

Once installed pihole is available at the https://pi.hole, then log with the credential ''admin'' and the password set in the ''password'' esmith property

====Making devices use Pi-hole====
To use Pi-Hole, make sure that your devices use Pi-Hole's IP address as their only DNS server. To accomplish this, there are generally 2 methods to make it happen:

  - In router's LAN DHCP settings, set Pi-Hole's IP address as the only DNS server available for connected devices.
  - Manually configure each device to use Pi-Hole's IP address as their only DNS server.

Note: Some routers (or even ISPs) do not allow to change LAN DNS settings, so you might want to disable router's DHCP server and use the NetHServer built in DHCP server instead.
More information about making other devices use Pi-Hole can be found at [[https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245|upstream documentation.]]

<WRAP center round important 60%>
Some router can still serve DNS request when the IPV6 is enabled, you should turn it off because we do not use yet with NethServer. I mean the livebox4 of orange for example
</WRAP>

==== Pihole wrapper ====

do ''pihole'' in your terminal to get help

pihole facilities wrapper to docker command


    pihole ip : find the IP of pihole given by your dhcp server for aeria network
    pihole status : retrieve the status of pihole container
    pihole env : retrieve all the environment vars of the container
    pihole bash : start a shell inside the container
    pihole start: Start the pihole container
    pihole stop: Stop the pihole container
    pihole destroy: Delete the pihole container
    pihole build: Delete then create the pihole container
    pihole upgrade: Upgrade docker image, delete then create the pihole container
    pihole ps: Container information
    pihole log: Display the error log of the container

====Upgrade====

As many docker container the upgrade of a container means you must destroy it before

''pihole upgrade''

Upgrade the docker image, delete then build again the container

====Backup====
All the container data are in ''/var/lib/pihole'', it is included in the backup-data of your NethServer if used.
====Bugs====

Please raise Issues on [[https://github.com/stephdl/dev/issues|github]]

{{tag>module}} {{tag>stephdl}}