HDDEMUX(1)

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)) 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) 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 (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), systemctl(1), systemd.unit(5), https://datatracker.ietf.org/doc/draft-dkg-dprive-demux-dns-http/

AUTHORS
Daniel Kahn Gillmor dkg@fifthhorseman.net