Block ads on all your devices: 4 solutions for a Linux VPS

Install AdGuard Home on your Linux VPS

This installation uses the official AdGuard Home Docker image. If Docker is not installed on your VPS yet, start with our Install Docker on Linux guide.

We will begin with a deliberately private configuration: DNS, the setup wizard and the administration panel will only be reachable from the VPS. This lets you finish the configuration without exposing a DNS resolver to the Internet.

Create the persistent AdGuard Home directories:

mkdir -p /opt/adguardhome/work /opt/adguardhome/conf
cd /opt/adguardhome

Then create compose.yaml:

cat > compose.yaml <<'EOF'
services:
  adguardhome:
    container_name: adguardhome
    image: adguard/adguardhome:latest
    ports:
      - "127.0.0.1:53:53/tcp"
      - "127.0.0.1:53:53/udp"
      - "127.0.0.1:3000:3000/tcp"
      - "127.0.0.1:8081:80/tcp"
    volumes:
      - "./work:/opt/adguardhome/work"
      - "./conf:/opt/adguardhome/conf"
    restart: unless-stopped
EOF

Start the container:

docker compose up -d
docker compose ps

On the first launch, AdGuard Home opens its setup wizard on port 3000. Because that port is bound to 127.0.0.1, open an SSH tunnel from your computer:

ssh -L 3000:127.0.0.1:3000 root@VPS_IP

Keep this SSH connection open, then browse to http://127.0.0.1:3000/.

Complete the setup wizard

The wizard first asks which interfaces and ports to use. With the Compose file above, you can keep:

• Admin Web interface: all interfaces, port 80.
• DNS server: all interfaces, port 53.

Those choices apply inside the container. On the VPS itself, Docker still publishes DNS only on 127.0.0.1:53 and the Web interface only on 127.0.0.1:8081.

You can keep the proposed upstream DNS servers to get started. If you prefer to reuse the resolvers already used by the VPS, enter their real IP addresses later under Settings > DNS settings > Upstream DNS servers. Do not use 127.0.0.53 from inside the container.

Create your administrator username and a strong password, then finish the wizard.

After setup, the main panel listens on port 80 inside the container. Open a new tunnel:

ssh -L 8081:127.0.0.1:8081 root@VPS_IP

You can now open http://127.0.0.1:8081/ and sign in with the account you created in the wizard.

Check that filtering works

If dig is not installed on your VPS yet, install it and query AdGuard Home directly:

apt update
apt install -y dnsutils
dig @127.0.0.1 pi-hole.net +short
dig @127.0.0.1 doubleclick.net +short

The first query should return a normal IP address. With the default filters currently enabled, doubleclick.net is blocked and returns 0.0.0.0.

You can confirm the result in Query Log. The dashboard also shows total queries, blocked domains and the most active clients.

Let your devices use AdGuard Home

The Compose file deliberately keeps DNS on 127.0.0.1 during installation. Once AdGuard Home is working, choose the access method that fits your devices:

• Classic DNS: publish port 53 on the VPS IPv4 address only after restricting the firewall to authorized source IP addresses.
• DoH, DoT or DoQ: configure encryption with a domain name and TLS certificate. This is usually the most convenient choice for phones and devices that often change networks.
• Private network: keep port 53 on a private address if you use WireGuard or another VPN.

Port 3000 is no longer needed after the setup wizard, so you can remove that mapping from the Compose file.

What if you prefer DoH, DoT or DoQ?

AdGuard Home can also serve encrypted DNS natively. In practice, DoH uses HTTPS, DoT uses a dedicated TLS connection and DoQ uses QUIC. This is useful when you want to use your DNS outside your VPN, but it requires a domain name pointing to the VPS and a valid TLS certificate.

In Settings > Encryption settings, enable encryption and provide the domain name, certificate and private key. Only expose the corresponding ports once this configuration is complete.

AdGuard Home commonly uses port 443 for DoH and port 853 for DoT/DoQ. If you choose this mode, publish only the protocols you actually need and keep an appropriate access policy. A publicly reachable encrypted DNS service is still an Internet service that needs to be administered accordingly.

If you do not want to expose any DNS service publicly, private VPN + private port 53 remains an excellent option. If you prefer not to install a VPN on your devices, DoH or DoT lets you use AdGuard Home directly with encrypted DNS.

If port 53 is already in use

On a standard Ubuntu installation, this 127.0.0.1 binding can coexist with systemd-resolved. If Docker still reports that the port is already allocated, identify what is listening before changing the system:

ss -lntup | grep ':53'

Do not disable a system resolver blindly. Check the exact address it is bound to first and adjust your setup only if necessary.

Update AdGuard Home

Persistent data is stored in /opt/adguardhome/work and /opt/adguardhome/conf. To pull a newer version of the official image:

cd /opt/adguardhome
docker compose pull
docker compose up -d

The compose.yaml file and the two persistent directories are enough to preserve the installation when the container is recreated. Back up /opt/adguardhome before major changes.

Install Technitium DNS Server on your Linux VPS

This installation uses the official Technitium DNS Server Docker image. If Docker is not installed on your VPS yet, start with our Install Docker on Linux guide.

We will initially bind both DNS and the Web console to 127.0.0.1. This lets you finish the setup and verify filtering without publishing a DNS resolver on the Internet.

Create the Technitium folders and a random administrator password:

mkdir -p /opt/technitium-dns/config /opt/technitium-dns/logs
cd /opt/technitium-dns
printf 'TECHNITIUM_PASSWORD=%s\n' "$(openssl rand -hex 18)" > .env
chmod 600 .env

Then create compose.yaml:

cat > compose.yaml <<'EOF'
services:
  dns-server:
    container_name: technitium-dns
    hostname: dns-server
    image: technitium/dns-server:latest
    ports:
      - "127.0.0.1:5380:5380/tcp"
      - "127.0.0.1:53:53/udp"
      - "127.0.0.1:53:53/tcp"
    environment:
      DNS_SERVER_DOMAIN: "dns.example"
      DNS_SERVER_ADMIN_PASSWORD: "${TECHNITIUM_PASSWORD}"
      DNS_SERVER_LOG_FOLDER_PATH: "/var/log/technitium/dns"
    volumes:
      - "./config:/etc/dns"
      - "./logs:/var/log/technitium/dns"
    restart: unless-stopped
    sysctls:
      net.ipv4.ip_local_port_range: "1024 65535"
EOF

dns.example is only used here as the server identifier. If you later configure DoH, DoT or DoQ with a real DNS name, replace it with the actual domain name you use.

Start the container:

docker compose up -d
docker compose ps

The Technitium Web console listens on port 5380. DNS port 53 is still reachable only from the VPS at this stage.

Connect to the Web console

From your computer, open an SSH tunnel:

ssh -L 5380:127.0.0.1:5380 root@VPS_IP

Keep that SSH connection open, then browse to http://127.0.0.1:5380/. The initial username is admin.

To display the password generated during the first startup:

cd /opt/technitium-dns
grep '^TECHNITIUM_PASSWORD=' .env | cut -d= -f2-

Log in with that password. DNS_SERVER_ADMIN_PASSWORD is only used to initialize the account when no Technitium configuration exists yet. If you later change the password from the Web console, the .env file will no longer be its source of truth.

Enable an ad-blocking list

In the Technitium console, open Settings > Blocking. Blocking itself is enabled by default, but a fresh installation does not yet contain a large external blocklist.

Under Quick Add, choose Default, then click Save Settings. Technitium adds its default blocklist and downloads it automatically. You can add more lists later if you actually need them, but stacking millions of domains for no reason only increases memory usage.

The recommended default blocking type is NX Domain. This means a blocked domain does not necessarily return 0.0.0.0: the server instead answers that the domain does not exist.

Verify DNS filtering

If dig is not available yet, install dnsutils first:

apt update
apt install -y dnsutils

Then query a normal domain and an advertising domain:

dig @127.0.0.1 pi-hole.net +short
dig @127.0.0.1 doubleclick.net +noall +answer +comments

The first command should return a normal IP address. For a blocked domain, look for status: NXDOMAIN and EDE: 15 (Blocked) in the second response. EDE means Extended DNS Error: here, this code indicates that a DNS rule blocked the response. If the lists change and this example is no longer blocked, test another advertising domain present in your list.

The dashboard then lets you monitor queries, recursive answers, cache activity, blocked domains and clients.

Let your devices use Technitium

The Compose file deliberately keeps DNS on 127.0.0.1 during installation. After validation, choose one of the three access methods described later in this guide: firewall-restricted classic DNS, DoH/DoT/DoQ, or a private network.

If you make Technitium reachable through classic DNS, also check the recursion ACLs under Settings > Recursion so that only authorized addresses or networks can use it. For phones and mobile devices, DoH or DoT is usually more convenient than a firewall rule based on an IP address that may change.

What about DoH, DoT or DoQ?

Technitium can natively provide all three protocols. DoH carries DNS through HTTPS, DoT uses a dedicated TLS connection and DoQ uses QUIC. Enable them under Settings > Optional Protocols with a real domain name and a valid TLS certificate.

In Docker, the usual ports are 443/tcp and 443/udp for DoH, then 853/tcp and 853/udp for DoT and DoQ. Do not publish these ports until TLS and your access rules are configured.

If you want to expose nothing publicly, private VPN + private port 53 remains very easy to secure. Otherwise, Technitium’s native DoH or DoT support lets you use the server without a VPN.

If port 53 is already in use

This 127.0.0.1 binding can coexist with systemd-resolved when it only listens on its reserved local DNS addresses. If Docker still reports a conflict, first identify the exact address already in use:

ss -lntup | grep ':53'

Do not disable the system resolver until you have identified the actual conflict.

Update Technitium

Configuration is persisted in /opt/technitium-dns/config and logs in /opt/technitium-dns/logs. To update the official image:

cd /opt/technitium-dns
docker compose pull
docker compose up -d

Back up /opt/technitium-dns before major changes. The Web console also provides Backup Settings for exporting the DNS configuration.

Install Blocky on your Linux VPS

Blocky is mainly configured through a YAML file. This installation uses the official Docker image published by the project. If Docker is not installed yet, start with our Install Docker on Linux guide.

We will first publish DNS and the API only on 127.0.0.1. Once the installation is validated, you can choose firewall-restricted classic DNS, DoH/DoT, or a private network.

Create the Blocky directory:

mkdir -p /opt/blocky
cd /opt/blocky

Then create config.yml:

cat > config.yml <<'EOF'
upstreams:
  groups:
    default:
      - 1.1.1.1
      - 9.9.9.9
blocking:
  denylists:
    ads:
      - https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
  clientGroupsBlock:
    default:
      - ads
ports:
  dns: 53
  http: 4000
prometheus:
  enable: true
EOF

The two addresses under upstreams are example public resolvers. You can replace them with the resolvers you prefer, including the real addresses of the DNS servers already used by your VPS. The denylists section, where blocklists are declared, uses the StevenBlack list, which is also used in Blocky’s official documentation.

Now create compose.yaml:

cat > compose.yaml <<'EOF'
services:
  blocky:
    container_name: blocky
    image: ghcr.io/0xerr0r/blocky:latest
    ports:
      - "127.0.0.1:53:53/tcp"
      - "127.0.0.1:53:53/udp"
      - "127.0.0.1:4000:4000/tcp"
    environment:
      TZ: "America/New_York"
    volumes:
      - "./config.yml:/app/config.yml:ro"
    restart: unless-stopped
EOF

Start Blocky:

docker compose up -d
docker compose ps

The container should become healthy after the lists are loaded and the upstream resolvers are checked.

Validate the configuration and filtering

Blocky includes a configuration validation command. Use it to catch YAML errors before troubleshooting anything else:

docker exec blocky /app/blocky validate --config /app/config.yml

The output should confirm that the configuration is valid.

If dig is not installed yet, add dnsutils, then test a normal domain and an advertising domain:

apt update
apt install -y dnsutils
dig @127.0.0.1 pi-hole.net +short
dig @127.0.0.1 doubleclick.net +short

The first command should return a normal IP address. With the list used here, doubleclick.net is currently blocked and returns 0.0.0.0.

You can also check the blocking state through the local API:

curl http://127.0.0.1:4000/api/blocking/status

An active installation returns {"enabled":true}.

What is port 4000 for?

Blocky does not include a large administration dashboard like Pi-hole, AdGuard Home or Technitium. Port 4000 mainly serves its REST API and Prometheus metrics.

In this configuration it therefore remains deliberately bound to 127.0.0.1. For example, you can confirm that Prometheus data is available with:

curl http://127.0.0.1:4000/metrics | head

You do not need to open this port to the Internet to use Blocky as your DNS server.

Let your devices use Blocky

The Compose file deliberately keeps DNS on 127.0.0.1 during installation. Once Blocky is working, you can publish port 53 only to authorized IP addresses, configure its DoH/DoT server, or keep DNS on a private network.

Blocky is mainly aimed at users who are comfortable with configuration files. If your priority is a simple setup across several phones and PCs, AdGuard Home remains the better fit thanks to its interface and built-in encrypted protocols.

What about DoH or DoT?

Blocky can also serve DNS-over-HTTPS (DoH), where DNS queries travel through HTTPS, and DNS-over-TLS (DoT), where they use a dedicated TLS connection. On a public VPS, however, this needs more care than a private DNS port because Blocky’s HTTP/HTTPS services also expose its REST API, an interface intended for tools and scripts, along with metrics and diagnostic functions.

If you want to provide public DoH, keep Blocky behind a trusted reverse proxy and expose only the DNS path you actually need, usually /dns-query. If you prefer to expose nothing publicly, simply keep DNS on the private WireGuard IP.

Change the configuration and update Blocky

After editing config.yml, validate it and restart the container:

cd /opt/blocky
docker exec blocky /app/blocky validate --config /app/config.yml
docker compose restart

To update the official image:

cd /opt/blocky
docker compose pull
docker compose up -d

Your configuration remains in /opt/blocky/config.yml. Blocky also refreshes remote lists periodically, so you do not need to manually download the blocklist again for every update.

Install Pi-hole on your Linux VPS

This installation uses the official Pi-hole Docker image. If Docker is not installed on your VPS yet, start with our Install Docker on Linux guide.

We will first bind Pi-hole only to 127.0.0.1. This lets you verify the installation without exposing a recursive DNS service to the Internet. After validation, you can choose firewall-restricted classic DNS, add a DoH/DoT component, or use a private network.

Create the Pi-hole directory and a random administration password:

mkdir -p /opt/pihole/etc-pihole
cd /opt/pihole
printf 'PIHOLE_PASSWORD=%s\n' "$(openssl rand -hex 18)" > .env
chmod 600 .env

Now create compose.yaml:

cat > compose.yaml <<'EOF'
services:
  pihole:
    container_name: pihole
    image: pihole/pihole:latest
    ports:
      - "127.0.0.1:53:53/tcp"
      - "127.0.0.1:53:53/udp"
      - "127.0.0.1:8080:80/tcp"
    environment:
      TZ: "America/New_York"
      FTLCONF_webserver_api_password: "${PIHOLE_PASSWORD}"
      FTLCONF_dns_listeningMode: "ALL"
    volumes:
      - "./etc-pihole:/etc/pihole"
    restart: unless-stopped
EOF

Pi-hole requires FTLCONF_dns_listeningMode: "ALL" when it runs on Docker’s default bridge network, the private virtual network Docker creates for containers. This does not make your DNS public: in this configuration Docker still publishes the DNS ports only on the VPS loopback address 127.0.0.1.

Start Pi-hole:

docker compose up -d
docker compose ps

On the first start, Docker downloads the image and Pi-hole initializes its lists. After a short while, docker compose ps should report the container as healthy.

You can also check the DNS service directly:

docker exec pihole pihole status

The important lines should show that FTL, Pi-hole’s DNS engine, is listening on port 53 and that blocking is enabled.

Open the Web interface without exposing the administration port

The Web interface is deliberately bound to 127.0.0.1:8080. From your computer, open an SSH tunnel to the VPS:

ssh -L 8080:127.0.0.1:8080 root@YOUR_VPS_IP

Keep that SSH connection open, then visit http://127.0.0.1:8080/admin/ in your browser.

To display the password generated during installation:

cd /opt/pihole
grep '^PIHOLE_PASSWORD=' .env | cut -d= -f2-

Use that password on the Pi-hole login page. The dashboard then lets you follow queries, blocked domains, clients and filtering lists.

Check that blocking works

If dig is not available on your VPS yet, install it and send two queries directly to Pi-hole:

apt update
apt install -y dnsutils
dig @127.0.0.1 pi-hole.net +short
dig @127.0.0.1 doubleclick.net +short

The first command should return a normal IP address. With the current default blocklists, doubleclick.net is blocked and returns 0.0.0.0. If a list changes later, you can always confirm the result from Query Log in the Pi-hole interface.

Let your devices use Pi-hole

The Compose file deliberately keeps DNS on 127.0.0.1 during installation. After validation, there are three options:

• Classic DNS: publish port 53 on the VPS IPv4 address only for source addresses allowed by your firewall.
• Encrypted DNS: add a DoH/DoT component in front of Pi-hole, because Pi-hole does not provide these protocols natively.
• Private network: keep DNS on a private address reachable through WireGuard or another VPN.

That extra layer for encrypted DNS is exactly why Pi-hole is less attractive than our AdGuard Home recommendation on a VPS.

Update Pi-hole

With Docker, updating remains straightforward:

cd /opt/pihole
docker compose pull
docker compose up -d

The /opt/pihole/etc-pihole directory keeps your configuration and data across container recreations. /opt/pihole/.env contains the administration password, so keep that file protected and do not share it.

Which address should you enter?

If you use classic DNS, enter the public IPv4 address of your VPS, for example 203.0.113.10. Port 53 must then be reachable over UDP and TCP, the two transports used by classic DNS.

Do not leave port 53 open to the whole Internet. Restrict it in your firewall to the addresses or networks that are allowed to use it. On a fixed Internet connection, for example, you can allow only your current public IP address.

The Compose files in this guide deliberately start on 127.0.0.1. If you choose classic DNS, replace only the two DNS mappings with the actual public IPv4 address of your VPS, for example:

ports:
  - "203.0.113.10:53:53/tcp"
  - "203.0.113.10:53:53/udp"

Then apply the change with docker compose up -d, but only after the firewall restrictions are in place.

If your public address changes often, that restriction becomes less convenient. Mobile 4G/5G source addresses also change regularly, so DoH/DoT or WireGuard are better suited there.

If you use DoH or DoT, you will usually enter a name such as dns.example.com instead of the raw IP address. That name must point to the VPS and the service must have a valid TLS certificate.

Finally, if your DNS remains deliberately private on an address such as 10.66.66.1, your devices must join that private network, for example through WireGuard.

Windows 10 and Windows 11: simply change the DNS server

On Windows, no additional software is required to use classic DNS.

Open Settings > Network & Internet, select your Wi-Fi or Ethernet connection and open its properties. Depending on your Windows version, look for DNS server assignment or Edit IP settings, choose Manual, then enable IPv4.

Under Preferred DNS, enter your VPS address:

203.0.113.10

Leave the secondary DNS field empty, or use a second filtering DNS server that you control. If you enter an ordinary public resolver as the secondary server, some requests may bypass your filtering.

On Windows 11, you can also enable DNS over HTTPS if your server provides DoH. Windows 10 does not expose this DoH setting directly in the same interface.

Then check which DNS server is actually being used:

nslookup pi-hole.net
nslookup doubleclick.net

The Server line should point to your DNS server. Depending on the software, a blocked domain may return 0.0.0.0 or NXDOMAIN.

Android: use built-in Private DNS when DoT is available

Android includes a Private DNS setting that works on Wi-Fi and mobile data. It uses DoT, so your server must provide DNS-over-TLS.

Open Settings > Network & Internet > Private DNS. The exact path may vary slightly by manufacturer. Choose Private DNS provider hostname, then enter only your server name, for example:

dns.example.com

Do not enter https:// and do not enter only the IP address: Android expects the hostname of the DoT server here.

AdGuard Home and Technitium can provide DoT directly. Blocky can also serve DoT when configured for it. Pi-hole needs an additional component or a different method.

If you prefer DoH or want to manage DNS through an app, Rethink DNS is an open-source alternative. Its DNS mode can send requests to a user-selected DoH or DoT resolver. Add the DoH URL or DoT hostname of your own server.

For AdGuard Home, Android’s built-in Private DNS setting remains the simplest route once DoT is enabled on the VPS.

iPhone and iPad: native DNS settings for Wi-Fi

For a Wi-Fi network, iOS and iPadOS let you change the DNS server without installing an application.

Open Settings > Wi-Fi, tap the information button next to the connected network, then Configure DNS > Manual > Add Server.

Enter the IPv4 address of your VPS, for example:

203.0.113.10

Remove the old DNS servers from that configuration if you want to make sure requests use your filtering DNS, then save.

This setting applies to that configured Wi-Fi network. To apply encrypted DNS on 4G/5G and other networks too, DNSecure is an open-source app dedicated to DoH and DoT on iOS and iPadOS.

In DNSecure, add your own DoH or DoT server, enable Use This Server, then select DNSecure in the iOS or iPadOS DNS settings. Encrypted DNS then applies system-wide rather than only in Safari.

TVs, consoles and other devices

If the device lets you enter a DNS server manually, use the same logic as on Windows and enter your VPS IPv4 address for classic DNS, with the firewall properly restricted.

If it does not provide a useful DNS setting, your router may be able to distribute your DNS server to every device on the network. Look for the DNS setting of the DHCP server, the router service that automatically gives devices their IP address and network settings. With classic DNS, keep VPS port 53 restricted to the public IP address of your home connection.

Where does WireGuard fit in?

WireGuard remains useful if you want no DNS service exposed publicly at all. In that case, keep port 53 bound only to the VPS private address, for example 10.66.66.1, and connect the device to the WireGuard network. To set up this VPN, follow our guide Install a VPN on a Linux VPS: WireGuard vs OpenVPN.

The client configuration then includes entries such as:

[Interface]
DNS = 10.66.66.1

[Peer]
AllowedIPs = 10.66.66.0/24

The [Interface] section contains the device settings here. The [Peer] section describes the WireGuard server it connects to. AllowedIPs specifies which network addresses should go through the tunnel.

With this setup, only the private network goes through WireGuard. This is a split tunnel: normal Internet browsing still uses your usual connection, while DNS reaches the VPS through the private tunnel.

If you instead want to send all Internet traffic through WireGuard, use a full-VPN configuration with AllowedIPs = 0.0.0.0/0 and also configure routing and NAT (Network Address Translation) on the VPS, the mechanism that lets tunnel traffic leave through the server’s public address. That is not required just to benefit from DNS filtering.

Check that filtering works

After changing DNS, open a few websites and check your DNS software interface or logs: Pi-hole, AdGuard Home and Technitium show DNS queries, while Blocky exposes them through its logs and metrics.

If no queries arrive, first confirm that the service is listening on the address used by the device and that the firewall allows the relevant protocol: port 53 for classic DNS, 853 for DoT, or the HTTPS port configured for DoH.