Skip to content

docs: fix instructions for disabling systemd-resolved port 53 for fedora (still compatible with Ubuntu) #1860

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
LizenzFass78851 wants to merge 1 commit into from
Closed

docs: fix instructions for disabling systemd-resolved port 53 for fedora (still compatible with Ubuntu) #1860

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,10 +186,10 @@ Here is a rundown of other arguments for your docker-compose / docker run.
### Installing on Ubuntu or Fedora

Modern releases of Ubuntu (17.10+) and Fedora (33+) include [`systemd-resolved`](http://manpages.ubuntu.com/manpages/bionic/man8/systemd-resolved.service.8.html) which is configured by default to implement a caching DNS stub resolver. This will prevent pi-hole from listening on port 53.
The stub resolver should be disabled with: `sudo sed -r -i.orig 's/#?DNSStubListener=yes/DNSStubListener=no/g' /etc/systemd/resolved.conf`.
The stub resolver should be disabled with: `sudo sh -c 'mkdir -p /etc/systemd/resolved.conf.d && printf "[Resolve]\nDNSStubListener=no\n" | tee /etc/systemd/resolved.conf.d/no-stub.conf'`.
Comment thread
yubiuser marked this conversation as resolved.

This will not change the nameserver settings, which point to the stub resolver thus preventing DNS resolution. Change the `/etc/resolv.conf` symlink to point to `/run/systemd/resolve/resolv.conf`, which is automatically updated to follow the system's [`netplan`](https://netplan.io/):
`sudo sh -c 'rm /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'`.
This will not change the nameserver settings, which point to the stub resolver thus preventing DNS resolution. Change the `/etc/resolv.conf` symlink to point to `/run/systemd/resolve/resolv.conf`, which is automatically updated to follow the ubuntu system's [`netplan`](https://netplan.io/) or fedora system's [`sysconfig`](https://docs.fedoraproject.org/en-US/fedora-coreos/sysconfig-network-configuration):
`sudo sh -c 'rm -f /etc/resolv.conf && ln -s /run/systemd/resolve/resolv.conf /etc/resolv.conf'`.
After making these changes, you should restart systemd-resolved using `systemctl restart systemd-resolved`.

Once pi-hole is installed, you'll want to configure your clients to use it ([see here](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245)). If you used the symlink above, your docker host will either use whatever is served by DHCP, or whatever static setting you've configured. If you want to explicitly set your docker host's nameservers you can edit the netplan(s) found at `/etc/netplan`, then run `sudo netplan apply`.
Expand All @@ -208,6 +208,13 @@ network:
version: 2
```

For fedora users, you can run the following commands to edit the sysconfig(s) found at `/etc/NetworkManager/system-connections` via nmcli.

Example sysconfig nmcli commands:

@yubiuser yubiuser Jul 12, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if we should have instructions how to set Pi-hole as the DNS for the host at all. While this is a valid configurations, the host's DNS will break if Pi-hole is not running.

@LizenzFass78851 LizenzFass78851 Jul 12, 2025

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For Ubuntu's netplan, there is already a similar example of how to use Pihole as a system DNS server in the operating system:

docker-pi-hole/README.md

Lines 195 to 209 in ee0d04f

Once pi-hole is installed, you'll want to configure your clients to use it ([see here](https://discourse.pi-hole.net/t/how-do-i-configure-my-devices-to-use-pi-hole-as-their-dns-server/245)). If you used the symlink above, your docker host will either use whatever is served by DHCP, or whatever static setting you've configured. If you want to explicitly set your docker host's nameservers you can edit the netplan(s) found at `/etc/netplan`, then run `sudo netplan apply`.
Example netplan:
```yaml
network:
ethernets:
ens160:
dhcp4: true
dhcp4-overrides:
use-dns: false
nameservers:
addresses: [127.0.0.1]
version: 2
```

Therefore, the additionall instructions for set Pihole as a DNS server for the operating system for Fedora users.

@yubiuser yubiuser Jul 12, 2025

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see where you'e coming from. This is a more general discussion. (I think I meant to suggest to also move the Ubuntu part to the docs). Maybe @pi-hole/docker-maintainers have an opinion

1. `nmcli connection add type ethernet ifname ens160 con-name ens160-night autoconnect yes`
2. `nmcli connection modify ens160-night ipv4.method auto ipv4.ignore-auto-dns yes ipv4.dns "127.0.0.1"`
3. `nmcli connection up ens160-night`

Note that it is also possible to disable `systemd-resolved` entirely. However, this can cause problems with name resolution in vpns ([see bug report](https://bugs.launchpad.net/network-manager/+bug/1624317)).\
It also disables the functionality of netplan since systemd-resolved is used as the default renderer ([see `man netplan`](http://manpages.ubuntu.com/manpages/bionic/man5/netplan.5.html#description)).\
If you choose to disable the service, you will need to manually set the nameservers, for example by creating a new `/etc/resolv.conf`.
Expand Down