DNS Deck

What you need

• Windows 10 or 11 with Stream Deck 7.1 or newer. Any Stream Deck works; the Stream Deck + gets dials and touch strip images too.
• One of five DNS servers this computer can reach, on your own network: Pi-hole v6, Pi-hole v5, AdGuard Home, Technitium DNS Server or Blocky. Up to four of them, of any mix.
• A login for each: an app password, an API token or a username and password, depending on the server. Blocky needs none.
• Nothing on the server. No plugin, no agent, no extra port.

1. Install the plugin

2. Set up a server

Drop any DNS Deck key on the deck, click it, and open Servers. Each of servers A to D has the same settings, shared by every DNS Deck key.

• Type: leave it on Work it out and the plugin asks the server what it is, or pick it yourself.
• Name: optional. It is what the keys call the server.
• Address: where you open the server's web interface, with its port if it has one. A pasted /admin address works. With no port, Technitium is looked for on 5380 and Blocky on 4000.
• Username and Password: what each kind of server needs, below.
• Certificate: tick it only for your own server on https with a self-signed certificate. It is off by default, and then a certificate this computer does not trust is refused.

Pick Status under a server to check it: it says which kind of server it found, or what is wrong. Read every sets how often the keys ask, from 2 to 60 seconds; the default is 5.

Pi-hole v6

The address is the one you open Pi-hole at, usually on port 80. In Pi-hole, open Settings, Web interface / API, make an app password, and put it in Password; leave Username empty. An app password also works with two-factor login on, where your normal password would not.

Pi-hole v5

The address is the one you open Pi-hole at, usually on port 80. Copy the API token from Settings, API and put it in Password; leave Username empty. Pi-hole v5 only accepts its token in the address of each request, so use v5 on your own network.

AdGuard Home

The address is the one you open AdGuard Home at, with the port you gave its web interface when you set it up (80 unless you changed it). Username and Password are the ones you log in with.

Technitium DNS Server

The address is the web console's, on port 5380. Best is an API token: in Technitium open Administration, Sessions, Create Token, put the token in Password and leave Username empty. A token never expires. Your username and password work too, but not with two-factor login on.

Blocky

The address is Blocky's HTTP port, usually 4000. Blocky's API has no login, so leave Username and Password empty; a Password, if you set one, is sent as a bearer token for a proxy in front of Blocky.

For the count keys, turn on statistics in Blocky's config (statistics.enable: true). That gives the numbers over the last 24 hours and the top blocked domain. With only prometheus on, the keys show the numbers since Blocky started, without the top domain; with neither, they say turn on statistics. Protection, pause and Lists & cache work either way, and the plugin notices statistics being turned on without a restart.

3. Servers A to D

Set up as many as four servers, of any kind, and pick Server A, B, C or D on each key. The servers belong to the plugin, not to one key, so every key on server A reads the same one. Four servers fit a Stream Deck XL with a row each, as in the picture at the top.

With more than one server set up, every key carries a small chip in its top corner: the server's letter and its type, PH for Pi-hole, AG for AdGuard Home, TN for Technitium and BL for Blocky. With one server the chip is left off.

4. The keys

The ring round every key shows the server's state from across the room: cyan while it blocks, amber while it is paused, coral when blocking is off, and grey when the server has gone quiet.

• Protection: ON, OFF or the time left on a pause, beside a shield, with the server's name. Press to turn blocking back on. Turning it off takes a second press within three seconds, so a stray press cannot leave your network unprotected; Turning off in the key's settings makes it one press. Off stays off until you turn it on again.
• Pause: pause blocking for 30 seconds, 5 minutes, 30 minutes, an hour or a number of minutes you choose, counted down on the key with a bar. Press again during the pause to turn blocking back on at once. The server ends the pause itself, so blocking comes back even if this computer is off.
• Pause all: every server you have set up, with a pill for each letter in its state's colour. Press to pause them all; press again while any is paused or off to turn them all back on. A server that is not answering turns red and is left out.
• Stat: one number. Queries, Blocked (the count and its share), Blocked %, Clients, the Top blocked domain, or Response time. Press to read it again now.
• Blocked bar: blocked % as one bar drawn across one to four keys side by side. Put one on each key of the row, set the same Keys wide on all of them, and number them from the left.
• Lists & cache: one press to update the server's block lists now, or to flush its DNS cache. The key shows it working, then lists updated, cache flushed or why the server refused. Technitium and Blocky only.

When a server goes quiet a key keeps its numbers for 30 seconds, then turns grey, and after a minute says can't reach and how long it has been. It comes back by itself. A wrong password or token shows at once.

5. Stream Deck + dials

• Turn a Stat dial through queries, blocked, blocked %, clients, top blocked and response time, skipping any that server does not report.
• Push to pause that server for the time set under Dial push pauses, or to resume it.
• Tap the strip to read it again.

6. What each server can do

The gaps, in plain words:

• Technitium has no response time, and pauses in whole minutes, so a 30-second pause there lasts a minute.
• Blocky needs its statistics on for the numbers and the top blocked domain; with only Prometheus metrics the numbers count from when Blocky started, and there is no top domain. With neither, the number keys say turn on statistics.
• Lists & cache works on Technitium and Blocky only. On Pi-hole and AdGuard Home the key says not on that server.
• Pi-hole v5 has no response time and does not report the time left on a pause, so the countdown shows only for pauses set from the deck; a pause set elsewhere reads as off.
• AdGuard Home has no count of clients, only its top list, so a full list shows as 100+. Blocky's list holds 20.

Where a server cannot report something, the key says not on that server, never a made-up zero.

7. What it does with your server

• It talks only to the servers you enter, on your own network, over their own APIs. No account, no cloud, and nothing installed on the server. It asks every few seconds, five by default, and the top blocked domain and response times every 30 seconds.
• Passwords and tokens stay on this computer, in Stream Deck's own settings for the plugin, and each is only sent to its own server. It never goes in an address, except on Pi-hole v5, which accepts its token no other way.
• One session, given back. On Pi-hole v6, and on Technitium with a username and password, it keeps one login session and ends it when it stops. After a wrong password it asks only once a minute, so the server does not lock you out.
• Self-signed certificates are refused unless you tick Trust this server's certificate for that server.
• The log records states and counts, never an address, a username, a password or a domain.

Frequently asked

The key says can't reach.

Nothing answered at that address. The line under it says why: nothing on that port means the machine is there but nothing listens on that port, so check it is the web interface's port (5380 for Technitium, 4000 or your own for Blocky); name not found means this computer cannot find that address; no answer means the server is down or out of reach. If it said can't reach after working for a while, the server stopped answering, and the key comes back by itself when it does.

The key says wrong password, or wrong API token.

The server refused the login. On Pi-hole v6 use an app password, not your normal one; on Pi-hole v5 the API token; on AdGuard Home your login; on Technitium an API token with Username left empty, or your username and password. Check it with Status under that server. Until it is right the plugin asks only once a minute, so the server's login limit is never hit.

The key says needs 2FA code.

Two-factor login is on. Use an app password on Pi-hole v6, or an API token on Technitium; both work with two-factor login on.

The count keys say not on Blocky, turn on statistics.

Blocky only reports numbers with its statistics on. Set statistics.enable: true in its config and restart Blocky; the keys pick it up within 30 seconds. See Blocky.

A key says not on Pi-hole, or not on AdGuard Home.

That server does not report this to other apps, or DNS Deck does not use it there yet: Lists & cache on Pi-hole and AdGuard Home, and response time on Pi-hole v5 and Technitium. See what each server can do.

The key says cert not trusted.

The server is on https with a certificate this computer does not trust, which is usual for a self-signed one. Tick Certificate for that server, or use its plain http address.

Does it slow the server down?

No. It asks for the same small summaries the server's own dashboard shows, every few seconds, and on Pi-hole v6 and Technitium it reuses one login session rather than opening a new one each time.

Is it made by Pi-hole, AdGuard, Technitium or Blocky?

No. DNS Deck is unofficial and not affiliated with Pi-hole, AdGuard, Technitium or Blocky. Pi-hole, AdGuard, Technitium and Blocky are names and trademarks of their respective owners. The shield on the keys is our own.

Something is still wrong.

Email support@teatimeservers.ca with what the key says and which kind of server it is, and we will take a look.