When I started working on my first issue on TXTDirect I had no idea how to even setup and use the project. Didn’t know anything about DNS and its concepts and was looking for a quick way to get familiar with the project. With the help of my colleagues I was able to start an instance CoreDNS and setup TXTDirect on my laptop. After running the dependencies and TXTDirect, it was the time to implement a simple scenario to see how it works.

One of the simple use cases of TXTDirect was giving fancy vanity URIs to my projects to get rid of memorizing the ports. For example you can have custom URIs like azathoth.frontend and azathoth.backend for your projects to be free from memorizing the port number of each running project on your machine.

Installation

Before installing TXTDirect you need to first install CoreDNS or any other DNS server on your machine. To install CoreDNS, you can use your system’s package manager or compile the project from source. I personally prefer to compile every Go program from the source to check its code in the meanwhile and also always be sure that I’m using the latest version. But if you use an distro like Arch or Manjaro you’re safe cause you can always get the latest version from AUR.

Install CoreDNS from source

To install CoreDNS from source you first have to clone it and then move the its directory and run the make command.
Note: You have to install GNU’s make tool on your machine if you don’t have it already. You can run make -v command to see if you have it or not.

$ git clone https://github.com/coredns/coredns
$ cd coredns
$ make

After running the make command you can find a binary file named coredns in the directory that you ran make command.

To be sure that everything is fine you can run ./coredns -version command.

Install TXTDirect

You have two ways to install TXTDirect. One is to fetch the project from GitHub and compile it from source and the other way is to use our Docker image and run it inside a docker container.

Install TXTDirect from source

Just like CoreDNS you should have GNU’s make tool to compile the project. Fetch the code using go get command and move to project’s directory inside your $GOPATH. Then run the make build command to compile the project for your distro.

$ go get go.txtdirect.org/txtdirect
$ cd $GOPATH/src/go.txtdirect.org/txtdirect
$ make build

Then you can run the generated binary using $ ./txtdirect command to be sure everything works fine. It probably shows a server running on port 2015.

Install and use TXTDirect with Docker

Just like the previous section, fetch the project using go get command and run the docker-run target using make instead of build.

$ go get go.txtdirect.org/txtdirect
$ cd $GOPATH/src/go.txtdirect.org/txtdirect
$ make docker-run

When you run make docker-run it will start an container and builds TXTDirect, then uses the binary generated by the first container to create an Docker image which runs TXTDirect on Alpine. Then it will run an container with that image and an instance of TXTDirect is running inside that container.

Configuration

After installing CoreDNS and TXTDirect it’s time to setup our DNS records and config TXTDirect. Generally if you want to add a domain and configure it in TXTDirect, you have to follow these steps:

1. Add domain to hosts file aka /etc/hosts
2. Add TXT records for it in your DNS zone
3. Add domain to TXTDirect config

hosts file

First of all you should add the domains that you want to use in your records to your OS’ hosts file.
For the sake of simplicity, we will stick to Linux based machines in this tutorial. You can find the hosts file in the /etc/hosts. Open it with your favorite editor and add your domains like the example below:

#<ip-address>  <hostname.domain.org> <hostname>
127.0.0.1   localhost.localdomain   localhost   lovecraft
::1 localhost.localdomain   localhost   lovecraft

# TXTDirect
127.0.0.1 azathoth.frontend
127.0.0.1 azathoth.backend
127.0.0.1 nyarlathotep.thetld
127.0.0.1 hastur.anothertld

DNS Records

If you don’t have any ideas about how DNS works I suggest you to read this amazing article by Justin Ellingwood on DigitalOcean: An Introduction to DNS Terminology, Components, and Concepts

Summary for those who don’t want to read a whole article:
Basically when a DNS server recieves an request, it looks into a file called Zone File which hold the DNS records and looks for the right record for that request. Most of people will think a zone file only contains infomation about which domain points to which IP address. But there are lots of more DNS types for different tasks. One of those types that TXTDirect works with is TXT type. Basically a TXT resource record provides the ability to associate arbitrary text with a host or other name. The arbitary text can be anything you want, but in TXTDirect we have a set of standards for the TXT records that are a bit different in each redirect type.

Sample DNS records

Here is an sample zone file that we use in this tutorial to use with CoreDNS and tell TXTDirect to find use these records to redirect the requests.

@                   3600 IN SOA     ns.example.com. domains.example.com. (
                                      2017202003   ; serial
                                      5m           ; refresh
                                      5m           ; retry
                                      1w           ; expire
                                      12h    )     ; minimum

@                  86400 IN NS      ns.example.net.
@                  86400 IN NS      ns.example.nl.


azathoth.frontend.                IN A 127.0.0.1
_redirect.azathoth.frontend.      IN TXT "v=txtv0;to=http://127.0.0.1:3000;type=host;code=302"

azathoth.backend.                 IN A 127.0.0.1
_redirect.azathoth.backend.       IN TXT "v=txtv0;to=http://127.0.0.1:4000;type=host;code=302"

As you can see we define two records for each domain, one to point the domain to the IP address and one TXT record that contains TXTDirect’s record fields.

TXTDirect TXT records

As you can see in the sample zone file, there are key-value fields inside each TXT record. Each redirect type has it own set of fields to work with but since host is the simplest type it only needs to= field and code= field is optional.

Fields description:

• to=: The endpoint that you want to redirect the request.
• code: Redirect status code that will be used.
• v=: The TXTDirect’s record version.

For more information about redirect types and their fields you can check TXTDirect’s Documentation

Configure and start CoreDNS

Now that we have a zone file we have to start CoreDNS and feed it with the records. To start CoreDNS you have to write a config file called Corefile and give it the path to your zone file.
Here is an example of a Corefile:

.:5353 {
  file ./path/to/zonefile zonefile
  forward . 8.8.8.8
  errors stdout
  log
}

The first line defines the port that CoreDNS listens to for DNS queries and the second line is the path to your zone file.

Now to start the CoreDNS instance, run this command:

$ coredns -conf ./Corefile

The output should be something like this:

.:5353
2019-08-27T22:16:04.904+04:30 [INFO] CoreDNS-1.5.2
2019-08-27T22:16:04.904+04:30 [INFO] linux/amd64, go1.12, cfc4948f-dirty
CoreDNS-1.5.2
linux/amd64, go1.12, cfc4948f-dirty

Configure and start TXTDirect

Now that we have our zone file setup and a running instance of CoreDNS it’s time for configuring TXTDirect.

Create a file and name it whatever you want and paste this example in it.

azathoth.frontend:80, azathoth.backend:80 {
    txtdirect {
        enable host
        resolver 127.0.0.1:5353
        logfile stdout
    }
    log / stdout
    errors stdout
}

• azathoth.frontend:80, azathoth.backend:80:
  This line tells TXTDirect to listen for which domains.
  Important Note: Be sure to run TXTDirect with sudo since we don’t want to use ports anymore it should listen on port 80. Feel free to change the ports and don’t use sudo when running TXTDirect.
• txtdirect {} block:
  This block is where the actual TXTDirect config will be written.
• enable host:
  This line enables the host redirect type which is TXTDirect’s simplest type and basically it only redirects an incoming request to a specific endpoint with a custom status code defined in the TXT record. To learn about the other types you can check TXTDirect’s Documenation.
• resolver 127.0.0.1:5353:
  In this line we tell TXTDirect to use our custom DNS resolver (The running CoreDNS instance) instead of system’s default resolver.
• logfile stdout: You can tell TXTDirect where to write its logs. Available options are [stdout, stderr and PathToAFile].
• log and errors outside txtdirect block:
  These configs belong to the running web server’s logs and errors.

Now to start TXTDirect you have to run this command:

$ ./txtdirect -conf /path/to/config/file

Note: As I mentioned earilier, you have to run the command above with sudo if you want to use port 80 and don’t have to remember each project’s port.

---

Well, that’s it! Now you have an instance of TXTDirect which redirect every incoming request for azathoth.frontend and azathoth.backend to their own endpoints that are specified in the zone file. Please feel free to checkout our documenation and learn more about the other redirect types. I will promise that you wouldn’t be disappointed cause we have lots of more types for managing your Go packages, Docker images and etc.

Hope this article was helpful for you. Since it’s my first blog post, please let me know if I had any problems either technical or grammer issues.

P.S: Will write another article about how DNS works and what are its main concepts. Be sure to check my blog again in a few weeks (probably 2 weeks cause I already have plans for another post) for the article. Will try my best to keep it as simple as possible so everyone who don’t have any previous background in this field to understand the concepts.