DoH#
Added in version 1.12.0.
Implements a DNS over HTTPS (DoH) server as defined by RFC 8484. Accepts DNS queries carried over HTTP/HTTPS and proxies them to a group of DNS servers over UDP or TCP.
A DoH client submits a DNS query either as a GET request, with the DNS
message passed Base64URL-encoded in the dns query-string argument, or as
a POST request, with the raw DNS message in the request body. In both
cases the media type of the DNS message is application/dns-message.
A DNS response accepted by the module with a nonzero RCODE is returned
to the client with the 200 (OK) status. The RCODE remains in the DNS
message and does not trigger a retry under the invalid_response
condition of doh_next_upstream.
The doh_transport directive controls whether queries use UDP or TCP. To protect against off-path response spoofing, the module randomizes the query ID sent to the DNS server and restores the client's original ID in the response.
Note
This query-ID randomization uses a non-cryptographic generator and offers only limited protection; reach the DNS servers over a properly secured trusted network, as recommended for the resolver directive.
The Cache-Control header field of the response is derived from the
minimum TTL of the response: it is set to max-age=<ttl>, or to
no-store when no cacheable TTL can be determined.
When building from source, the module can be disabled with
the Proxying DNS over HTTPS queries to a group of DNS servers: Makes outgoing connections to a DNS server originate from the specified local IP
address with an optional port. The parameter value can contain
variables. The special value The For this parameter to work, it is usually necessary to run Angie worker
processes with superuser privileges. On Linux this is not
required, as the worker processes inherit the Sets the Defines a timeout for establishing a connection with a DNS server. Default the size of one operating-system memory page http, server, location Limits the size of a DNS query message accepted from a client. The configured
Default http, server, location Specifies in which cases a query should be passed to the next server in the
upstream group: an error occurred while establishing a connection with the server,
passing a query to it, or reading the response; a timeout occurred while establishing a connection with the server,
passing a query to it, or reading the response; the server returned an invalid DNS response; disables passing a query to the next server. Passing a query to the next server can be limited by the
number of tries and by
time. Default http, server, location Limits the time during which a query can be passed to the
next server.
Setting Limits the number of possible tries for passing a query to the
next server.
Setting Sets the address of a DNS server to which DNS queries are proxied. The address
can be specified as a domain name or IP address with a port: or as a server group: Queries are forwarded to the server over UDP or TCP, as configured by the
doh_transport directive. Only one doh_pass directive can be specified
in a location. Defines a timeout for reading a response from a DNS server. The timeout is set
only between two successive read operations, not for the transmission of the
whole response. If the DNS server does not transmit anything within this time,
the connection is closed. Sets a timeout for transmitting a request to a DNS server. The timeout is set
only between two successive write operations, not for the transmission of the
whole request. If the DNS server does not receive anything within this time, the
connection is closed. Enables the Selects the transport protocol used to forward DNS queries to a DNS server: if the upstream's keepalive cache holds a free TCP
connection, the query is sent over it (TCP); otherwise it is first sent
over UDP and retried over TCP if the server responds with a truncated
message (the queries are sent over UDP only; a truncated response is treated as an
error, and the query is not retried over TCP; queries are sent over TCP only.--without-http_doh_module build option.
In packages and images from our repos, the module is
included in the build.Configuration Example#
http {
upstream dns_upstream {
server 127.0.0.1:53;
}
server {
listen 443 ssl;
server_name dns.example.com;
ssl_certificate dns.example.com.crt;
ssl_certificate_key dns.example.com.key;
location /dns-query {
doh_pass dns_upstream;
}
}
}
Directives#
doh_bind#
off cancels the
effect of the doh_bind directive inherited from the previous configuration
level, allowing the system to auto-assign the local IP address and port.transparent parameter allows outgoing connections to a DNS server to
originate from a non-local IP address, for example, from the real IP address of
a client:doh_bind $remote_addr transparent;
CAP_NET_RAW capability from the
master process when the transparent parameter is specified.doh_buffer_size#
size of the buffer used for reading the response received from
a DNS server. The size cannot be less than 512 bytes.doh_connect_timeout#
doh_max_size#
doh_max_size size;size must be at least 12 bytes. A query shorter than 12 bytes (the size
of a DNS message header) or larger than size is rejected.doh_next_upstream#
doh_next_upstream error | timeout | invalid_response | off ...;doh_next_upstream error timeout;errortimeoutinvalid_responseoffdoh_next_upstream_timeout#
doh_next_upstream_timeout time;doh_next_upstream_timeout 0;0 disables this limitation.doh_next_upstream_tries#
0 disables this limitation.doh_pass#
doh_pass 127.0.0.1:53;
doh_pass dns_upstream;
doh_read_timeout#
doh_send_timeout#
doh_socket_keepalive#
SO_KEEPALIVE socket option for outgoing connections to a
DNS server. With off, the operating system's socket settings remain in
effect.doh_transport#
autoTC flag is set);udptcp
Content