FDNS(1) fdns man page FDNS(1)
NAME
fdns - Firejail DNS over HTTPS/TLS proxy
SYNOPSIS
Start the server (root user):
fdns [OPTIONS]
Start the monitor (regular user):
fdns --monitor
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 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
Allow all DNS query types; by default only A queries are al‐
lowed. In case --ipv6 is set, AAAA queries are also allowed.
--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 do‐
mains. 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: 40 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 [email protected]
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 con‐
nection open. For most servers we are using values between 25
and 40 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 specify‐
ing 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 (ad‐
blocker, 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
--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 ev‐
erything 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 direc‐
tory. This is the only directory allowed by our AppArmor pro‐
file.
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
Setup FDNS on a workstation
You would need to set FDNS as your DNS server in /etc/resolv.conf:
$ cat /etc/resolv.conf
nameserver 127.1.1.1
You can also use Firejail security sandbox to redirect all the DNS
traffic to 127.1.1.1, where FDNS listens by default. Firejail decouples
the DNS functionality, allowing each sandbox to have its own DNS set‐
ting. Your system DNS configuration is not touched. If things go
wrong, you won't lose your Internet connectivity. Here are the steps:
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 inter‐
face:
$ sudo fdns --proxy-addr=192.168.1.44 --daemonize
You can also add a specific tag as --server=security or --server=fam‐
ily.
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 de‐
fault?
As root user, add the following two lines in /etc/firejail/glob‐
als.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 pro‐
cesses
/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)
0.9.74.2 Sep 2024 FDNS(1)
fdns 