Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/albertito/dnss
DNS over HTTPS [mirror]
https://github.com/albertito/dnss
dns dns-proxy doh doh-server go-application https-proxy security
Last synced: 3 months ago
JSON representation
DNS over HTTPS [mirror]
- Host: GitHub
- URL: https://github.com/albertito/dnss
- Owner: albertito
- License: other
- Created: 2015-10-18T10:29:13.000Z (about 9 years ago)
- Default Branch: main
- Last Pushed: 2024-05-12T09:09:37.000Z (6 months ago)
- Last Synced: 2024-05-13T09:42:56.132Z (6 months ago)
- Topics: dns, dns-proxy, doh, doh-server, go-application, https-proxy, security
- Language: Go
- Homepage: https://blitiri.com.ar/git/r/dnss/
- Size: 243 KB
- Stars: 121
- Watchers: 10
- Forks: 17
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# dnss
dnss is a daemon for using DNS over HTTPS.
It can act as a proxy, receiving DNS requests and resolving them using
DNS-over-HTTPs (DoH). This can be useful to improve DNS security and privacy
on laptops and small/home networks.
It can also act as a DoH server, in case you want end to end control.
[](https://github.com/albertito/dnss/actions/workflows/tests.yaml)
[](https://goreportcard.com/report/github.com/albertito/dnss)
[](https://codecov.io/github/albertito/dnss)
## Features
* Supports the
[DNS Queries over HTTPS (DoH)](https://en.wikipedia.org/wiki/DNS_over_HTTPS)
standard ([RFC 8484](https://tools.ietf.org/html/rfc8484)).
* Local cache (optional).
* HTTP(s) proxy support, autodetected from the environment.
* Monitoring HTTP server, with exported variables and tracing to help
debugging.
* Separate resolution for specific domains, useful for home networks with
local DNS servers.
## Install
### Debian/Ubuntu
The `dnss` package installs the daemon configured in proxy mode and ready to
use, using Google's public resolvers (and easily changed via configuration).
```shell
sudo apt install dnss
```
### Manual install
To clone the repository and build the binary:
```shell
git clone https://blitiri.com.ar/repos/dnss
cd dnss
go build
```
And if you want to configure the daemon to be automatically run by systemd:
```shell
# Copy the binary to a system-wide location.
sudo cp dnss /usr/local/bin/
# Set it up in systemd.
sudo cp etc/systemd/dns-to-https/* /etc/systemd/system/
sudo systemctl dnss enable
```
On systems with SELinux, like Fedora, you might see hidden errors. In that
case, run this to set the security context for the binary:
```sh
sudo semanage fcontext -a -t bin_t "/usr/local/bin/dnss"
sudo restorecon -v /usr/local/bin/dnss
```
## Examples
### DNS server (proxy mode)
Listens on port 53 for DNS queries, resolves them using the given HTTPS URL.
```shell
# Use the default HTTPS URL (currently, dns.google):
dnss -enable_dns_to_https
# Use Cloudflare's 1.1.1.1:
dnss -enable_dns_to_https -https_upstream="https://1.1.1.1/dns-query"
# Use Google's dns.google:
dnss -enable_dns_to_https -https_upstream="https://dns.google/dns-query"
# Use the default HTTPS URL for all resolutions, except for domain "myhome"
# which is resolved via a local DNS server.
dnss -enable_dns_to_https -dns_server_for_domain="myhome:10.0.1.1:53"
```
### HTTPS server
Receives DNS over HTTPS requests, resolves them using the machine's configured
DNS servers, and returns the replies. You will need to have certificates for
the domains you want to serve.
Supports both DoH and JSON modes automatically, and the endpoints are
`/dns-query` and `/resolve`.
```shell
# Serve DNS over HTTPS requests, take certificates from letsencrypt.
DOMAIN=yourdomain.com
dnss -enable_https_to_dns \
-https_key=/etc/letsencrypt/live/$DOMAIN/privkey.pem \
-https_cert=/etc/letsencrypt/live/$DOMAIN/fullchain.pem
```