The following Do Name Stuff (DNS) functionality is deployed to VNS3 as a plugin using the container system. These instructions cover customization of the container image that will be used so that customer variables and rule sets can be employed.

Please be familiar with the VNS3 Plug-In Configuration Guide.

Do Name Stuff Plugin - What does it do?

The Do Name Stuff plugin is built on coreDNS, a DNS server written in GO and licensed under the Apache License Version 2.

Simply stated Do Name Stuff Plugin serves DNS A records from an /etc/hosts type file that it automatically generates from clientpack tags.

Many VNS3 users run encrypted overlay topologies and need a simple way to provide DNS resolution for their overlay host addresses.

This container plugin is designed to automatically generate a list of overlay IPs and assigned names appended with a given domain suffix that will be used to answer DNS queries.

Do Name Stuff Plugin - How does it work?

Do Name Stuff plugin name resolution:

User process - Users create dns tags on client packs.
Runtime process - A process on the plugin generates an /etc/hosts style list of overlay IPs, names and appended domain names.

Getting the Do Name Stuff Plugin

From the Plugins Catalog page you can click on the Install button to import the plugin where it will then show up under the Plugins Dashboard.

Alternatively users can get the plugin by downloading the image and uploading it to your controller.

The Linux-based (Ubuntu 20.04) Do Name Stuff Plugin is accessible at the following URL: https://vns3-containers-read-all.s3.amazonaws.com/DoNameStuff/DoNameStuff_base_18-20200304.tar.gz

This is a read-only Amazon S3 storage location. Only Cohesive Networks can update or modify files stored in this location.

This URL can be used directly in a VNS3 Controller via the Web UI or API to import the container for use into that controller. (General screenshot walkthrough and help available in the plug-in configuration document.)

Launching the Do Name Stuff Plugin (Plugin Manager)

After selecting Start Instance from the Actions menu you then name your container, provide a description and the command used to execute the container.

Do Name Stuff Plugin start instance

The name and description should be something meaningful within the context of your organization and its policies.

Under the Advanced section you will find:

For the DO Name Stuff Plugin the command used to run plugin container will be: /usr/bin/supervisord

The variables you will want to add are:

API_TOKEN “The API Token value you created from the controllers Access Management section”

DOMAIN “The global domain suffix that you want to apply to all records”

The DOMAIN variable is optional as the domain name can be applied with a ‘domain’ tag on the clientpack. In the case that both are present the domain tag will override the value of the global variable.

Confirming the Do Name Stuff Plugin is Running

After executing the Start Instance operation you will need to navigate to the Instances tab.

You should see your Do Name Stuff instance with the name you specified. The Status should be Running and it should have been given an IP address on your internal plug-in subnet (in this case 198.51.100.2).

Tagging Clientpacks

Do Name Stuff Plugin clientpack tags

The Do Name Stuff Plugin utilizes the clientpack tagging mechanism of VNS3. There are two tag keys that are used:

‘dns’ - You can give one or many dns names for each client pack. If setting multiple names, separate them with colons ‘:’ and no spaces. Because the Do Name Stuff plugin is configured with round-robin enabled you can can set multiple clientpacks to have the same name, for example ( (dns: server1:web) (dns: server2:web) )

‘domain’ - The ‘domain’ tag will override the global variable DOMAIN if set. You may use one or many domain names on clientpacks. The default Do Name Stuff configuration will look first at the generated hosts file and if the record being looked up does not exist there then the request will be sent on to the defined upstream provider.

Because of the nature of domain naming syntax rules only alpha-numeric, hyphen and underscore characters are allowed.

Accessing and Customizing the Do Name Stuff Plugin

Selecting Manage from the Actions menu will bring you to the instance manager page.

Primary files for customization

The Corefile file, /opt/coredns/Corefile, is the primary file to control both the Do Name Stuff plugin and controll where to send all upstream queries that are not in the hosts file that has been generated from clientpack tags.

The following sections provide summary information about the relevant configuration sections to setup the resolve and forwarding behavior for your use-case.

Detailed documentation for configuration of the CoreDNS forward can be found here: https://coredns.io/plugins/forward/#5.3

Corefile

This section begins with . which answers all port 53 request.

The reload directive will reload any configuration changes without the need to restart the server process.

The errors directive tells coredns to log any errors. Users can add a new line with a log directive if you choose, though doing so will add considerable lines to the log as all external lookup calls will be logged.

The loadbalance round_robin directive is used in the case where you might have multiple different A records, each with the same domain name but a different IP address. Each time the server is queried, it sends the IP address to which it most recently responded with to the back of the queue.

The fallthrough directive is used to direct where queries go if not found in the hosts file.

. {
reload 5s
errors
loadbalance round_robin
hosts hosts {
reload 5s
fallthrough
}
loadbalance round_robin
forward . 127.0.0.1:5301 127.0.0.1:5302
}

Below that you will find the section that defines where to send all other DNS queries. The supplied configuration is set to loadbalance round _obin requests between Google and Cloudflare.

.:5301 {
reload 5s
errors
loadbalance round_robin
forward . tls://8.8.8.8 tls://8.8.4.4 {
tls_servername dns.google
health_check 5s
}
cache 30
}
.:5302 {
reload 5s
errors
loadbalance round_robin
forward . tls://1.1.1.1 tls://1.0.0.1 {
tls_servername cloudflare-dns.com
health_check 5s
}
cache 30
}

If you wanted to send non domain requests to a single endpoint such as your AWS DNS endpoint where your VPC CIDR is 10.0.0.0/24 here is an example:

. {
reload 5s
errors
loadbalance round_robin
hosts hosts {
reload 5s
fallthrough
}
forward . 10.0.0.2
}

Forwarding Traffic to the coreDNS DNS Plugin

Forwarding traffic to the container uses the VNS3 firewall.

VNS3 Firewall

If your Do Name Stuff plugin is going to forward lookups to upstream providers like google or cloudflare you will need a masquerade rule to allow outbound traffic

POSTROUTING -o eth0 -s 198.51.100.2/32 -j MASQUERADE

Add a destination NAT rule to the VNS3 firewall to direct DNS traffic sent to the VNS3 controllers overlay IP. This will NAT traffic to the DNS Container’s IP.

#Destination NAT inbound traffic to a <controller overlay ip> on a <destination port> and send it to the <coreDNS Listening Port> on the <coreDNS Container IP>:

PREROUTING -i tun0 -p tcp -d <controller overlay vip>/32 --dport <destination port> -j DNAT --to <coreDNS Container IP>:<coreDNS Listening Port>
PREROUTING -i tun0 -p udp -d <controller overlay vip>/32 --dport <destination port> -j DNAT --to <coreDNS Container IP>:<coreDNS Listening Port>

Here are example rules:

PREROUTING -i tun0 -p tcp -d 100.64.0.254/32 --dport 53 -j DNAT --to 198.51.100.2/32:53
PREROUTING -i tun0 -p udp -d 100.64.0.254/32 --dport 53 -j DNAT --to 198.51.100.2/32:53

Here are example rules using VNS3 variables:

PREROUTING -i tun0 -p tcp -d ${peer_1_overlay_ip} --dport 53 -j DNAT --to ${plugin_instance_1_ip}:53
PREROUTING -i tun0 -p udp -d ${peer_1_overlay_ip} --dport 53 -j DNAT --to ${plugin_instance_1_ip}:53

Running the Do Name Stuff Plugin

Once the container is running on your VNS3 controller you will not need to do anything else.

Troubleshooting the Do Name Stuff Plugin

Do Name Stuff Plugin Manager configuration

On the Plugin Instance Manage page you will find the following useful tools:

Processes / Process Manager: supervisor:

coredns - the Do Name Stuff server process. this can be stopped and started here.

names - This process queries the VNS3 api every 5 seconds to generate the hosts file. For trouble shooting purposes it can be stopped and started.

Processes / Exacutables:

generate hosts file - Running this will display the output of the code that is used to generate the hosts file. If there are errors due to invalid characters here is where you will see which ones are causing issues. You will also see errors related to the API Token.

*Invalid characters - Only alpha-numeric, hyphen and underscore characters can be used.

Do Name Stuff Plugin Manager configuration