Friday, November 17, 2017

Running Technitium DNS Server on Ubuntu Linux

Updated: 11 Feb 2024

Technitium DNS Server is build to be cross platform using the .NET. You can run the DNS Server Portable App on Windows, Linux, or macOS by using ASP.NET Core 8 Runtime. Raspberry Pi with an arm7 CPU is supported and thus both Raspberry Pi 1 and Raspberry Pi Zero which have arm6 CPU are not supported.

This post is written for Ubuntu Linux but, you can easily follow similar steps on your favorite distro.

This blog post is updated regularly to provide latest instructions to install the DNS Server. So, refer it when you are about to do a fresh installation.

Using Automated Installer / Updater

Automated installer script can be used to install or update the DNS Server. The automated installer script has been tested on following distros:

  • Ubuntu Server (x64)
  • Ubuntu Desktop (x64)
  • Raspbian (Buster) (ARM32)
  • CentOS 8.2 (2004) (x64)
  • Fedora Server 32 (x64)
The installer script may work on other distros and platforms as well.

curl -sSL | sudo bash

NOTE! If you have a firewall installed, you will need to allow these ports manually:

  • 5380/tcp (for web console access)
  • 53443/tcp (for web console HTTPS access)
  • 53/udp (default DNS service)
  • 53/tcp (default DNS service)
  • 853/udp (DNS-over-QUIC service)
  • 853/tcp (DNS-over-TLS service)
  • 443/udp (DNS-over-HTTPS service over HTTP/3)
  • 443/tcp (DNS-over-HTTPS service over HTTP/1.1 and HTTP/2)
  • 80/tcp (DNS-over-HTTP service for reverse proxy or certificate renewal HTTP challenge)
  • 67/udp (if you plan to use the built-in DHCP server)

Using Automated Uninstaller

Automated uninstaller script can be used to remove the DNS Server that was installed using the above automated installer script. The uninstaller script will remove both the DNS Server and .NET runtime.

curl -sSL | sudo bash

NOTE: The uninstaller will set your /etc/resolv.conf file to use and DNS servers. To restore the defaults follow the steps for your distro:

  • Ubuntu Server, Ubuntu Desktop, CentOS, or Fedora
    sudo systemctl enable systemd-resolved
    sudo systemctl start systemd-resolved
    sudo rm /etc/resolv.conf
    sudo ln -s /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf
    The above steps will restore the default systemd-resolved setup.
  • Raspbian (Buster)
    sudo rm /etc/resolv.conf
    sudo resolvconf -ul
    The above steps will restore the default resolvconf setup.

Deploying Docker Container

You can install the DNS Server using the official Docker image available on Docker Hub.

Download the docker-compose.yml file and edit it as per your deployment requirements. Once the file is ready, run the following commands to create a new Docker container using the docker-compose.yml file as shown below:

docker compose up -d

To update an existing container, run the following commands:

docker compose down
docker image rm technitium/dns-server
docker compose up -d

Installing DNS Server Manually

Install the ASP.NET Core 8 Runtime from here. If you want to install ASP.NET Core Runtime on Raspberry Pi, use the instructions in this blog post to install it manually.

Once you have installed ASP.NET Core Runtime, start Terminal or SSH into the server and follow the steps below to install DNS Server on Ubuntu:

  1. Download DNS Server portable app using wget and extract it.
    sudo mkdir -p /opt/technitium/dns
    sudo tar -zxf DnsServerPortable.tar.gz -C /opt/technitium/dns
  2. You can now run the DNS Server directly from console as a standalone app.
    cd /opt/technitium/dns
    sudo ./
  3. Or, if your distro uses systemd, follow these steps to install it as a daemon.
    sudo cp /opt/technitium/dns/systemd.service /etc/systemd/system/dns.service
    sudo systemctl enable dns.service
    sudo systemctl start dns.service

    You may want to check the systemd log entries to find issue if the daemon fails to start:

    journalctl --unit dns --follow

  4. Open the url http://<server-ip-address>:5380/ to access the web console.

Updating DNS Server Manually

Make sure you got the ASP.NET Core 8 Runtime from here. Start Terminal and follow the steps below to update DNS Server on Ubuntu:

  1. Download DNS Server portable app using wget and extract it.
    sudo tar -zxf DnsServerPortable.tar.gz -C /opt/technitium/dns
  2. If your distro uses systemd, follow these steps to restart the DNS Server daemon.
    sudo systemctl restart dns.service

    You may want to check the systemd log entries to find issue if the daemon fails to start:

    journalctl --unit dns --follow

  3. Open the url http://<server-ip-address>:5380/ to access the web console.

Note! The installation folder has been changed from the old "/etc/dns" to "/opt/technitium/dns" in the above instructions. You must extract the files into the folder in which you have the DNS server installed.

Common Issue With Ubuntu

If you are using Ubuntu Desktop, you may find dnsmasq or systemd-resolved daemon already running on UDP port 53 preventing the DNS Server to listen on the same port. You can check the DNS Server log file from the web console to confirm the issue by finding this error:

[2019-01-01 07:30:59 UTC] [] System.Net.Sockets.SocketException (98): Address already in use
   at System.Net.Sockets.Socket.UpdateStatusAfterSocketErrorAndThrowException(SocketError error, String callerName)
   at System.Net.Sockets.Socket.DoBind(EndPoint endPointSnapshot, SocketAddress socketAddress)
   at System.Net.Sockets.Socket.Bind(EndPoint localEP)
   at DnsServerCore.DnsServer.Start() in Z:\Technitium\Projects\DnsServer\DnsServerCore\DnsServer.cs:line 811

You may confirm if its dnsmasq or systemd-resolved by running sudo netstat -nlpu command.

Follow these steps below to disable the dnsmasq service:

  1. Edit the NetworkManager.conf file to disable dnsmasq service:
    sudo nano /etc/NetworkManager/NetworkManager.conf
    Comment out the dns=dnsmasq line by adding # character at the beginning like this #dns=dnsmasq and exit the editor by pressing CTRL+X and enter y to save the file.
  2. Restart the computer to apply changes as shown below:
    sudo reboot now
  3. After system reboot, open Terminal and check DNS Server logs again from the web console.

Follow these steps below to disable the systemd-resolved service:

  1. Disable the systemd-resolved service and stop it:
    sudo systemctl disable systemd-resolved
    sudo systemctl stop systemd-resolved
  2. Configure /etc/resolv.conf as shown below:
    sudo rm /etc/resolv.conf
    sudo echo "nameserver" > /etc/resolv.conf
  3. If you are using Ubuntu Desktop then edit your /etc/NetworkManager/NetworkManager.conf using nano:
    sudo nano /etc/NetworkManager/NetworkManager.conf
    Put the following line in the [main] section of your /etc/NetworkManager/NetworkManager.conf as shown below:
    Restart network-manager:
    sudo service network-manager restart
  4. Now restart the DNS Server and check logs again from the web console.
    sudo systemctl restart dns.service

Build From Source Code

You can also build the DNS server from source and install it manually by following the Build Instructions.

That's it!

The DNS Server is running and you can configure your network with the IP address of this computer for DNS resolution.

Check out the web console to create zone, check cached zones, access DNS client tool and configure server settings.

The DNS Server creates a folder named config in the current folder which contains the server config and zone files. Make sure you copy this folder while moving the DNS server folder if you want all the zone files and config to persist.

For any related queries, feel free to comment on this post.

Technitium DNS Server Released!

Technitium DNS Server is an open source tool that allows anyone to run DNS server on their computer or local network. Its aimed towards software developers who like to simulate live production scenarios on their laptop or local network setup for testing or debugging purposes. However, it can be used for any DNS related requirement. Applications of using your own local DNS server is limited only by the your imagination!

Technitium DNS Server Web Console

The DNS server is cross platform and can be deployed on Windows, Linux or macOS (using Mono Framework or .NET Core). The DNS portable console app allows running the service instantly with zero initial configuration, just run the executable and its ready. The DNS server provides web console access that allows it to be accessible over network.

A unique feature available with this server is to enable/disable hosted zones with a single click allowing switching between staging/testing setup to live production setup instantly. Once a zone is disabled, the DNS server will start recursively resolving the domain and use cached results. When the zone is enabled, the records hosted on the server override the cached results. This reduces a lot of efforts when trying to achieve similar thing using hosts file. Hosted records can be set with low TTL values to force the operating system DNS client to re-query.

The DNS server has many standard features like recursion, caching, wildcard sub domains, forwarders, IPv6 support etc. A very useful and frequently used feature is the DNS Client tool included with the web console. This DNS Client tool is a general purpose DNS resolver that can be used to query any name server accessible over the network. The DNS Client can also perform recursive query on its own and display results from the authoritative name server for the given domain. The recursive query feature saves time by automatically finding out the authoritative name servers via the root servers. DNS Client is also available as a separate online tool at website.

Apart from just resolving queries, the DNS Client also provides a very useful feature to import records from the output of the query into the local DNS. This feature is really useful when you quickly want to copy existing records for a given domain. You can query with type ANY which would list out all possible records or use specific type needed, and import them in one go into the local server zone. You may then edit a few records with value that you need for testing and its ready to use. With query type ANY, its advised to use TCP protocol since the UDP protocol may not accommodate all the records resulting in a truncated response.

Technitium DNS Server include following features:

  • Fully manageable local DNS server.
  • Wildcard sub domain support.
  • Disable/Enable hosted zones for quick switching between staging & production.
  • DNS Client tool for resolving queries.
  • Import records feature allows to import records of live domain using DNS Client.
  • Recursive querying support.
  • Web console for allowing access over network.
  • DNS caching with cache viewer interface in web console.
  • Forwarders setup to allow chaining other DNS server to reduce response time.
  • IPv6 network support in DNS server core for querying.
  • Built-in system logs and query logs.
  • Cross platform implementation for running on Linux or macOS using Mono Framework or .NET Core.

There are many applications of having a self hosted local DNS server. Some of them are:

  • Software developers or web developers can simulate live setup without need to use hosts file.
  • Security researchers can use it in their lab setups for spoofing domain names while performing experiments.
  • Users can keep watch on domain being used by various applications using the Cached Zone listing.
  • Block certain domains to partially or fully fail a website/application feature. User can block domain by creating an empty zone such that the application/website using that domain can no longer get the right IP address to the server failing all requests.

It must be noted that this DNS server is not suitable to be used for production or any critical application. The software is released as alpha version denoting that its not yet stable and may have bugs.

Technitium DNS Server is open source and available under GNU General Public Licence (GPL) v3 on GitHub.

Comments and feedback are things that help push new features and improve usability, and thus are most welcome. Send your feedback to or leave your comments below.