A server next to the Pi-hole logo

Configure Pi-hole Upstream DNS Servers

  • Adam Douglas

For the most part Pi-hole makes things pretty straight forward to set settings. Whether you are more comfortable with the web interface or the command-line, it can be done with a little bit of work. Of course there is the assumption that the user understands quite a bit of knowledge or experience to make this all trivial to work with. Let’s explore what is an upstream DNS is and then the ways in which we can change the upstream DNS servers.

What is Upstream DNS Servers?

The domain name system or better known as DNS is like a phone book. Every time a request is made to go to for example, “adamsdesk.com” a lookup is made to the DNS server to determine the IP (Internet protocol) address in order to make the connection.

In this context, an upstream DNS server is just another DNS server that is used when a domain name cannot be resolved locally (e.g. Pi-hole). When a domain name cannot be resolved, this means there is no local record for the domain name with an IP address in order to direct where to make the connection to.


The following instructions were tested using the following.

  • Arch Linux Arm
  • Pi-hole v5.12
    • AdminLTE v5.12
    • FTL v5.15


  • Steps prefixed with a “$” (dollar sign) represents the CLI (command-line interface) prompt
  • Steps prefixed with a “#” (number sign) represents the CLI prompt with elevated user permissions (e.g. root)
  • The text after the “$” or “#” is to be entered at the CLI
  • Pi-hole is already installed and configured

Web Interface: Change Upstream DNS Servers

  1. Login to Pi-hole web interface (e.g. http://pi.hole).
  2. Click on the “Settings” in the menu.
  3. Click on the “DNS” tab at the top of page.
  4. Set or select the desired DNS provider.

    Choose one of the following methods.

    1. Select a provider under “Upstream DNS Servers”

      Make sure to select at least two per provider for redundancy for the desired group IPv4 or IPv6.

    2. Set a custom Upstream DNS Servers.

      Manually Enter IP address for Custom 1 (IPv4) and Custom 2 (IPv4) or Custom 1 (IPv6) and Custom 2 (IPv6). Make sure to the checkbox is checked next to the desired input fields.

  5. Click on the “Save” button at the bottom right of the page.

Manually: Change Upstream DNS Servers

Each DNS server address is configured within two files /etc/pihole/setupVars.conf and /etc/dnsmasq.d/01-pihole.conf. By default, Pi-hole will use Google’s DNS servers.

  1. Edit Pi-hole Setup Variables.
     # nano /etc/pihole/setupVars.conf
  2. Edit Dnsmasq configuration file.
     # nano /etc/dnsmasq.d/01-pihole.conf
  3. Restart Pi-hole DNS service for changes to take affect.
     # pihole restartdns

This is post 30 of 100, and is round 2 of the 100 Days To Offload challenge.

    • change topic
    • Change 100DaysToOffload message