---
name: "hddemux"
section: "1"
platform: "linux"
package: "hddemux"
version: "0.5-1.1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/hddemux"
---

# hddemux(1)

demultiplexes incoming TCP connections between HTTP and DNS

## NAME

hddemux - demultiplexes incoming TCP connections between HTTP and DNS

## SYNOPSIS

hddemux

## DESCRIPTION

hddemux takes a set of listening stream-based file descriptors (see [sd\_listen\_fds(3)](/sd_listen_fds/3.md)) and accepts new connections on them.

When a new connection comes in, it decides from the first few octets whether the 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.

## ENVIRONMENT VARIABLES

HTTP\_TARGET and DNS\_TARGET should be either a DNS name or an IP address, optionally followed by a colon and a port number. If either variable is unset, it will default to “localhost”.

If the port number is not specified, HTTP\_TARGET defaults to TCP port 80, and DNS\_TARGET defaults to TCP port 53.

If HDDEMUX\_DEBUG is set to a non-empty string, then it will send a lot of verbose debugging info to stderr.

IDLE\_TIMEOUT is used to set 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 (10 minutes). 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 (configuration, outstanding established streams, etc) to stderr.

## 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
  ```

Configuration can be done by overriding the .service file (e.g. with Service.Environment= entries). See the “edit” documentation in [systemctl(1)](/systemctl/1.md) and the “Overriding vendor settings” section of [systemd.unit(5)](/systemd.unit/5.md).

## CONSTRAINTS

hddemux is designed to demultiplex HTTP/1.x from stream-based DNS. Trying to demultiplex other protocols (including HTTP/2 or later) is not advised. Please see draft-dkg-dprive-demux-dns-http for more information and analysis.

## 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.

## SEE ALSO

[sd\_listen\_fds(3)](/sd_listen_fds/3.md), [systemctl(1)](/systemctl/1.md), [systemd.unit(5)](/systemd.unit/5.md), https://datatracker.ietf.org/doc/draft-dkg-dprive-demux-dns-http/

## AUTHORS

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