Pi-hole Web Interface: The Next Generation

Looks nice. I'd like to see more of the demo interface. Any password?

The login page is just for looks right now.

Thank you for your answer and time.

I have looked into the workings of pi-hole some more, besides just using it with great appreciation.

If I understand the current working correctly:

  • pi-hole is a C written application, lets call it the "core". its a service(?)
  • this core can be interacted with using the command line, singleton, since its a service
  • this core communicates with DNSMasq, that really does the DNS and optional DHCP stuff
  • FTL is a second part, complementing the core.
  • FTL saves statistics for the day in memory and long-term statistics in a DB-file
  • FTL gets the information by reading logs that the core saves to disk
  • The core probably gets this information by reading DNSMasq logs(?)
  • Before FTL, PHP read the core log files directly (and was slow at it, i understand)
  • Currently PHP uses a socket to connect to either the PHP API or FTL API
  • The PHP API is the slower one
  • The FTL API is the faster one

So, to eliminate PHP completely, you need to be able to connect the web interface to FTL without the (current) use of PHP's sockets. Currently both the old PHP way and the new FTL way of getting statistics rely on that PHP socket.

Are you guys planning on using a JS websocket to connect the new web GUI to FTL? This would require FTL to have websocket code. A bit more code. But, you could let go of PHP so you win a lot too of course. Yet, you can't just make a browser connect to anything. You can only upgrade a HTTP-request, so this would mean the webserver needs to be able to handle websockets, plus.. for the webserver to then communicate with FTL. This would require lighttpd to get some custom work done to it (for the lighttpd<>FTL part) leaving nginx and apache to be no longer an option, no?

I'd love to hear if I see the big picture of the workings right, and if my conclusions at the end are right. Most likely I'm still missing something. Hopefully one of you can tell me. I'm especially curious about the (I suppose) JS to FTL connection.

Have a great day!

Core Pi-hole is written in Bash: GitHub - pi-hole/pi-hole: A black hole for Internet advertisements
It handles the core routines such as gravity, installing/updating/reconfiguring Pi-hole, managing the lists (white, black, etc), managing access to setupVars for the PHP web interface (this may be moved later though), chronometer, checking the block lists, and some other utilities such as pihole -t.
Core Pi-hole does not have any services of its own (besides dnsmasq and lighttpd).

You got FTL's part right. It provides statistics about the logs generated by Pi-hole Core (dnsmasq). These statistics are used by the web interface and chronometer. Before FTL, PHP would have to parse the dnsmasq log for every query (verrrrrrry expensive and slow).

The PHP web interface has an API file (api.php, which uses api_FTL.php) which connects to FTL over a local socket to get data from it to pass on to whatever was calling the API.

We're developing an HTTP API which will connect to FTL via a Unix socket using the MessagePack protocol to efficiently stream data. Since it runs server-side, it will take the place of the current PHP API, and should be faster too. We considered developing the HTTP library in C inside FTL (and even implemented most of it), but we decided to move that HTTP API functionality to a new program. The reasons for this decision were that we felt that FTL should focus on generating the statistics and implementing a web server in C is not the best idea (especially if we want to easily add advanced features, and other languages are better for that).
You can see the work done in FTL to support this here: https://github.com/pi-hole/FTL/pull/75

We haven't decided when to fully announce the new API, but we hope it will be soon. :slight_smile:

Thank you for getting into details. I'm learning and understanding more now.

So, we're looking at..

  1. Pi-Hole core (bash script)
  2. FTL for keeping track of stats
  3. A new component to serve stats from FTL to the webinterface
  4. Webserver of any kind to complete it all

The new component (lets call it Web-API) will use a socket to talk to FTL on the same machine. It uses MessagePack inbetween the two. Cool.

How is the Web-API connected to the Web-GUI though? The GUI gets served by a webserver, and it could request stuff through the webserver obviously. But is it going to talk to the new Web-API around the webserver? through the webserver?

Anyway, agreed in this case that PHP is rather large for the simple job it has in pi-hole. But I see more oppertunities to make it lighter and faster even after PHP is gone.

You said you don't want to create a webserver in C so you can profit from mainstream techniques later on. To me, if the situation above is right, I would be thinking; let's integrate a small simple webserver into the new Web-API. Just serving the few pages the Web-GUI offers, the Web-GUI right now doesn't require any fancy stuff as of now. This way you can get rid of any 3rd party webserver overhead too. Plus, the only thing that should be interesting to have is the powerful and relatively new websocket-tech. Instead of AJAX polling, you can very easily push new stats from the Web-API to the Web-GUI. And the other way around, a few post events from the Web-GUI back to the Web-API. Then the Web-API can fire off core bash commands or talk messagepacked-sockety stuff with FTL and thats it.

What are your thoughts on that?

PS: in the future, SSL would be nice. But since certs in a closed off network are a thorn in developers' eyes for years now (self signing, devices nagging about it), I don't see that getting solved anytime soon.

The web interface will communicate with the API via HTTP requests (the API will be exposed on We're looking into a few configurations, including serving the web interface through the API like you were thinking :smile: (therefore putting it on port 80). That would allow us to not require even Lighttpd, and users can do a reverse proxy to put it in other configurations.

SSL is something that would be helpful for users, and we even have a FAQ now for the current version of Pi-hole if you want to manually add in that functionality:

Does the new UI have ajax support for the Query Log page? I don't know react well enough to understand this, yet: https://github.com/pi-hole/web/blob/master/src/components/QueryLog.js

I'm hoping to have a page that just shows me the blocked urls in close to real-time via ajax, so I don't have to refresh manually.

That might be something that an API could expose for you. We're in the concept stages of looking at ways to get that information to users and it would provide data in a structured format when queried.

1 Like

The Query Log loads in data from an endpoint here:
That line calls this function to get the query data from the API:

If you want to have real-time updates, we should implement that using web sockets. We could use server-side events, but that's not implemented in IE or Edge whereas web sockets are. Ajax would just mean we have to keep a long or short-poll connection to the server, which is not as nice or clean as the first two solutions.


Could you possibly add a few lines to the readme with a developer quickstart guide? This seems like a great project to get familiar with React, but I am a bit out of the loop on the details with the node toolchain. A few quick points on how to build a dev environment would be great.

1 Like

Sure, check out

Can we have the device MAC (and IP) addresses use ANY monospaced font? It will help readibility on the page.

I’m a UX designer. If there is anything I can do to help out, please let me know! Thanks for all your hard work!

1 Like

ironic , web.pi-hole.io is being blocked by my pPiHole which is only using the OOTB supplied lists (+ one manual blacklist entry)

ho hum, /me adds to whitelist

Nope whitelisting and restarting DNSserver doesnt help

pi@Heimdall:~ $ pihole -t | grep -w "web.pi-hole.io"
23:33:58 dnsmasq[16915]: query[A] web.pi-hole.io.lan from
23:33:58 dnsmasq[16915]: cached web.pi-hole.io.lan is NXDOMAIN
23:33:58 dnsmasq[16915]: query[AAAA] web.pi-hole.io.lan from
23:33:58 dnsmasq[16915]: cached web.pi-hole.io.lan is NODATA-IPv6
23:33:58 dnsmasq[16915]: query[A] web.pi-hole.io from
23:33:58 dnsmasq[16915]: cached web.pi-hole.io is NXDOMAIN
23:33:58 dnsmasq[16915]: query[AAAA] web.pi-hole.io from
23:33:58 dnsmasq[16915]: cached web.pi-hole.io is NODATA-IPv6
23:34:06 dnsmasq[16915]: query[A] web.pi-hole.io from
23:34:06 dnsmasq[16915]: cached web.pi-hole.io is NXDOMAIN
23:34:22 dnsmasq[17100]: query[A] web.pi-hole.io.lan from
23:34:22 dnsmasq[17100]: forwarded web.pi-hole.io.lan to
23:34:22 dnsmasq[17100]: reply web.pi-hole.io.lan is NXDOMAIN
23:34:22 dnsmasq[17100]: query[AAAA] web.pi-hole.io.lan from
23:34:22 dnsmasq[17100]: forwarded web.pi-hole.io.lan to
23:34:22 dnsmasq[17100]: reply web.pi-hole.io.lan is NODATA-IPv6
23:34:22 dnsmasq[17100]: query[A] web.pi-hole.io from
23:34:22 dnsmasq[17100]: forwarded web.pi-hole.io to
23:34:22 dnsmasq[17100]: reply web.pi-hole.io is NXDOMAIN
23:34:22 dnsmasq[17100]: query[AAAA] web.pi-hole.io from
23:34:22 dnsmasq[17100]: forwarded web.pi-hole.io to
23:34:22 dnsmasq[17100]: reply web.pi-hole.io is NODATA-IPv6

It's https://web.pi-hole.net the pi-hole.io domain doesn't exist anymore and that's why you see the NXDOMAIN.

1 Like

Hey, I just clicked the demo link in the first post :slight_smile:

You can also check out the Pi-Hole public repositories and make direct contributions there!

Please do.

When can I try it out? And I see a docker folder, please, please, please do not make that mandatory to use, make an optional docker image for people who do want docker but I see no reason why it would require it. Anyway, looks great and I'm happy to see php getting the boot and nodejs taking his spot. Great work, developers!!