This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

DNS (Nice)

Add DNS Records

Finding the Right Instructions

Hint

When adding domain for Nice, see also Add Route / Endpoint.

Pattern

Examples

Instructions
{installation_name}.tocco.ch
{service_name}.tocco.ch
(only subdomains of tocco.ch)
dgh.tocco.ch
dghtest.tocco.ch

${INSTALLATION_NAME}.tocco.ch

{domain}.{tld}
example.ch
example.net

Root Domain (example.net)

www.{domain}.{tld}
www.example.net
www.example.ch

Special Case www

{subdomain}.{domain}.{tld}
admin.example.net
intranet.example.net
www.example.net

Subdomain (some-name.example.net)

${INSTALLATION_NAME}.tocco.ch

Every installation has an record for ${INSTALLATION_NAME}.tocco.ch:

; 'exampleinc' is the installation's name
exampleinc.tocco.ch.      3600 IN CNAME  os4.tocco.ch.

Instructions:

  1. Go to domain tocco.ch (password in secrets2.yml) (link only works when logged in to tocco account)

  2. Remove any existing A, AAAA, ALIAS, ANAME and CNAME record for ${INSTALLATION_NAME}.tocco.ch.

  3. Create record:

    ../../_images/installation.tocco.ch.png

  4. Verify DNS Records

Root Domain (example.net)

For root domains, an ALIAS is to be used:

example.net           IN ALIAS   exampleinc.tocco.ch.
                           ;     ^^^^^^^^^^^^^^^^^^^
                           ; ${INSTALLATION_NAME}.tocco.ch

Instructions:

  1. Find out if Domain is Managed by Us

  2. For domains managed by us, execute the following instructions in Nine’s Cockpit. Password in secrets2.yml.

    For domains managed by the customer, or another third party, forward the following instructions for removing/adding DNS records to the customer.

  3. Remove any existing A, AAAA, ANAME and ALIAS record for the domain. Do not touch subdomains such as, www.example.net or some-name.example.net.

  4. Create record:

    ../../_images/root_domain.png

    Example user interface. Other interfaces may look significantly different.

  5. Verify DNS Records

Note

What if type ALIAS is not available?

Type ALIAS is sometimes known as ANAME:

example.net    IN ANAME   exampleinc.tocco.ch.
;                         ^^^^^^^^^^^^^^^^^^^
;                     ${INSTALLATION_NAME}.tocco.ch

Iff ALIAS and ANAME aren’t available, create both of the following records instead:

example.net.     IN A      5.102.151.37
example.net.     IN AAAA   2a06:c01::54a7

; HTTPS is not supported by all DNS providers. Skip it
; if there is no HTTPS type.
example.net.     IN HTTPS  0  exampleinc.tocco.ch.
;                          ^           ^
;                          |           |
;                          |  target: {INSTALLATION_NAME}.tocco.ch
;                          |
;                        priority: always 0

Special Case www

www.some-domain.tld should point to the root domain:

www.example.net       IN CNAME   example.net.
    ^^^^^^^^^^^                  ^^^^^^^^^^^
  ; root domain                  root domain

Instructions:

  1. Find out if Domain is Managed by Us

  2. For domains managed by us, execute the following instructions in Nine’s Cockpit. Password in secrets2.yml.

    For domains managed by the customer, or another third party, forward the following instructions for removing/adding DNS records to the customer.

  3. Remove any existing A, AAAA, ANAME, ALIAS or CNAME record for the www subdomain. Do not touch the domain (e.g example.net) or any other subdomains (e.g. some-domain.example.net).

  4. Create record:

    ../../_images/www_subdomain.png

    Example user interface. Other interfaces may look significantly different.

  5. Verify DNS Records

Subdomain (some-name.example.net)

Subdomains, with the exception of www, should point to ${INSTALLATION}.tocco.ch:

intranet.example.net  IN CNAME   exampleinc.tocco.ch.
                           ;     ^^^^^^^^^^^^^^^^^^^
                           ; ${INSTALLATION_NAME}.tocco.ch

Instructions:

  1. Find out if Domain is Managed by Us

  2. For domains managed by us, execute the following instructions in Nine’s Cockpit.Password in secrets2.yml.

    For domains managed by the customer, or another third party, forward the following instructions for removing/adding DNS records to the customer.

  3. Remove any existing A, AAAA, ANAME, ALIAS or CNAME record for the subdomain. Do not touch the domain (e.g example.net) or any other subdomains (e.g. another-subdomain.example.net).

  4. Create record:

    ../../_images/some_subdomain.png

    Example user interface. Other interfaces may look significantly different.

  5. Verify DNS Records

Find out if Domain is Managed by Us

Obtain a list of DNS server for the domain via terminal:

dig -t ns ${DOMAIN}}

Or do an NS lookup online.

If the result contains the name servers ns1.tocco.ch and ns2.tocco.ch, the domain is managed by us. Otherwise, it is not.

Hint

${DOMAIN} is the domain part only, e.g. tocco.ch and not www.tocco.ch or cockpit.tocco.ch.

Verify DNS Records

Get A records for FQDN via terminal:

dig ${FQDN}

Or do an A lookup online.

Hint

${FQDN} is the full domain name, like tocco.ch, www.tocco.ch or admin.tocco.ch.

Verify output:

The ANSWER SECTION of the output must contain the following A entries:

... IN A 5.102.151.37

The output may also contain CNAME entries. However, it must not contain any other A entries. If it does, they must be removed.

Get AAAA records for FQDN via terminal:

dig -t aaaa ${FQDN}

Or do a AAAA lookup online.

Verify output:

The ANSWER SECTION of the output must contain the following AAAA entries:

... IN AAAA 2a06:c01::54a7

The output may also contain CNAME entries. However, it must not contain any other AAAA entries. If it does, they must be removed.

Technical Notes

Why use CNAME Pointing to ${INSTALLATION_NAME}.tocco.ch for Other Subdomains?

Having all records point to ${INSTALLATION_NAME}.tocco.ch means that we only need to change this single record to have all records changed for a single installation.

Example:

extranet.example.net. IN CNAME example.tocco.ch.
example.tocco.ch.     IN CNAME os4.tocco.ch.
example.tocco.ch.     IN A 5.102.151.37

In this example, only example.tocco.ch. needs to be adjusted when moving the installation to another platform.

Additionally, many domains are managed by third parties. Having A/AAAA records would mean communicating all changes to the customer rather than being able to change them at our discretion.

Why use CNAME Pointing to Root Domain for www and it Only?

The term:`root domain, e.g. example.net, and the www subdomain, e.g. www.example.net, are inherently linked and the two are always expected to point to the same page in today’s internet. Hence, having the two “glued” together via CNAME is but logical.

When it comes to other subdomains the situation looks different. Let’s consider the following subdomain:

; this is an example of how not to do it
intranet.example.net.  IN CNAME  example.net.

For these two domains, intranet.example.net and example.net, it’s very much a possibility that only the root domain, example.net, is moved without the intranet.example.net subdomain. However, because of the CNAME, intranet.example.net would be moved inadvertently too. There is no way for us to find out whether a root domain is used as CNAME target for domains in the hand of third parties.

Why use ALIAS/ANAME for Domains?

The reasoning is the same as for subdomains. The reason CNAME isn’t used here is that the DNS protocol doesn’t allow it on root domains. See Why use CNAME Pointing to ${INSTALLATION_NAME}.tocco.ch for Other Subdomains?

ALIAS remains completely unspecified but an attempt has been made to standardize ANAME. However, this draft has expired and current implementations very greatly.

Why use HTTPS?

  1. This tells clients to upgrade to https:// rather than potentially use http:// on first connect. Thereafter, Strict Transport Security will be in force.

  2. Allows redirects on root domains giving us more control over the domain. CNAME isn’t allowed on root domain.

    We could redirect most traffic if needed.

  3. We’ll be able to add our own HTTPS records on the target (${INSTALLATION_NAME}.tocco.ch) to inform about new protocols (e.g. HTTP/3) or other features like ECH.

Caveats

  1. Nine does not support HTTPS. So, we can’t set it on os4.tocco.ch yet.

  2. For backwards compatibility, AAAA and even A records will need to remain for the time being.

    Browser understand HTTPS but not all other tools have support yet. Curl support, for example, is still experimental.

  3. HTTPS records don’t redirect CAA records which means if we want to introduce CAA for customers domains, we’d need customers to add it.

How to detect the use of ALIAS/ANAME?

Due to the lack of specification, there is no definite way to determine whether a server is using A/AAAA records or ALIAS/ANAME. Yet, this may be necessary to determine whether a DNS record needs to be changed.

One method is trying to see if the TTL on authoritative server decreases over time:

First, find an authoritative server:

$ dig -t ns +short tocco.ch
ns1.tocco.ch.
ns2.tocco.ch.

Resolve A record twice with some delay:

$ for _ in a b; do
    dig +noall +answer +norecurse @ns1.tocco.ch tocco.ch;
    echo
    sleep 2
  done
tocco.ch.           4140  IN  A     5.102.151.37

tocco.ch.           4138  IN  A     5.102.151.37

The decreasing TTL is a strong indication that ALIAS/ANAME is in effect.

Another possibility is to adjust the suspected target of an ALIAS/ANAME:

Let’s assume the following records existed:

example.net.        3600  IN  ANAME  os4.tocco.ch.
os4.tocco.ch.       3600  IN  A      5.102.151.37

where, of course, we’d only see:

os4.tocco.ch.  3600  IN  A           5.102.151.37

In order to find out if there indeed is an ALIAS/ANAME in place, the record for os4.tocco.ch could be altered:

We could remove one of the records (though be it rather dangerous):

os4.tocco.ch.  3600  IN  A           5.102.151.37

Or temporarily add one:

os4.tocco.ch.  3600  IN  A           5.102.151.37
os4.tocco.ch.  3600  IN  A           1.2.3.4

Of course, we’d have to make sure 1.2.3.4 returns a response clients handle well.

Keep in mind possible caching as result TTLs.