qusal/salt/sys-pihole/README.md

# sys-pihole

Pi-hole DNS Sinkhole in Qubes OS.

## Table of Contents

* [Description](#description)
* [Installation](#installation)
* [Usage](#usage)
  * [Web interface](#web-interface)
  * [Torified Pi-Hole](#torified-pi-hole)
  * [Local DNS server](#local-dns-server)
  * [DNS issues after netvm restart](#dns-issues-after-netvm-restart)
* [Credits](#credits)

## Description

The package will create a standalone qube "sys-pihole". It blocks
advertisements and internet trackers by providing a DNS sinkhole. It is a drop
in replacement for sys-firewall.

The qube will be attached to the "netvm" of the "default_netvm", in other
words, if you are using Qubes OS default setup, it will use "sys-net" as the
"netvm", else it will try to figure out what is your upstream link and attach
to it.

## Installation

Pi-Hole commits and tags are not signed by individuals, but as they are done
through the web interface, they have GitHub Web-Flow signature. This is the
best verification we can get for Pi-Hole. If you don't trust the hosting
provider however, don't install this package.

- Top:
```sh
sudo qubesctl top.enable sys-pihole browser
sudo qubesctl --targets=tpl-browser,sys-pihole-browser,sys-pihole state.apply
sudo qubesctl top.disable sys-pihole browser
sudo qubesctl state.apply sys-pihole.appmenus
```

- State:
<!-- pkg:begin:post-install -->
```sh
sudo qubesctl state.apply sys-pihole.create
sudo qubesctl --skip-dom0 --targets=tpl-browser state.apply browser.install
sudo qubesctl --skip-dom0 --targets=sys-pihole state.apply sys-pihole.install
sudo qubesctl --skip-dom0 --targets=sys-pihole-browser state.apply sys-pihole.configure-browser
sudo qubesctl state.apply sys-pihole.appmenus
```
<!-- pkg:end:post-install -->

If you want to change the global preferences `updatevm` and `default_netvm`
and the per-qube preference `netvm` of all qubes from `sys-firewall` to
`sys-pihole`, run:
```sh
sudo qubesctl state.apply sys-pihole.prefs
```

## Usage

### Web interface

Pi-hole will be installed with these default settings:

- The DNS provider is Quad9 (filtered, DNSSEC)
- Steven Black's Unified Hosts List is included
- Query logging is enabled to show everything.

You can change the settings via the admin interface:
- URL: http://localhost/admin
- There is no password (access allowed only through localhost)

If you want to view statistics or manage the server through a GUI, open
`sys-pihole` or `sys-pihole-browser` desktop file `pihole-browser.desktop`
from Dom0. Addresses starting with `http` or `https` will be redirected
to `sys-pihole-browser`.

The browser separation from the server is to avoid browsing malicious sites
and exposing the browser to direct network on the same machine the server is
running. The browser qube is offline and only has access to the admin
interface. In other words, it has control over the server functions, if the
browser is compromised, it can compromise the server.

### Torified Pi-Hole

If you want to combine Pi-Hole with Tor, then you should reconfigure your
netvm chaining (will break tor's client stream isolation) as such:

- qube -> sys-pihole -> Tor-gateway -> sys-firewall -> sys-net

### Local DNS server

If you want sys-pihole to use itself to resolve DNS queries, enable the
service `local-dns-server` from Dom0 to sys-pihole:
```sh
qvm-features sys-pihole service.local-dns-server 1
```

Don't forget to restart sys-pihole after the changes.

Note that if Pi-hole as a problem the host will not not be able to reach the
internet for updates, syncing time etc.

### DNS issues after netvm restart

If you encounter problems with DNS after having upstream netvm route changes,
restart Pi-hole DNS from sys-pihole:
```sh
pihole restartdns
```

## Credits

- [Patrizio Tufarolo](https://blog.tufarolo.eu/how-to-configure-pihole-in-qubesos-proxyvm/)
- [Unman](https://github.com/unman/shaker/tree/main/pihole)