Guide: Setting Up a HNS-Bridge DNS Resolver & HNSD Light Client

By: Thomas Costanzo

Jan 24, 2022

This guide will walk you through setting up your own Handshake DNS Resolver that runs from your own instance of HNSD (the Handshake light client written in node.js).

A self-hosted DNS resolver for Handshake will make your bridge available for anyone to open any HNS TLD/SLD on the HNS Blockchain, using any device/browser of your choice.

There are currently a few resolvers out there, but the more we have, the better. A few examples of HNS DNS resolvers are hns.to, rsvr.xyz, and hns.is.

The way you would use them would look like this: costanzo.hns.to / costanzo.rsvr.xyz and costanzo.hns.is . Costanzo/ is the TLD on HNS public blockchain, and the remaining parts are the resolver that you’re using.

There will be 2 things that needs to be done to complete your own DNS resolver.

You will need HNSD setup (guide below).
The actual HNS-Bridge created by Angrymouse on Github.

So let’s get started.

PART 1, Compiling HNSD lite node on Ubuntu 20.x

First, you’ll need to install Node.JS 14 and some build tools on your Ubuntu server:

sudo apt update
sudo apt upgrade
curl -sL https://deb.nodesource.com/setup_14.x | sudo bash -
sudo apt -y install git nodejs gcc g++ make npm automake autotools-dev libtool bind9-utils dnsutils net-tools unbound
sudo npm install -g pm2 node-gyp

Then clone HNSD repo to your home dir and build it from source:

git clone git://github.com/handshake-org/hnsd.git ~/hnsd
cd ~/hnsd
./autogen.sh && ./configure && make

Now setup pm2 (node.js process manager) to run it in background:

sudo pm2 autostart

If it suggests some commands to run, then run it

Now start your HNSD lite node in background with pm2:

pm2 start ./hnsd — name=”hnsd” — -p 4 -r 127.0.0.1:5341 -n 127.0.0.1:5369 -i 0.0.0.0
pm2 save

You’re done with installing!

Check your HNSD node by digging it:

dig @127.0.0.1 -p 5341 namebase +dnssec

If it shows something like this:

; <<>> DiG 9.16.1-Ubuntu <<>> @127.0.0.1 -p 5341 namebase +dnssec
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 3527
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags: do; udp: 4096
;; QUESTION SECTION:
;namebase. IN A;; ANSWER SECTION:
namebase. 139 IN A 52.43.158.89;; Query time: 940 msec
;; SERVER: 127.0.0.1#5341(127.0.0.1)
;; WHEN: Sun Jan 02 19:43:36 EST 2022
;; MSG SIZE rcvd: 53

Then my congratulations! You installed HNSD light client! Now move to installing HNS-Bridge if you want to install it! If your terminal output looks different than whats above, then you did something wrong. Try asking people on this discord server for assistance.

PART 2, Installing HNS-bridge on Ubuntu 20.x

Build tools

Since you installed HNSD, needed tools are already installed, my congrats!

Downloading code and installing dependencies

git clone https://github.com/angrymouse/hns-bridge ~/hns-bridge
cd ~/hns-bridge
npm install

Buying a domain

To setup HNS-bridge, you need to buy traditional domain for your bridge somewhere, where doesn’t matter (we recommend Namecheap, as they’re Handshake friendly).

This is needed to make your bridge accessible by <yourdomain>.

Example: <handshake-domain>.hns.is, angrymouse.hns.is, costanzo.rsvr.xyz

When domain is bought, point * and @ by A records to external IP address of YOUR server on which you’ll run HNS-bridge.

Configuring HNS-Bridge

HNS-Bridge uses config.json to configure it

Setup should look like this:

{
“nameservers”: [
“127.0.0.1:5341”
“103.196.38.38”
],
“port”: 80, // Note: this value must be 80 to work
“domainMap”: {
“<your-domain-name>”:”” // E.g “hns.is”:”” or “rsvr.xyz”:””
},
“rootRedirect”: “
https://angrymouse.hns.is/
” // Where your domain’s root will redirect when calling bare domain (rsvr.xyz but not portfolio.costanso.rsvr.xyz)
}

Don’t forget to remove // with lines after it — that’s comments, if you don’t remove it then config will be invalid and bridge won’t work!

Opening ports

Usually there’s UFW firewall on Ubuntu. If you installed another just open port 80. Here’s the command for enabling ufw:

sudo ufw allow http

Running HNS-bridge

To run HNS-bridge in daemon mode use pm2:

pm2 start . — name=”hns-bridge”
pm2 save

Congrats!

You made it! Don’t forget to open port 80 on your router if you use home servers, and enjoy your new HNS-Bridge!

Special thanks to Angrymouse for his HNS-Bridge that he created on his Github, and assistance his with this write up. Contact us with future ideas of what to build next!

Costanzo/ and/or Angrymouse/

BlockChannel

Discussion about this post