Skip to main content

Duck DNS

A simple setup for your own free Dynamic DNS domain, ideal for (but not limited to) setups hosted at home.

This will allow you to access your server remotely through a domain, rather than having to remember the dynamically changing IP

Registering at Duck DNS

You need a (free) account with Duck DNS in order to be able to use their service.

After logging in, please create your Duck DNS domain. There is a limit of 5 domains per account.


You can start the installation by running the following command. This will register the IP of your machine to your domain at Duck DNS, and schedule automatic updates in order to detect changes in your IP in the future.

sudo box install duckdns

During the installation you will be asked for your Duck DNS domain, and your Duck DNS token. You can find both of these on your profile page after logging in.

Duck DNS Token and domain registration

Your full domain is the "domain" in the image below, plus "". Therefore, in the example below, the full domain would mean

Further steps

Assuming you are using a home setup, we suggest you to set up static IPs on both your machine and your router, and then setting up the port forwarding. A great resource for this is

Depending on your installed applications, you might need to forward different ports.

If you intend to use any applications facilitated by nginx (You probably do...), we highly suggest you to install letsencrypt through box. This will give you a valid SSL certificate as well as set your nginx configuration to use the new domain name.

Install options

None of these are required for you to define if you want an easy install. If you would like to do something custom, then here are some options for you.

Make sure you know what you're doing!

Please note that it is difficult for us to support these options as they are custom for each install

None of the options are sanity-checked on install so setting something wrong could break your installation.

Again, you do not need to set these if you don't know what you're doing.

There are a couple options you can set before installing transmission through export.

If you'd like to use one of these, run export option=value before running the install command.

The following variables are exposed:
  • duck_subdomain
    • e.g. test003, or my-house.
    • Do NOT include the if you are using the environment variable
  • duck_token
    • e.g. abcd12e3-ab1c-123a-a1bc-123abc45d678

As an example, executing export duck_subdomain="my-house" will set the value of the variable for use in the script.

You can then run the installation command, and the values will be ingested.

Note: If you are using sudo ..., please use sudo -E ... for these variables to be considered in the installation.

Removing Duck DNS

You can get rid of all the files as well as the automatic refresh behavior by running the command below.

Please note: This will also make a call to Duck DNS to un-set the IP from your domain.

sudo box remove duckdns

Changing domain and token after installation

Please remove duckdns with box and install it again. This will double-check that everything is correct for you.

sudo box remove duckdns && sudo box install duckdns

However, we won't stop you from editing the full script in /opt/duckdns/ and changing the values there, just make sure to get a new letsencrypt cert if you had one before.