How to setup CNAME


I’m trying to setup OpenBalena. I would like to evaluate OpenBalena on my personal laptop running on Ubuntu 18.04 .
From the getting started:, I need to setup CNAME.
Which tool are you using to setup CNAME entries? Do you have any example file for openbalena configuration?
From my side, I tried the tool bind9 without success. I’m probably missing competencies in this domaine.

If you have already installed OpenBalena, please share your configuration !



Hi, you should set up the CNAME entries with your DNS provider (the company that manages your domain name that you want to set up OpenBalena for). It depends on the different providers.

If you let us know what is your domain name registrar or DNS provider, we can give more information, or can check their documentation for setting up CNAME entries.

Thanks for your reply.

I would like to do a try of OpenBalena solution on my local network.
I have a rasperry pi connected on this local network and want to have my laptop to host OpenBalena.
All is running on local network.
I am wondering how to setup CNAME entries.
Does the bind9 tool is the right one to do this?

From what I understand with this tool I need to edit two files,

  • a first one: /etc/bind/db.openbalena.local
  • a second one: /etc/bind/named.conf.local
    Then reload configuration with this command
    $sudo named-checkzone openbalena.local /etc/bind/db.openbalena.local
    Is it correct?

I would need help to fill these files with the required CNAME entries.

Thanks a lot in advance,

Hi @py4mac. For the benefit of other users who may find this thread, let me cover two scenarios:

  1. You have an actual internet domain name (globally resolvable by root DNS servers) like, say “”, which was “bought” through a domain name registrar - a company like, say,

  2. You have a “local” domain name that is not globally resolvable in the internet (like “openbalena.local”), and was not registered through any internet domain name registrar. Yet, you want your local network to be able to resolve names under that domain name, like “api.openbalena.local”.

The vast majority of users fall in the first category, so let me emphasise that it is not necessary to run your own DNS server (using BIND9 or otherwise) on your local network, even if you are running openBalena on a private on-premises network. Like @imrehg pointed out in his answer, by far the easiest and most reliable solution is to use the registrar’s web control panel (again, like GoDaddy’s) to register CNAME records. By the way, it’s OK to add private IP addresses to the public internet DNS; for example, it’s OK to use GoDaddy’s control panel to add a private IPv4 address like to a public DNS record like, say, “”. Of course, a private IP address is only routable within its private network, so external machines won’t be able to reach it even if they are able to resolve the DNS name.

If you are in the second category, even then there may be simpler solutions to consider before trying BIND 9. Although the openBalena guide mentions CNAME records, ultimately what matters is that your local network is able to map hostnames (like {api | registry | vpn | s3} to the IP address of your openBalena server. To this end, some options are:

  • Configuring your WiFi router - some WiFi routers offer the feature of working as a forwarding DNS server, and allow mapping host names to IP addresses.

  • Using the /etc/hosts file on Linux or MacOS (under Windows, I think the file is C:\Windows\System32\Drivers\etc\hosts), adding lines similar to the ones below (replace with the IP address of your server/laptop). Note that in this case, you’d have to configure every device separately.   s3.openbalena.local   api.openbalena.local   vpn.openbalena.local   registry.openbalena.local
  • Using dnsmasq, which is a simpler DNS server than BIND 9. Check the following page for some brief instructions, especially the section “Adding a custom domain”:
    dnsmasq will look in the /etc/hosts file of the machine it is running on, so you would add lines similar to the ones above to that machine. But then you only need to edit the /etc/hosts file of that one machine, rather than every devices’.

  • Finally, using BIND 9. I believe the following Ubuntu guide covers some of your questions:
    After the header lines (SOA, NS, PTR), your db.openbalena.local file could contain the following lines (replace with the IP address of your laptop):

laptop    IN    A
api       IN    CNAME  laptop
s3        IN    CNAME  laptop
registry  IN    CNAME  laptop
vpn       IN    CNAME  laptop


Thanks @pdcastro - great explanation man.

Something I would like to add here, relevant to running OpenBalena on your laptop to test, is that you will need someway for your devices (Pi, NUC etc) to resolve the keydomains like “api.openbalena.local” or whatever domain you choose.

Without modification to the balenaOS image running on the Pi to do this, you are stuck with the option of configuring your LAN DNS resolver OR using public DNS records. We do something similar ourselves for development and use the public DNS route, and I have personally used my DD-WRT router on my LAN to use non-public TLDs like “api.openbalena.lan”.

Summary - As long as the device can do a DNS lookup for “api.{domain you configure here}” and the other subdomains mentioned above, be able to connect over HTTPS to those servers, then it should work.

Thanks a lot for this great explanation! It helps me a lot!
I have only made changes on /etc/hosts file. It works nice!
Let’s start to load an image on RPI now! :slight_smile:


Sorry for my long delay. I’ve successfully installed OpenBalena. I’ve setup DNS routes on my laptop that’s why I successfully connect to my local Balena instance. I’ve build my image and flashed it on RPI.
My issue now is that the RPI can’t connect to my laptop due to my local network. The url api.openbalena.local is not resolved correctly. I also use DD-WRT router.
Could you please give me guidelines to setup local DNS routes inside the router?

Thanks a lot,


@py4mac sure, you need to go to Services -> Services -> Additional DNSMasq Options in the DD-WRT config…

You will need to add the relevant address=/{domain}/{IP} entries for your setup. Something like:


where is the IP of your OpenBalena host.

For all how wants to do a local installation without having an DNS server, but using a Fritz Box.
I’ve used to get the 4 needed sub domains linked to the local ip address of my openbalena server.
I just needed to enter these domains into the DNS rebind protection exception list of the Fritz Box.
By doing this I was able to get my first device connected. (It’s still offline, but this seems to be another issue other people also have as described in Devices recognized by server but always offline)

Thanks a lot for your help!
All is working now!

Best regards,

Just to add one point.
The router firmware is not DD-WRT as I initially thought by Merlin Firmware.
The step by step instruction guide is here:
All is working now, thanks!

Best regards,

Glad to read you guys got it sorted out :+1:

1 Like

Hi, I’m trying to set up scenario 2 using dnsmasq in a separate server. I’m not being able to register my device in my local openBalena installation. I can access https://api.openbalena.local/ping from other devices but not the one with balena OS.

I enabled logging on my DNS server and I see only AAAA queries for api.openbalena.local coming from this device. If I ssh into this device and run curl https://api.openbalena.local/ping I get “curl: (6) Could not resolve host: api.openbalena.local”, and no DNS query is registered in my server. Is it possible that the local DNS server in balena OS is not forwarding DNS queries that it can’t resolve?

Any help would be much appreciated!

Hello, the .local TLD is probably confusing things on your network. If you could reprovision using another domain, eg openbalena.lan, and go through the same process you may have better luck. It may be simpler however to just configure DNS on your network such that it serves a specific IP for a given host. Your laptop will most likely also need to have a static IP for this to work.

We’ll be including an mDNS broadcaster with openBalena in the next release, which would sort this kind of issues nicely, but until then you can work around it.

1 Like

I just changed the domain from openbalena.local to and it worked!

@gmerciel that’s great - thanks for letting us know!