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, envDNS_PORT
) -
-H, --host [host]
— Servers host (default 0.0.0.0, envDNS_HOST
) -
-P, --provider [provider]
— Relay DoH provider from list or direct DoH URL (default cloudflare, envDNS_PROVIDER
) -
-L, --log-level [level]
— Log level (see list of levels below, default ERROR, envLOG_LEVEL
) -
--https-key [key]
— HTTPS key file-path or PEM-file content (envDOH_HTTPS_KEY
) -
--https-cert [cert]
— HTTPS cert file-path or PEM-file content (envDOH_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