Skip to content

Updated Unifi router instructions #1259

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

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Updated Unifi router instructions #1259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c38cc46
chore: added updated OS info
legoraft Jul 4, 2025
158d7a8
feat: changed unifi ipv4 tutorial to most recent version
legoraft Jul 4, 2025
944bd07
feat: changed WAN steps and added interface info
legoraft Jul 4, 2025
3aafdbc
chore: removed unused usg dhcp image
legoraft Jul 4, 2025
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
Binary file removed docs/images/routers/usg-lan-dhcp.png
View file
Open in desktop
Binary file not shown.
Binary file added docs/images/routers/usg-lan-dns.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/routers/usg-lan-protocol.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 14 additions & 4 deletions docs/routers/ubiquiti-usg.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
This guide was developed using a Ubiquiti Cloud Key v2 with UniFi Network v7.1.61. Following the first method below will have you adding your Pi-hole as a DNS server for all devices on your LAN. Following the second method below will have DNS queries route through your USG and then to your Pi-hole. Either option is valid, depending on your specific requirements, but it is recommended to choose one or the other - not both.
This guide was updated using a Ubiquiti Cloud Gateway Ultra with UniFi Network 9.2.87. Following the first method below will have you adding your Pi-hole as a DNS server for all devices on your LAN. Following the second method below will have DNS queries route through your gateway and then to your Pi-hole. Either option is valid, depending on your specific requirements, but it is recommended to choose one or the other - not both.

!!! note
While this guide attempts to cover both IPv4 and IPv6, your mileage may vary.
Expand Down Expand Up @@ -34,16 +34,26 @@ Go to **Settings** --> **Networks** and click on the Network line that you want

![Screenshot of USG LAN](../images/routers/usg-lan.png)

Under **DHCP**, in the DHCP Server Management section click "Show options" to reveal the **DHCP DNS Server** section. Check the **Enable** box and enter your Raspi's IPv4 address here.
Make sure you are in the IPv4 section of the settings (indicated at the top):

![Screenshot of USG LAN DHCP settings](../images/routers/usg-lan-dhcp.png)
![Screenshot of USG LAN protocol switch](../images/routers/usg-lan-protocol.png)

Toggle **Advanced** to "Manual" and scroll down to the DNS server section. Uncheck the **Auto** box and enter your Raspi's IPv4 address here.

![Screenshot of USG LAN DNS settings](../images/routers/usg-lan-dns.png)

!!! note
This part of the tutorial hasn't been updated to the most recent version. You have to switch to the IPv6 section and can enter a DNS server there.

Scroll down to **IPv6**, and under the **DHCPv6/RDNSS DNS Control** section, uncheck **Auto** if it's enabled and enter Raspi's IPv6 address here. Click **Apply Changes** to have the settings persistently saved.

![Screenshot of USG LAN DHCPv6 settings](../images/routers/usg-lan-dhcpv6.png)

All client devices on your network should now automatically be configured with a single IPv4 and single IPv6 address for DNS resolution. If you don't see your client devices update quickly enough, you *can* toggle Wi-Fi off/on or disconnect the Ethernet cable for a couple of seconds and then reconnect it.

!!! note
The default pi-hole behavior (local requests), doesn't work if you have multiple VLANs. You should switch to another [interface](../ftldns/interfaces.md).
Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
The default pi-hole behavior (local requests), doesn't work if you have multiple VLANs. You should switch to another [interface](../ftldns/interfaces.md).
The default Pi-hole interface binding behavior ('Allow only local requests'), doesn't work if you have multiple VLANs. You should switch to another [interface](../ftldns/interfaces.md).

I think it does not work with local request only as all request for VLANs go to the router first. Instead of writing

switch to another [interface]

It might be better to suggest directly "Respond only on interace XXX"


### Method 2: Using your Pi-hole as a resolve for your USG

If you'd rather have your USG forward all DNS traffic to Pi-hole, you can complete this *alternative* step. Doing so will have DNS queries taking the following path:
Expand All @@ -59,6 +69,6 @@ Log into your Unifi Cloud Key. Go to **Settings** -> **Internet**. Click on the

![Screenshot of USG WAN](../images/routers/usg-wan.png)

Under **Advanced**, in the DNS Server section uncheck the Auto box and add your Raspi's IPv4 address. This allows your USG to use Pi-hole for all DNS lookups. Click **Apply Changes** to have the settings persistently saved.
Toggle **Advanced** to "Manual". In the DNS Server section uncheck the Auto box and add your Raspi's IPv4 address. This allows your USG to use Pi-hole for all DNS lookups. Click **Apply Changes** to have the settings persistently saved.

![Screenshot of USG WAN Advanced settings](../images/routers/usg-wan-advanced.png)