HDDEMUX(1)

💖 hddemux — the manual, but make it slay 💖

okay bestie, gather round, because hddemux (that's the manual page name, section 1, Unix manual pages, iykyk) is genuinely one of the cutest little programs out there and I need you to understand it. no cap.

---

✨ NAME ✨

hddemux — demultiplexes incoming TCP connections between HTTP and DNS.

like... it's a traffic cop but make it fashion. 💅

---

🦋 SYNOPSIS 🦋

hddemux

that's it. that's the whole synopsis. no flags, no args, no nonsense. she just runs. iconic behavior honestly. 👑

---

🌸 DESCRIPTION 🌸

so here's the vibe. hddemux takes a set of listening stream-based file descriptors (peep sd_listen_fds(3) for the lore) and accepts new connections on them. 🫶

when a new connection comes in, it looks at the first few octets</> and decides whether this connection is HTTP/1.x or DNS.

• if it thinks it's HTTP/1.x, it splices the connection to the HTTP_TARGET. 🌈
• if it thinks it's DNS, it splices the connection to the DNS_TARGET. 🦋

one port, two destinies. the way that it just knows?? obsessed.

---

🎀 ENVIRONMENT VARIABLES 🎀

okay this is the part where you actually configure her, so pay attention bestie.

• HTTP_TARGET and DNS_TARGET — these should be either a DNS name or an IP address, and optionally you can follow that with a colon and a port number. if either variable is unset, it just defaults to localhost. (yes really, just localhost. she's lowkey humble like that. 🙈)
• if the port number is not specified, HTTP_TARGET defaults to TCP port 80, and DNS_TARGET defaults to TCP port 53.
• HDDEMUX_DEBUG — set this to a non-empty string and she will send a lot of verbose debugging info to stderr. like a lot a lot. she will tell you everything. 💀
• IDLE_TIMEOUT — this sets the number of milliseconds that hddemux will permit a session to be in an open state with no traffic passing before it tries to close both sides. the default is 600000 (that's 10 minutes, for the non-math girlies 🧮). set this variable to 0 to never try to do this kind of cleanup.

---

💜 SIGNALS 💜

when hddemux receives SIGUSR1, it dumps an overview of the current state of the demuxer to stderr — that's the configuration, outstanding established streams, etc. etc.

basically you poke her and she trauma-dumps her whole current situation to stderr. relatable tbh. 😭

---

🌈 EXAMPLES 🌈

for systemd, you need a .socket unit file:

#/lib/systemd/hddemux.socket
[Unit]
Description=HTTP/1.x and DNS demuxer socket
Documentation=man:hddemux(1)

[Socket]
ListenStream=/run/hddemux/socket

[Install]
WantedBy=sockets.target

and a .service unit file:

#/lib/systemd/hddemux.service
[Unit]
Description=HTTP/1.x and DNS demuxer service
Documentation=man:hddemux(1)
Requires=hddemux.socket

[Service]
Type=notify
ExecStart=/usr/bin/hddemux
WorkingDirectory=/run/hddemux/workdir
User=hddemux
Group=hddemux

[Install]
Also=hddemux.socket

and configuration? you do that by overriding the .service file — e.g. with Service.Environment= entries. go read the "edit" documentation in systemctl(1) and the "Overriding vendor settings" section of systemd.unit(5). 🫡

---

⭐ CONSTRAINTS ⭐

hddemux is designed to demultiplex HTTP/1.x from stream-based DNS. trying to demultiplex other protocols — and yes that includes HTTP/2 or later — is not advised. 🚫

if you want more info and analysis, please see draft-dkg-dprive-demux-dns-http. it's giving "required reading". 📚

---

💀 WARNING 💀

note that this effectively acts as a stream redirector once the client's first flight has been processed. it does this with no attempt to defend against stream redirection loops, so be careful not to redirect it to itself — or it will eat all of your memory in infinite recursion. 💀💀💀

bestie. do not point it at itself. i am begging you. that's the whole warning. she will simply consume everything you love. 🔥

---

🔥 SEE ALSO 🔥

• sd_listen_fds(3)
• systemctl(1)
• systemd.unit(5)
• https://datatracker.ietf.org/doc/draft-dkg-dprive-demux-dns-http/

---

👑 AUTHORS 👑

Daniel Kahn Gillmor <dkg@fifthhorseman.net>. 🫶

---

and that's the whole page, bestie!! this version is from 2017 May, and yeah — HDDEMUX(1) really is the source, that's where all of this came from. mwah. 💋✨🎀