Domains

Two kinds, not five

The alternative is the vocabulary people have been confusing for twenty years: addon domain, parked domain, subdomain, alias, redirect. KLYRN has two, and the rule that decides between them is a question the customer can answer.

alias

The same website, under another name. Same files, same database, same certificate.

redirect

Visitors are sent somewhere else, keeping the path and the query string.

A subdomain that should show a different website is simply its own site. shop.example.com with its own files and its own database is klyrn site create shop.example.com, with the same account as the parent if you want them to share a home. A subdomain that should show the same website is an alias.

Adding an alias

klyrn site domain list example.com
klyrn site domain add example.com shop.example.com
klyrn site domain add example.com example.net
klyrn site domain remove 7        # the id from 'domain list'

An alias joins the vhost's server_name and goes onto the Let's Encrypt certificate as soon as it resolves to this server. Until it resolves, the name is listed with its DNS state (ready, missing, elsewhere or unknown) and the certificate is ordered for the names that do resolve rather than failing for all of them.

A lookup that fails is reported as its own state and retried once after 300 ms, because one SERVFAIL from a busy resolver is not information anybody can act on. It is never reported as "no record", which would tell a customer to create something they already have.

KLYRN refuses to add a name that is:

• The site's own domain.
• www.<domain> while www handling is set to alias: turn that off first.
• The panel's own hostname.
• Already a site on this server, or already pointing at another site. The message says which.

Unlike site creation, a leading www. on a domain row is kept. Someone who types www.example.net must not silently get example.net.

Redirects

klyrn site domain add example.com old.example.com --redirect-to https://example.com
klyrn site domain add example.com legacy.example.com --redirect-to https://example.com/new --code 302

A redirect gets its own nginx server block on both ports, and the name goes on the certificate. That last part is the one people forget: a visitor arriving at https://old.example.com would otherwise meet a certificate for a different name before the redirect could run.

The destination is validated because it is written into an nginx configuration file:

• Required, and no longer than 500 characters.
• Must begin https:// or http://.
• May not contain a newline, tab, quote, backslash, semicolon or brace.
• The code is 301 (permanent, the default) or 302 (temporary). Nothing else.

www handling

A site created without --no-www serves www.<domain> as an alias and puts it on the certificate if it resolves here. Change it later:

klyrn site set example.com --www alias
klyrn site set example.com --www none

If you would rather www redirected to the apex than served it, set --www none and add www.example.com as a redirect. That is a deliberate choice rather than a hidden default, and the certificate covers it either way.