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
|
|
{domain}.{tld} |
example.ch
example.net
|
|
www.{domain}.{tld} |
www.example.net
www.example.ch
|
|
{subdomain}.{domain}.{tld} |
admin.example.net
intranet.example.net
www.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:
Go to domain tocco.ch (password in secrets2.yml) (link only works when logged in to tocco account)
Remove any existing A, AAAA, ALIAS, ANAME and CNAME record for ${INSTALLATION_NAME}.tocco.ch.
Create record:
Root Domain (example.net)¶
For root domains, an ALIAS is to be used:
example.net 3600 IN ALIAS exampleinc.tocco.ch.
; ^^^^^^^^^^^^^^^^^^^
; ${INSTALLATION_NAME}.tocco.ch
Instructions:
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.
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.
Create record:
Note
What if type ALIAS is not available?
Type ALIAS is sometimes known as ANAME:
example.net 3600 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. 3600 IN A 5.102.151.37
example.net. 3600 IN AAAA 2a06:c01::54a7
Special Case www¶
www.some-domain.tld should point to the root domain:
www.example.net 3600 IN CNAME example.net.
^^^^^^^^^^^ ^^^^^^^^^^^
; root domain root domain
Instructions:
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.
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).
Create record:
Subdomain (some-name.example.net)¶
Subdomains, with the exception of www, should point to ${INSTALLATION}.tocco.ch:
intranet.example.net 3600 IN CNAME exampleinc.tocco.ch.
; ^^^^^^^^^^^^^^^^^^^
; ${INSTALLATION_NAME}.tocco.ch
Instructions:
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.
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).
Create record:
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
andns2.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::54a7The 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 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 domain level. 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.
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.37The 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.37where, 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.4Of 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.