.TH FDNS 1 "MONTH YEAR" "VERSION" "fdns man page"
.SH NAME
fdns \- Firejail DNS over HTTPS/TLS proxy
.SH SYNOPSIS
Start the server (root user):
.PP
.RS
fdns [OPTIONS]
.RE

Start the monitor (regular user):
.PP
.RS
fdns --monitor
.RE

.SH DESCRIPTION
FDNS is an encrypted DNS proxy server for small networks and Linux desktops.
To speed up the name resolution FDNS caches the responses, and uses a configurable
adblocker and privacy filter to cut down the unnecessary traffic.

We preconfigure FDNS with a large list of DoH/DoT service providers. For privacy reasons we
use only services from non-logging providers. We prefer servers run out-of-pocket by
students, engineers, open-source enthusiasts, privacy-oriented non-profit organizations, etc.
Currently there are more than 100 such servers on our list.

We also track a corporate category with four providers: Adguard, CleanBrowsing, Cloudflare,
and Quad9. All have a non-logging privacy policy that will work in most parts of the world.

The servers are organized using a simple geographically-aware tagging system. This allows the
user to request specialized services such as adblocking, security, family filters, etc.

Once started, FDNS chooses a server at random, as close geographically as possible.
We derive the computer location from the timezone setting. There are no IP packets sent
out to geolocation services. Three geographical zones are defined so far: Americas,
AsiaPacific and Europe. Use --list=all option to print all the servers and the corresponding tags.

.SH OPTIONS
.TP
\fB\-\-allow-all-queries
Allow all DNS query types; by default only A queries are allowed. In case --ipv6 is set,
AAAA queries are also allowed.
.TP
\fB\-\-allow-expired-certs
Allow expired SSL certificates during SSL connection.
.TP
\fB\-\-allow-self-signed-certs
Allow self-signed SSL certificates during SSL connection. Use this option for bringing up new servers.
.TP
\fB\-\-blocklist=domain
Block domain and return NXDOMAIN.
.br

.br
Note: Blocking domains can also be requested in /etc/fdns/hosts file. This setting is global, and it will block the domains in
all fdns instances running on your computer. Use --blocklist when you have multiple fdns proxies running,
each instance with a different blocklist.
.br

.br
Example:
.br
$ fdns --blocklist=fonts.googleaps.com

.TP
\fB\-\-blocklist=file=fileman
Block all domains listed in the file.
.br

.br
Example:
.br
$ fdns --blocklist-file=cloudflare

.TP
\fB\-\-cache-ttl=seconds
Change DNS cache TTL, in seconds. By default we use a fixed cache TTL of 40 minutes.
.TP
\fB\-\-certfile=filename
Use an SSL certificate file in PEM format. By default we use the certificates installed
by OpenSSL.
.br

.br
Example:
.br
$ sudo fdns --certfile=/etc/ssl/certs/ca-certificates.crt
.TP
\fB\-\-daemonize
Detach from the controlling terminal and run as a Unix daemon. The typical way to start
FDNS as network proxy is
.br

.br
$ sudo fdns --proxy-addr-any --daemonize
.br
.TP
\fB\-\-debug
Print debug messages.
.TP
\fB\-\-debug-transport
Print HTTP2 debug messages.
.TP
\fB\-\-debug-ssl
Print SSL/TLS debug messages.
.TP
\fB\-\-details
SSL connection information, HTTP headers and network traces are printed on the screen during the testing
phase of the connection.
.br

.br
Example:
.br
$ fdns --test-server=cloudflare --details
.br
$ sudo fdns --server=cloudflare --details
.TP
\fB\-\-disable-local-doh
Disable DoH services for applications running on the local network.
NOTE: Applications can still use an external DoH server if they have a hardcoded IP-Address.
If you realy want to block other DoH connection you must use your firewall.
.TP
\fB\-\-forwarder=domain@address
Conditional domain forwarding to a different DNS server.
.br

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

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

.TP
\fB\-\-help, \-?, \-h
Print command-line options and exit.
.TP
\fB\-\-ipv6
Allow AAAA requests. Use this option if you have Internet IPv6 connectivity. By default IPv6 queries are disabled.


.TP
\fB\-\-keepalive=value
Use this session keepalive value instead of the one in the server file. A HTTP2 PING exchange is initiated if there is
no DNS query activity in order to keep the HTTP 2 connection option. For most servers we are using a random value between 60 and 90 seconds.
In many cases you can bump it above 120 seconds.
.br

.br
Example:
.br
$ sudo fdns --keepalive=120 --server=coudflare
.TP
\fB\-\-list
List the DoH service providers available in your current zone.
.br

.br
Example:
.br
$ fdns --list
.br
Current zone: Europe
.br
42l - non-profit, France, Europe
.br
	https://42l.fr
.br
aaflalo - Netherlands, Europe, adblocker
.br
	https://www.aaflalo.me
.br
appliedprivacy - non-profit, Austria, Europe
.br
	https://appliedprivacy.net
.br
bortzmeyer - France, Europe
.br
	https://www.bortzmeyer.org/doh-bortzmeyer-fr-policy.html
.br
cznic - Czechia, Europe
.br
	https://www.nic.cz/odvr/
.br
[...]
.TP
\fB\-\-list=server-name|tag|all
List the available DoH service providers based on a tag, server name, or all.
.TP
\fB\-\-log-timeout=minutes
Amount of time queries are kept for monitoring, default 10 minutes, maximum 1140 (one day).
.br

.br
Example:
.br
$ sudo fdns --log-timeout=60
.TP
\fB\-\-monitor
Start the stats monitor. Without specifying an IP address (see below), the monitor is looking for a proxy at 127.1.1.1. If it fails,
it looks for a proxy on the regular loopback address 127.0.0.1. If it fails again, it will display a proxy found on any other addresses.
.br

.br
Example:
.br
$ fdns --monitor
.TP
\fB\-\-monitor=proxy-address
Start the stats monitor for a specific FDNS instance. Run this command as a regular user in a terminal.
.br

.br
Example:
.br
$ fdns --monitor=127.2.2.2
.TP
\fB\-\-nofilter
No DNS request filtering. This disables the adblocker, the tracker filter, the coinblocker filter,
and the user hosts file installed in /etc/fdns directory.

.TP
\fB\-\-proxies
List all running instances of FDNS.
.br

.br
Example:
.br
$ fdns --proxies
.br
pid 4900, address 127.3.3.3
.br
pid 4893, address 127.2.2.2
.br
pid 4883, address 127.1.1.1 (default)
.TP
\fB\-\-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.
.br

.br
Example:
.br
$ sudo fdns --proxy-addr=127.0.0.1
.TP
\fB\-\-proxy-addr-any
Listen on all available system interfaces and 127.0.0.1 for loopback interface.
.TP
\fB\-\-qps=number
Queries per second rate limit for resolver processes, default 5. When the limit is reached, incoming
packets from the local network are dropped.
.TP
\fB\-\-resolvers=number
The number of resolver processes, between 1 and 10, default 3.
.TP
\fB\-\-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.
.br

.br
Examples:
.br
$ sudo fdns --server=cloudflare
.br
$ sudo fdns --server=non-profit
.br
$ sudo fdns --server=family
.br
$ sudo fdns --server=https://dns.google/dns-query
.br
$ sudo fdns --server=dot://dot1.applied-privacy.net
.br
.TP
\fB\-\-test-server
Test all the servers from your geographical zone.
.br

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


.TP
\fB\-\-test-server=server-name|tag|all
Test the servers based on a tag, server name, or all. Specifying a URL allows you to test servers
not yet supported by FDNS.
.br

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

.br
$ fdns --test-server=https://dns.google/dns-query
.br
   SSL connection opened in 405.68 ms
.br
   DoH response average 78.86 ms
.br

.br
$ fdns --test-server=dot://dot1.applied-privacy.net
.br
   SSL/TLS connection: 770.46 ms
.br
   DoT query average: 137.26 ms

.TP
\fB\-\-test-url=URL
Check if URL is dropped by the adblock/tracker filters.
.br

.br
Example:
.br
$ fdns --test-url=amazon-adsystem.com
.br
URL amazon-adsystem.com dropped by "amazon-adsystem.com" rule
.TP
\fB\-\-test-url-list
Check URLs as they are introduced on STDIN.
.br

.br
Example:
.br
$ cat biglist.txt | fdns --test-url-list
.br
.TP
\fB\-\-unlist=server
Remove the server from the list for this FDNS instance.
.br

.br
Example:
.br
$ fdns --unlist=quad9 --unlist=quad9-2
.br

.br
FDNS will not attempt to connect to quad9 and quad9-2 in the example above.
.TP
\fB\-\-version
Print program version and exit.
.TP
\fB\-\-whitelist=domain
Whitelist mode: resolve only the specified domains and drop everything else.
.br

.br
Example:
.br
$ sudo fdns --whitelist=gentoo.org \\
      --whitelist=assets.gentoo.org \\
      --whitelist=security.gentoo.org \\
      --whitelist=wiki.gentoo.org
.TP
\fB\-\-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.
.br

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

.br
$ sudo fdns --whitelist-file=/etc/fdns/whitelist-gentoo
.TP
\fB\-\-zone=zone-name
Set a different geographical zone.
The zones defined so far are Americas, AsiaPacific and Europe.

.SH Setup FDNS on a workstation
You would need to set FDNS as your DNS server in /etc/resolv.conf:
.br

.br
.PP
.RS
$ cat /etc/resolv.conf
.br
nameserver 127.1.1.1
.br

.br
.RE
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 setting. Your system DNS configuration is not touched.
If things go wrong, you won't lose your Internet connectivity. Here are the steps:



.TP
\fBStart FDNS:
$ sudo fdns
.TP
\fBStart your applications in Firejail:
$ firejail --dns=127.1.1.1 firefox
.br
$ firejail --dns=127.1.1.1 transmission-qt
.br
.TP
\fBStart the monitor:
$ fdns --monitor
.br
.br
.SH Setup FDNS as a network server
Install FDNS and set "nameserver 127.0.0.1" in /etc/resolv.conf. Start FDNS using --proxy-addr-any. The proxy will listen on all system interfaces, and 127.0.0.1 for loopback interface. The default 127.1.1.1 is not used in this case.
.PP
.RS
$ sudo fdns --proxy-addr-any --daemonize
.br

.br
.RE
Or you can run it only on a specific interface. Example assuming 192.168.1.44 is the IP address of eth0:
.PP
.RS
$ sudo fdns --proxy-addr=192.168.1.44 --daemonize
.br

.br
.RE
When using --daemonize, errors and warnings are posted to syslog.

.SH Running multiple FDNS proxies on the same computer
On your computer, start a proxy for the all the kids on your network, and make the proxy available
on interface eth0 on your computer at address 192.168.1.44:
.PP
.RS
$ sudo fdns --proxy-addr=192.168.1.44 --server=family --daemonize
.br

.br
.RE
Start a regular proxy for yourself:
.PP
.RS
$ sudo fdns --server=security --daemonize
.br

.br
.RE
Check the proxies status:
.PP
.RS
$ fdns --proxies
.br
pid 11890, address 192.168.1.44
.br
pid 12062, address 127.1.1.1 (default)
.br

.br
.RE
Monitor kids proxy:
.PP
.RS
$ fdns --monitor=192.168.1.44
.br

.br
.RE
Monitor your proxy:
.PP
.RS
$ fdns --monitor
.br

.br
.RE
Use the PID number from "fdns --proxies" to shutdown one proxy or another:
.PP
.RS
$ sudo kill -9 11890
.br

.br
.RE
In about 30 seconds all processes associated with this specific proxy will exit.
.SH FAQ

.TP
\fBHow do I start FDNS when I power-on the computer?
One solution that will work on any Linux computer is to start it from /etc/rc.local.
.br

.br
$ cat /etc/rc.local
.br
#!/bin/sh -e
.br
/usr/bin/fdns --daemonize
.br
exit 0
.br

.br
Systemd users, can alternative enable the fdns.service unit.
.br

.br
$ sudo systemctl enable --now fdns.service
.br

.TP
\fBHow 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:
.br

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

.TP
\fBHow do I save a list with all the DNS requests?
Start FDNS this way:
.br

.br
$ sudo fdns | tee dnslist.txt
.br

.TP
\fBHow do I check FDNS is running in the background?
Use "--proxies" command to list all FDNS proxies running on your computer:
.br

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

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

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


.TP
\fBHow do I shut down FDNS?
$ sudo pkill fdns
.br

.SH FILES
/etc/fdns/adblocker - adblocker filter distributed with FDNS
.br
/etc/fdns/coinblocker - cryptomining filter distributed with FDNS
.br
/etc/fdns/fp-trackers - first-party tracker filter
.br
/etc/fdns/hosts - user hosts file
.br
/etc/fdns/servers - DoH/DoT servers FDNS knows about
.br
/etc/fdns/trackers - tracker filter distributed with FDNS
.br
/etc/fdns/worker.seccomp - seccomp filter applied to resolver processes

.SH 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.
.PP
Homepage: https://firejaildns.wordpress.com
.br
Development: https://github.com/netblue30/fdns

.SH SEE ALSO
\&\flfirejail\fR\|(1),
\&\flnxdomain\fR\|(1)


