man fdns

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

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.

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

       --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.
              The typical way to start FDNS as network proxy is

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

       --debug
              Print debug messages.

       --debug-transport
              Print HTTP2 debug messages.

       --debug-ssl
              Print SSL/TLS debug messages.

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

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

       --disable-local-doh
              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.

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

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

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

              Example:
              $ fdns --list
              Current zone: Europe
              42l - non-profit, France, Europe
                   https://42l.fr
              aaflalo - Netherlands, Europe, adblocker
                   https://www.aaflalo.me
              appliedprivacy - non-profit, 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/
              [...]

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

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

              Example:
              $ sudo fdns --log-timeout=60

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

              Example:
              $ fdns --monitor

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

              Example:
              $ fdns --monitor=127.2.2.2

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

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

       --proxy-addr-any
              Listen on all available  system  interfaces  and  127.0.0.1  for
              loopback interface.

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

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

       --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=non-profit
              $ sudo fdns --server=family
              $ sudo fdns --server=https://dns.google/dns-query
              $ sudo fdns --server=dot://dot1.applied-privacy.net

       --test-server
              Test all the servers from your geographical zone.

              Example:
              $ 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-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.

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

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

              $ fdns --test-server=dot://dot1.applied-privacy.net
                 SSL/TLS connection: 770.46 ms
                 DoT query average: 137.26 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

       --zone=zone-name
              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
              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
       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 inter‐
       faces,  and  127.0.0.1 for loopback interface. The default 127.1.1.1 is
       not used in this case.

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

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

              $ sudo fdns --proxy-addr=192.168.1.44 --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‐
       dress 192.168.1.44:

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

       Start a regular proxy for yourself:

              $ sudo fdns --server=security --daemonize

       Check the proxies status:

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

       Monitor kids proxy:

              $ fdns --monitor=192.168.1.44

       Monitor your proxy:

              $ fdns --monitor

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

              $ sudo kill -9 11890

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

FAQ
       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‐
       fault?
              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
              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/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

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
       firejail(1)

0.9.64                             Oct 2020                            FDNS(1)