NAME

fdns - Firejail DNS over HTTPS/TLS proxy

SYNOPSIS

Start the server (root user):

Start the monitor (regular user):

DESCRIPTION

FDNS is a lightweight encrypted DNS proxy designed for small networks and Linux desktops. The proxy implements caching, a DNS firewall, and uses configurable adblocker and privacy filters.

Out of the box, the proxy comes with a large number of non-logging and non-censoring DoH/DoT/DoQ service providers. At startup, it chooses a server at random, as close geographically as possible. The computer's location is determined by the time zone setting.

OPTIONS

--allow-all-queries

Disable FDNS firewall - see section DNS Firewall below.

--allow-expired-certs

Allow expired SSL certificates during SSL connection.

--allow-self-signed-certs

Allow self-signed SSL certificates during SSL connection. Use this option for bringing up new servers.

--blocklist-file=filename

Load an additional blocklist file at startup. Up to 8 such files can be loaded. The blocklists are regular 127.0.0.1 or 0.0.0.0 host files. All domains in the file are considered wildcard domains. Example:

$ sudo fdns --blocklist=/usr/fdns/newblocklist

Note: If AppArmor is enabled, please place your files additional files in /etc/fdns directory.

--certfile=filename

Use an SSL certificate file in PEM format. By default we use the certificates installed by OpenSSL.

Example:
$ sudo fdns --certfile=/etc/ssl/certs/ca-certificates.crt

--daemonize

Detach from the controlling terminal and run as a Unix daemon. Example:

$ sudo fdns --daemonize

--debug

Print debug messages.

--debug-transport

Print transport layer debug messages.

--details

SSL connection information, HTTP headers and network traces are printed on the screen during the testing phase of the connection establishment.

Example:
$ fdns --test-server=cloudflare --details
Testing server cloudflare
Tags: anycast, Americas, AsiaPacific, Europe
URL: https://cloudflare-dns.com/dns-query
Bootstrap IP address: 1.1.1.1
Port: 443
TLSv1.3, ALPN h2, SNI no

HTTP Header:
-----------------------------
| (HPACK dynamic table size: 4096)
| :status: 200
| server: cloudflare
| date: Mon, 19 Jun 2023 11:20:53 GMT
| content-type: application/dns-message
| access-control-allow-origin: *
| content-length: 77
| cf-ray: 7d9b62a62ff3ff84-BOS
-----------------------------
SSL/TLS connection: 519.42 ms

Network Trace:
-----> rx 60 bytes: IP + TCP + TLS + H2-WINDOW-UPDATE
-----> rx 187 bytes: IP + TCP + TLS + H2-HEADERS + H2-DATA (end stream)

DoH query average: 64.38 ms
Header uncompressed | compressed | ratio: 185 | 28 | 6.61:1
DoH/Do53 bandwidth ratio: 2.50
Keepalive: 50 seconds

Testing completed

--fallback-server=address

In case the main DoH/DoT server is down, use this regular DNS/UDP server for fallback. By default we test and chose the fastes server from the following list: Adguard, CleanBrowsing, Cloudflare, NextDNS, and Quad9.

Example:
$ sudo fdns --fallback-server=66.70.228.164

--forwarder=domain@address

Conditional domain forwarding to a different DNS server.

Example:
$ sudo fdns --forwarder=libre@66.70.228.164

The proxy will forward all .libre domains to OpenNIC server at 66.70.228.164.

--help, -?, -h

Print command-line options and exit.

--ipv6

Allow AAAA requests. Use this option if you have Internet IPv6 connectivity. By default IPv6 queries are disabled.

--keepalive=value

Use this session keepalive value instead of the one in the server file. A query for example.com domain is initiated if there is no DNS query activity in order to keep the HTTP2 connection open. For most servers we are using values between 25 and 50 seconds. In many cases you can bump the keepalive above 120 seconds.

Example:
$ sudo fdns --keepalive=120 --server=coudflare

--list[=server-name|tag|all]

List the DoH service providers available in your current zone, or specific servers based on names or tags.

Example:
$ fdns --list
Current zone: Europe
42l - France, Europe
https://42l.fr
aaflalo - Netherlands, Europe, adblocker
https://www.aaflalo.me
appliedprivacy - Austria, Europe
https://appliedprivacy.net
bortzmeyer - France, Europe
https://www.bortzmeyer.org/doh-bortzmeyer-fr-policy.html
cznic - Czechia, Europe
https://www.nic.cz/odvr/
[...]

--monitor[=proxy-address]

Start the stats monitor in a regular terminal. Without specifying an IP address, the monitor is looking for a proxy at 127.1.1.1.

Example:
$ fdns --monitor
$ fdns --monitor=127.2.2.2

--nofilter

No DNS request filtering. This disables all domain filters (adblocker, trackers, etc.) and the user hosts file installed in /etc/fdns directory.

--proxies

List all running instances of FDNS.

Example:
$ fdns --proxies
pid 4900, address 127.3.3.3
pid 4893, address 127.2.2.2
pid 4883, address 127.1.1.1 (default)

--proxy-addr=address

Configure the IP address the proxy listens on for DNS queries coming from the local clients. The default is 127.1.1.1.

Example:
$ sudo fdns --proxy-addr=127.0.0.1

--resolvers=number

The number of resolver processes, between 1 and 10, default 2.

--server=server-name|tag|all|url

Connect to a specific server, or to a random one based on the tag and your geographical location. Using "all" will instruct FDNS to chose a server at random from the list, regardless where the server is located. You can also specify a DoH URL for servers not yet supported by FDNS.

Examples:
$ sudo fdns --server=cloudflare
$ sudo fdns --server=security
$ sudo fdns --server=family
$ sudo fdns --server=https://dns.google/dns-query
$ sudo fdns --server=dot://dot1.applied-privacy.net
$ sudo fdns --server=quic://dns.adguard.com

--server-list=filename

Specify a list of servers, default /etc/fdns/servers. If the program is confined by AppArmor, place this file in /etc/fdns directory. Access to most other directories is blocked.

Example:
$ fdns --server-list=/etc/fdns/newlist

--test-server[=server-name|tag|all]

Test all the servers from your geographical zone. You can also request a specific server or tag.

Example:
$ fdns --test-server
Testing server adguard
SSL connection opened in 281.80 ms
DoH response average 55.44 ms
Testing server cleanbrowsing
SSL connection opened in 281.73 ms
DoH response average 57.90 ms
Testing server cloudflare
SSL connection opened in 251.37 ms
DoH response average 58.23 ms
Testing server dnscrypt-ca
SSL connection opened in 421.59 ms
DoH response average 83.51 ms
[...]

$ fdns --test-server=digital-society
SSL connection opened in 640.53 ms
DoH response average 155.22 ms

--test-url=URL

Check if URL is dropped by the adblock/tracker filters.

Example:
$ fdns --test-url=amazon-adsystem.com
URL amazon-adsystem.com dropped by "amazon-adsystem.com" rule

--test-url-list

Check URLs as they are introduced on STDIN.

Example:
$ cat biglist.txt | fdns --test-url-list

--version

Print program version and exit.

--whitelist=domain

Whitelist mode: resolve only the specified domains and drop everything else.

Example:
$ sudo fdns --whitelist=gentoo.org \
--whitelist=assets.gentoo.org \
--whitelist=security.gentoo.org \
--whitelist=wiki.gentoo.org

--whitelist-file=file-name

Similar to --whitelist above, it gets the domains from a file. If running under AppArmor, put the file under /etc/fdns directory. This is the only directory allowed by our AppArmor profile.

Example:
$ cat /etc/fdns/whitelist-gentoo
# whitelist file for gentoo.org
gentoo.org
assets.gentoo.org
security.gentoo.org
wiki.gentoo.org

$ sudo fdns --whitelist-file=/etc/fdns/whitelist-gentoo

DNS Firewall

A packet-level DNS firewall is one of the security layers we implement in FDNS. Before being forwarded to the DNS server, the queries received from the local network are examined and evaluated. Only type 1 (A) and type 28 (AAAA) queries are permitted; all other queries are promptly rejected. We return NXDOMAIN (non-existent domain) in response to type 12 (PTR) and type 65 (HTTPS) queries. These effectively disables the majority of DNS tunneling tools hackers employ to transmit data stolen from local network computers. The firewall can be turned off by using the --allow-all-queries command line option,

Additionally, there is a hard cap of 20 forwarded queries per second (default). Anything above this limit is dropped, forcing the browser to try again.

Setup FDNS on a workstation

You would need to set FDNS as your DNS server in /etc/resolv.conf:

Start FDNS:

$ sudo fdns

Start your applications in Firejail:

$ firejail --dns=127.1.1.1 firefox
$ firejail --dns=127.1.1.1 transmission-qt

Start the monitor:

$ fdns --monitor

Setup FDNS as a network server

Example assuming 192.168.1.44 is the IP address of your network interface:

FAQ

How do I start FDNS when I power-on the computer?

The command you need to run at startup is

# /usr/bin/fdns --daemonize

Include this command in your system startup scripts. If your system uses Systemd (Debian/Ubuntu/Arch/RedHat etc.), enable the fdns.service unit provided in /etc/fdns/fdns.service.

$ sudo systemctl enable --now fdns.service

How do I configure Firejail to send all the DNS traffic to FDNS by default?

As root user, add the following two lines in /etc/firejail/globals.local. If the file doesn't exist, create it:

$ cat /etc/firejail/globals.local
dns 127.1.1.1
ignore dns

How do I save a list with all the DNS requests?

Start FDNS this way:

$ sudo fdns | tee dnslist.txt

How do I check FDNS is running in the background?

Use "--proxies" command to list all FDNS proxies running on your computer:

$ fdns --proxies
pid 12062, address 127.1.1.1 (default)

Or run ss and look for sockets open on port 53:

$ sudo ss -nulp
State Recv-Q Send-Q Local Address:Port Peer Address:Port
UNCONN 0 0 127.1.1.1:53 0.0.0.0:* users:(("fdns",pid=4227,fd=11))
UNCONN 0 0 127.1.1.1:53 0.0.0.0:* users:(("fdns",pid=4226,fd=9))
UNCONN 0 0 127.1.1.1:53 0.0.0.0:* users:(("fdns",pid=4225,fd=7))

How do I shut down FDNS?

$ sudo pkill fdns

FILES

/etc/fdns/list.* - domain filters distributed with FDNS
/etc/fdns/fdns.service - systemd service file
/etc/fdns/hosts - user hosts file
/etc/fdns/resolver.seccomp - seccomp filter applied to resolver processes
/etc/fdns/servers - DoH/DoT servers FDNS knows about

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

Homepage: https://firejaildns.wordpress.com
Development: https://github.com/netblue30/fdns

SEE ALSO

dnsc(1), nxdomain(1)