man fdns

FDNS(1)                          fdns man page                         FDNS(1)

       fdns - Firejail DNS over HTTPS/TLS proxy

       Start the server (root user):

              fdns [OPTIONS]

       Start the monitor (regular user):

              fdns --monitor

       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, Clean‐
       Browsing,  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 set‐
       ting. There are no IP packets sent out to  geolocation  services.  Four
       zones are defined so far: EastAmerica, WestAmerica, AsiaPacific and Eu‐
       rope. Use --list=all option to print all the  servers  and  the  corre‐
       sponding tags.

              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 SSL certificates during SSL connection.

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

              Change  DNS  cache  TTL,  in  seconds. By default we use a fixed
              cache TTL of 40 minutes.

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

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

              Detach  from  the controlling terminal and run as a Unix daemon.
              The typical way to start FDNS as network proxy is

              $ sudo fdns --proxy-addr-any --daemonize

              Print debug messages.

              Print HTTP2 debug messages.

              Print SSL/TLS debug messages.

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

              $ fdns --test-server=cloudflare --details
              $ sudo fdns --server=cloudflare --details

              Disable DoH services for applications running on the local  net‐
              work.   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.

              Conditional domain forwarding to a different DNS server.

              $ sudo fdns --forwarder=libre@

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

       --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.

              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 op‐
              tion. For most servers we are using a random  value  between  60
              and  90  seconds.   In many cases you can bump it above 120 sec‐

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

       --list List the DoH service providers available in your current zone.

              $ fdns --list
              Current zone: Europe
              42l - non-profit, France, Europe
              aaflalo - Netherlands, Europe, adblocker
              appliedprivacy - non-profit, Austria, Europe
              bortzmeyer - France, Europe
              cznic - Czechia, Europe

              List the available DoH service providers based on a tag,  server
              name, or all.

              Amount  of time queries are kept for monitoring, default 10 min‐
              utes, maximum 1140 (one day).

              $ sudo fdns --log-timeout=60

              Start the stats monitor. Without specifying an IP  address  (see
              below),  the  monitor is looking for a proxy at If it
              fails, it looks for a proxy  on  the  regular  loopback  address
      If  it fails again, it will display a proxy found on
              any other addresses.

              $ fdns --monitor

              Start the stats monitor for a specific FDNS instance.  Run  this
              command as a regular user in a terminal.

              $ fdns --monitor=

              No  DNS  request  filtering.  This  disables  the adblocker, the
              tracker filter, the coinblocker filter, and the user hosts  file
              installed in /etc/fdns directory.

              List all running instances of FDNS.

              $ fdns --proxies
              pid 4900, address
              pid 4893, address
              pid 4883, address (default)

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

              $ sudo fdns --proxy-addr=

              Listen on all available  system  interfaces  and  for
              loopback interface.

              Queries per second rate limit for resolver processes, default 5.
              When the limit is reached, incoming packets from the local  net‐
              work are dropped.

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

              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.

              $ sudo fdns --server=cloudflare
              $ sudo fdns --server=non-profit
              $ sudo fdns --server=family
              $ sudo fdns --server=
              $ sudo fdns --server=dot://

              Test all the servers from your geographical zone.

              $ fdns --test-server
              Testing server aaflalo-adblocker
                   SSL connection opened in 309.55 ms
                   DoH response average 64.92 ms
              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

              Test the servers based on a tag, server name, or all. Specifying
              a URL allows you to test servers not yet supported by FDNS.

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

              $ fdns --test-server=
                 SSL connection opened in 405.68 ms
                 DoH response average 78.86 ms

              $ fdns --test-server=dot://
                 SSL/TLS connection: 770.46 ms
                 DoT query average: 137.26 ms

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

              $ fdns
              URL dropped by "" rule

              Check URLs as they are introduced on STDIN.

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

              Print program version and exit.

              Whitelist mode: resolve only the specified domains and drop  ev‐
              erything else.

              $ sudo fdns \

              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‐

              $ cat /etc/fdns/whitelist-gentoo
              # whitelist file for

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

              Set a different geographical zone.  The zones defined so far are
              EastAmerica, WestAmerica, AsiaPacific and Europe.

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

              $ cat /etc/resolv.conf

       You  can  also  use  Firejail  security sandbox to redirect all the DNS
       traffic to, 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= firefox
              $ firejail --dns= transmission-qt

       Start the monitor:
              $ fdns --monitor

Setup FDNS as a network server
       Install  FDNS and set "nameserver" in /etc/resolv.conf. Start
       FDNS using --proxy-addr-any. The proxy will listen on all system inter‐
       faces,  and for loopback interface. The default is
       not used in this case.

              $ sudo fdns --proxy-addr-any --daemonize

       Or you can run it  only  on  a  specific  interface.  Example  assuming is the IP address of eth0:

              $ sudo fdns --proxy-addr= --daemonize

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

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  ad‐

              $  sudo  fdns --proxy-addr= --server=family --daemo‐

       Start a regular proxy for yourself:

              $ sudo fdns --server=security --daemonize

       Check the proxies status:

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

       Monitor kids proxy:

              $ fdns --monitor=

       Monitor your proxy:

              $ fdns --monitor

       Use the PID number from "fdns --proxies" to shutdown one proxy  or  an‐

              $ sudo kill -9 11890

       In  about  30 seconds all processes associated with this specific proxy
       will exit.

       How 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.

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

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

              $ sudo systemctl enable --now fdns.service

       How  do I configure Firejail to send all the DNS traffic to FDNS by de‐
              As root user, add the following two lines in  /etc/firejail/gol‐
              bals.local. If the file doesn't exist, create it:

              $ cat /etc/firejail/globals.local
              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

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

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

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

       How do I shut down FDNS?
              $ sudo pkill fdns

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

       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.



0.9.64                             Oct 2020                            FDNS(1)