DNS Relay

DNS relay for UDP and DoH requests

Node usage

In code

// ESM
import { UDP, DoH } from 'dns-relay';
// CommonJS
const { UDP, DoH } = require('dns-relay');

// Instant start
UDP(53535, 'cloudflare');
DoH(80, '127.0.0.1', 'google');

// Class usage
const udp = new UDP(53535, 'cloudflare');
udp.start();

const doh = new DoH(53535, 'cloudflare');
doh.start();

// Object params
UDP({ port: 53535, host: '127.0.0.1', provider: 'cloudflare'});
const doh = new DoH({ port: 53535, host: '127.0.0.1', provider: 'cloudflare'});

Initialize

• UDP
  • UDP(...params): ClassUDP — argumental params. Return class object and instantly start server
  • UDP(params: Object): ClassUDP — object params. Return class object and instantly start server
  • new UDP(...params): ClassUDP — argumental params. Just class constructor call
  • new UDP(params: Object): ClassUDP — object params. Just class constructor call
• DoH
  • DoH(...params): ClassDoH — argumental params. Return class object and instantly start server
  • DoH(params: Object): ClassDoH — object params. Return class object and instantly start server
  • new DoH(...params): ClassDoH — argumental params. Just class constructor call
  • new DoH(params: Object): ClassDoH — object params. Just class constructor call

Params overwrites environment variables (see list below).

Parameters

Arguments

• UDP
  • UDP([port[, host[, provider[, logLevel]]]])
  • new UDP([port[, host[, provider[, logLevel]]]])
  • UDP({port: number, host: string, provider: string, logLevel: string})
  • new UDP({port: number, host: string, provider: string, logLevel: string})
• DoH
  • DoH([port[, host[, provider[, https[, logLevel]]]]])
  • new DoH([port[, host[, provider[, https[, logLevel]]]]])
  • DoH({port: number, host: string, provider: string, https: {key: string, cert: string}, logLevel: string})
  • new DoH({port: number, host: string, provider: string, https: {key: string, cert: string}, logLevel: string})

Available params

• port — server listen port
• host — server listen host
• provider — DoH-provider for relay. Use predefined name (see list below) or pass direct URL
• https — for DoH only {key: "pem or file-path", cert: "pem or file-path"}. HTTPS params for DoH server. If some file does not pass or unavaliable DoH server starts in HTTP.
• logLevel — Log level (see list of levels below)

Class methods

• start() — start server
• stop() — stop server
• setLogLevel(level) — set log level
• setProvider(provider || providerUrl) — set provider from list (see below) or direct url

Command line

Local usage:

$ npm install dns-relay
$ npx dns-relay [options] [servers...]

Global usage:

$ npm install -g dns-relay
$ dns-relay [options] [servers...]

Servers

You can enable one of UDP or DoH server

$ dns-relay doh # DoH only
$ dns-relay udp # UDP only
$ dns-relay doh udp # UDP and DoH server starts
$ dns-relay # dns-relay doh udp

Options

Options overrides environment variables

• -p, --port [port] — Servers port (default 53535, env DNS_PORT)
• -H, --host [host] — Servers host (default 0.0.0.0, env DNS_HOST)
• -P, --provider [provider] — Relay DoH provider from list or direct DoH URL (default cloudflare, env DNS_PROVIDER)
• -L, --log-level [level] — Log level (see list of levels below, default ERROR, env LOG_LEVEL)
• --https-key [key] — HTTPS key file-path or PEM-file content (env DOH_HTTPS_KEY)
• --https-cert [cert] — HTTPS cert file-path or PEM-file content (env DOH_HTTPS_CERT)
• -V, --version — output the version number
• -h, --help — display help for command

Docker usage

Command:

docker run \
  --name dns-relay \
  -p 53:53535/udp \
  -p 80:53535/tcp \
  -e DNS_HOST=0.0.0.0
  -e DNS_PORT=53535
  -e DNS_PROVIDER=google
  -e LOG_LEVEL=NONE
  nim579/dns-relay

Compose:

version: "2"
services:
  migrator:
    image: nim579/dns-relay
    ports:
      - 53:53535/udp
      - 80:53535/tcp
    environment:
      DNS_HOST=0.0.0.0
      DNS_PORT=53535
      DNS_PROVIDER=google
      LOG_LEVEL=NONE

Env variables

• DNS_PORT — Listen port for UDP and DoH servers

• DNS_HOST — Listen host for UDP and DoH servers

• UDP_PORT — Listen port for UDP server (overrides DNS_HOST, default 53535)

• UDP_HOST — Listen host for UDP server (overrides DNS_PORT, default 0.0.0.0)

• DOH_PORT — Listen port for DoH server (overrides DNS_HOST, default 53535)

• DOH_HOST — Listen host for DoH server (overrides DNS_PORT, default 0.0.0.0)

• DOH_HTTPS_CERT — HTTP cert (for DoH only). Pass absolute or relative url or PEM-file content

• DOH_HTTPS_KEY — HTTP key (for DoH only). Pass absolute or relative url or PEM-file content

• DNS_PROVIDER — Provider name or direct URL for relay (see list of providers below, default cloudflare)

• LOG_LEVEL — Logs level (see list of levels below, default ERROR)

Providers

List of available providers

• mozilla-cloudflare — https://mozilla.cloudflare-dns.com/dns-query
• google — https://dns.google/dns-query
• cloudflare — https://cloudflare-dns.com/dns-query
• quad9 — https://dns.quad9.net/dns-query
• cleanbrowsing-security — https://doh.cleanbrowsing.org/doh/security-filter/
• cleanbrowsing-family — https://doh.cleanbrowsing.org/doh/family-filter/
• cleanbrowsing-adult — https://doh.cleanbrowsing.org/doh/adult-filter/
• adguard — https://dns.adguard.com/dns-query
• adguard-family — https://dns-family.adguard.com/dns-query

Log levels

• NONE — no logs
• ERROR — error logs only
• INFO — error and info logs
• DEBUG — error, info and debug logs