<<Include(LoCoMenuHeader)>>

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 [[https://secure.wikimedia.org/wikipedia/en/wiki/TSIG|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 '''[[GnuPrivacyGuardHowto|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 [[attachment:nsset]] script and the Perl bindings for DNS installed (package: `libnet-dns-perl`).

Note that `nsset` may fail on newer releases of Ubuntu (such as Ubuntu 23.10) with an error such as `Usage:  Net::DNS::RR::TSIG->create( $keyfile, @options ) at /usr/share/perl5/Net/DNS/Packet.pm line 631.`. Use an Ubuntu 22.04 LTS machine, or a container, to perform the update as a workaround.

== Announcements ==

=== 2022-06-15 ===

`loco-dns.ubuntu.com` has migrated to a server that no longer accepts updates via UDP.

In order to keep using `nsset` for updates, please download the updated version as currently attached to this page. Link to attachment: [[attachment:nsset]]; link to diff: [[https://pastebin.ubuntu.com/p/w5nmRNn5y6/|nsset.patch]] (may not apply cleanly to your local copy).

If you use `nsupdate`, use the `-v` option to enable TCP unconditionally.

If you use another tool to perform DNS updates, please consult its documentation for information on switching to TCP.

== 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 [[attachment:nsset]] to do the required change; the basic syntax of this command is:

{{{

$ ./nsset -s loco-dns.ubuntu.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. (loco-dns.ubuntu.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 [[http://en.wikipedia.org/wiki/DNS_zone|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''' - ''a''dd a new DNS entry for a subdomain.
   * '''-u''' - ''u''pdate a DNS entry for a subdomain.
   * '''-d''' - ''d''elete a DNS entry for a subdomain.
  * And finally '''[domain-to-change]''' is the subdomain to apply the change to.

For example:

{{{

$ ./nsset -s loco-dns.ubuntu.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