There doesn’t seem to be a single, simple, straight forward tutorial online that shows how to get Lancache working with Pihole.

These are the URLs that I referenced to get this working, so just listing them here in case you want to read more, but I will explain everything.

URLPurpose Github page for Lancache website helpful site very helpful site

Domains to cache

To see what domains you should (and can) cache, check out this awesome Github repo. Each txt file contains the domains for the various game servers, Windows updates, etc. Be sure to check their lists every so often for any updates.

The reason we should check this list is because we will set up DNSMasq rules, so once in a while just make sure you are forwarding everything (more on this later). (There probably are other sources, but this one is pretty cool)

Docker Compose for Lancache

We need to host Lancache as a docker container. I will explain what you should change down below:

Take Note: I am using Portainer, hence “the “env_file: stack.env

Docker Compose File

version: '2'
    image: lancachenet/lancache-dns:latest
    restart: unless-stopped
    env_file: stack.env
      - ${DNS_BIND_IP}:53:53/udp
      - ${DNS_BIND_IP}:53:53/tcp

    image: lancachenet/monolithic:latest
    restart: unless-stopped
    env_file: stack.env
      - 80:80/tcp
      - 443:443/tcp
      - ${CACHE_ROOT}/cache:/data/cache
      - ${CACHE_ROOT}/logs:/data/logs

And here is my .env file I uploaded into Portainer for this stack


You have to change the following for your environment

env file
  1. This should be the IP address of the host that your Lancache is running on. We will forward DNS queries for Windows Updates and game servers from Pihole to this host IP (, which in turn will pass it to this container on port 53.
  2. This tells Lancache what upstream DNS provider to use to resolve the hostnames. We probably can point it back to Pihole, but we might end up creating a resolver loop.
  3. Change this to where you want your Lancache container to cache files on the host machine

Take Note: In your docker compose file, do NOT change port 80 and 443. If they are already in use on your host, make a plan, because Lancache MUST liseten on these 2 ports.

We can now start this stack on Portainer.

Creating the dnsmasq config file

I am going to use the Windows updates file from that UKLans repo I talked about above.

Now we just need to put it in dnsmasq format

For each line in that URL above, we will create a dnsmasq line that looks like this:


Keep in mind that, even though we tell dnsmasq to only forward, dnsmasq will forward ALL subdomains. This is how dnsmasq works.

You need to replace the IP address above with the IP address of the host that Lancache runs on. In our case, we put this in our env file

env file ips

Put the config into Pihole

I am using Pihole 5, not 6, as 6 is still in beta. The second link I provided above talks more about achieving the below, but in Pihole 6. I will stick to Pihole 5 for now.

SSH into your Pihole host, then cd to dnsmasq

cd /etc/dnsmasq.d

Then we need to create a new config file

nano 02-Cache.conf

And then we paste that dnsmasq config into this file. Then our file will look like this when we cat it:

dnsmasq config file

Now we need to restart pihole so it can pull in this new config (you can also restart your entire Pihole system if you want to)

pihole restartdns

So what is actually happening?

We bascially told Pihole that for any domain in our 02-Cache.conf file, that it must forward that domain to

Remember that is running the Lancache DNS server. So that Lancache DNS server will now get the request for, for example,, and then forward it to Here is a reminder of where comes from.

the upstream dns

This way Lancache knows about all this traffic and it can do its thing, which is check if something we need is in cache, and if it is, respond from cache; and if it is not in cache, fetch it from the internet, then store it in cache.

We can also see that our Pihole is passing on DNS requests for any of the domains in our dnsmasq config file, to our Lancache IP address:

pihole logs

Checking if Windows Updates are actually caching

In my env file I said that cache should be stored in /opt/lancache/ This will be stored on your host. So now if I check that folder, I can see that folders are being created in this folder and the size is growing

folder size growing

And here we can see items are added

cached items

So I downloaded an update on my PC, and then later on my laptop. In Portainer I could see that when downloading the same update from my laptop that Lancache saw increased traffic (everything to the right of the red line)

portainer graphs