Ubuntu Wiki

This document is intended to be a guide for LoCo DNS administrators and LoCo contacts who have access to their domain's DNS key. This system uses TSIG for DNS changes.

The documentation here only applies to LoCo sites which have their domain names registered on Canonical's nameservers.

If you are a LoCo contact and...

• would like to have the DNS of your domain or subdomain updated,
• don't have the key for your domain and wish to have it,
• would like to have both of the above done,

...please email a GnuPG-signed message to rt@ubuntu.com with the request. In the case of an update please specify which IP address the new domain should have.

In order to make changes to a DNS entry, you must have the nsset script and the Perl bindings for DNS installed (package: libnet-dns-perl).

Steps to take

• Check that the domain is hosted on Canonical's nameservers:

$ whois ubuntu-se.org | grep Server 

• This should display something like:

Name Server:NS1.CANONICAL.COM
Name Server:NS2.CANONICAL.COM
Name Server:NS3.CANONICAL.COM

• ..if not, then the domain isn't on Canonical's nameservers and these steps don't apply to your domain.
• Write down which IP the domain is currently pointing at - this is just in case something wrong happens and we want to revert back as soon as possible. This can be done with:

$ dig @ns1.canonical.com www.site.org

• For example, with www.ubuntu-se.org:

$ dig @ns1.canonical.com www.ubuntu-se.org

• And look for the answer section (where ADD.RIS.INH.ERE is the IPv4 address of the domain):

;; ANSWER SECTION:
www.ubuntu-se.org.      3600    IN      A       ADD.RIS.INH.ERE

• Open up the file which contains the key for your domain, it should be something like this:

key ubuntu-se.org. {
    algorithm hmac-md5;
    secret "blahfoobarblahbarfooblah";
};

• Where the text after secret is the secret key for the domain name.

• Use nsset to do the required change; the basic syntax of this command is:

$ ./nsset -s macquarie.canonical.com -k secret -K main-domain-name -z main-domain-name [operation] [domain-to-change]

• Where:

  • -s is followed by the update-host for the domain. (macquarie.canonical.com)

  • -k is followed by the secret key of the domain.

  • -K is the domain that the key belongs to. The trailing dot may be necessary but doesn't hurt.

  • -z is the DNS zone the domain belongs to (usually the same as the domain, can be left out).

  • -D is needed on newer Ubuntu systems, because of an obscure bug in the Perl DNS libraries. You'll get a bunch of debug info which you may ignore.

  • [operation] may be one of:

    • -a - add a new DNS entry for a subdomain.

    • -u - update a DNS entry for a subdomain.

    • -d - delete a DNS entry for a subdomain.

  • And finally [domain-to-change] is the subdomain to apply the change to.

For example:

$ ./nsset -s macquarie.canonical.com -k blahfoobarblahbarfooblah -K ubuntu-se.org. -z ubuntu-se.org -u www.ubuntu-se.org

• By running this command, we are updating the DNS entry for www.ubuntu-se.org.

• Specify which IP to point the domain at; say we want to point www.ubuntu-se.org at 74.125.45.100 - this is done by typing:

A 74.125.45.100

• Additional records (such as MX ones) can be added by pressing enter and adding them on new lines.

  When you're finish with the changes you've made, press Ctrl-D. If all the changes were correct NOERROR will be displayed by the script, if not, an error will be be shown.

  If you have made a mistake with a number and wish to stop the change, just press Ctrl-C and rerun the script.

• Check that the change was applied to the DNS server. This can be done by running this command once more:

$ dig @ns1.canonical.com www.ubuntu-se.org

• And look for the changes you made in the Answer section. Do note that the change can take up to 48 hours to spread through all the DNS servers on the Internet. If you run multiple changes in a short time, the servers at canonical.com may also reply with old data for a while.

And that's all there is to it!

I need help with something

If you need any more help, please send an email to rt@ubuntu.com explaining what you are trying to do and the details of the problem you are having.

CategoryLoCoTeams