• Stars
    star
    193
  • Rank 201,081 (Top 4 %)
  • Language
    JavaScript
  • License
    BSD 2-Clause "Sim...
  • Created about 5 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Sample Configuration for DNS over HTTPS (DoH/DoT gateway) and GSLB with NGINX

NGINX DNS (DNS/DoT/DoH)

This repository contains some NJS code, and example configuration files for using NGINX with DNS services. NGINX can be used to perform load balancing for DNS (TCP/UDP), and also DNS over TLS (DoT) and DNS over HTTPS (DoH)

NGINX can also be used to provide Global Server Load Balancing (GSLB).

See the example configuration files in the examples folder.

Setup

Copy the njs.d folder into /etc/nginx/ and one of the NGINX DoH examples to /etc/nginx/nginx.conf The ssl folder contains a test certificate, you will likely want to generate and use your own certificate and update the nginx.conf file accordingly.

Simple DNS

NGINX can do simple DNS load balancing, without the need for NJS, using the standard Stream module directives.

stream {

  # DNS upstream pool.
  upstream dns {
    zone dns 64k;
    server 8.8.8.8:53;
  }

  # DNS Server. Listens on both TCP and UDP
  server {
    listen 53;
    listen 53 udp;
    proxy_responses 1;
    proxy_pass dns;
  }
}

However if you want to carry out layer 7 inspection of the DNS traffic for logging or routing purposes, then you will need to use the NJS module included in this repository.

To perform DNS routing, you need to make a js_preread function call in the server context, and use a js_set function with a map. For example:

stream {
  js_import /etc/nginx/njs.d/dns/dns.js;
  js_set $dns_qname dns.get_qname;

  map $dns_qname $upstream_pool {
    hostnames;
    *.nginx one;
    default two;
  }

  upstream one {
    ...
  }

  upstream two {
    ...
  }

  server {
    listen 53 udp;
    js_preread dns.preread_dns_request;
    proxy_responses 1;
    proxy_pass $upstream_pool;
  }

}

DNS over TLS (DoT) and DNS over HTTPS (DoH) Gateway

NGINX can act as a DNS(TCP) <-> DNS over TLS (DoT) gateway without any NJS functions. Eg:

  upstream dns {
    zone dns 64k;
    server 8.8.8.8:53;
  }

  upstream dot {
    zone dot 64k;
    server 8.8.8.8:853;
  }

  server {
    listen 53;
    listen 853 ssl;
    ssl_certificate /etc/nginx/ssl/certs/doh.local.pem;
    ssl_certificate_key /etc/nginx/ssl/private/doh.local.pem;
    proxy_ssl on;
    proxy_pass dot;
  }

The above example will accpet DNS and DoT requests, and forward them to a DoT upstream. If your upstream is DNS, and you want to terminate DoT on NGINX, then remove the proxy_ssl on; directive, and change the proxy_pass directive to use the standard DNS upstream.

NJS is required if you want to act as a gateway between DoH and DNS/DoT. See the example configuration files in the examples folder.

The full configuration has a HTTP/2 service listening for requests, and does a proxy_pass for requests to /dns-query. We proxy to an internal stream service on port 8053, which uses js_filter to pull out the DNS packet from the HTTP wrapper, and forward onto an upstream DNS(TCP) or DoT server. The result is then wrapped back up in a HTTP response and passed to the HTTP/2 service for delivery to the client.

NGINX can log as much or as little as you like, and the NJS allows you to process information in the DNS requests and responses.

See: docs/nginx-dns-over-https for more information

NGINX GSLB (work-in-progress)

Use the nginx-glb.conf file to run an GSLB service. Copy the njs.d folder into /etc/nginx/ and the nginx-glb.conf to /etc/nginx/nginx.conf

TODO - Describe the example configuration and how to customise it.

More Repositories

1

focal-mainline-builder

Docker container to build Ubuntu Mainline kernels for use on 20.04 LTS
Shell
81
star
2

Docker-Brocade-vTM

Brocade vTM Docker Configuration
Shell
13
star
3

nginx-lb-operator

K8s/OCP Operator for managing external NGINX Load Balancers
Makefile
12
star
4

ansible_collection_nginx_management_suite

Ansible Collection for the NGINX Management Suite (NIM)
Python
11
star
5

Puppet-Brocade-vTM

Brocade vTM (Virtual Traffic Manager) Puppet Module
Puppet
11
star
6

ft232h-1wire

1-Wire bus implementation over GPIO on FT232H
Python
9
star
7

nginx-plus-ftp

Load Balancing FTPS with NGINX Plus
JavaScript
6
star
8

app-centric-with-controller

Automation workshop with NGINX Plus and NGINX Controller
HTML
5
star
9

BrocadeCloud

Brocade vTM integration scripts
Python
3
star
10

python-vadc

Python library for vADC
Python
3
star
11

nginx-radius

Load Balancing RADIUS with NGINX
JavaScript
2
star
12

ansible-playbooks

Misc Ansible Playbooks
Jinja
2
star
13

whatcheese

A simple Demo website and API running on NGINX UNIT
HTML
2
star
14

ServicesDirectorCFT

Services Director - Cloud Formation Template
Shell
2
star
15

MiscTrafficScripts

Miscellaneous TrafficScripts for vTM
Groff
2
star
16

Chef-Brocade-vTM

Chef Cookbook for Brocade vTM
Ruby
2
star
17

st2_chuck

StackStorm Chuck Norris Pack (using ICNDB)
Python
2
star
18

ansible_collection_tuxinvader_launchpad

Ansible collection for interacting with the Ubuntu Launchpad API
Python
1
star
19

BrocadeREST

tools for parsing vADC REST APIs
Ruby
1
star
20

ansible-role-nginx_controller_auth_provider

Ansible role for creating an Authentication Provider on Controller
Jinja
1
star