Panel guide

The panel is where you run your hostnames: claim them, hand out their tokens, check their history, switch the extras on and off. Sign in at legitdns.com and open the panel.

The hostname list

Every hostname you own, with the addresses it currently publishes (or its last-known addresses when nothing is published), and a quota meter: hostnames used out of hostnames allowed. Free accounts currently start with 3; referral bonuses and tier changes raise the number. The meter reads the same ledger the service enforces, so what it shows is what you have.

Claiming a hostname

"New hostname" asks for two things: a domain (picked from the list we offer) and a label in front of it. The form calls the part you type the label; label plus domain makes the full hostname, like mypi.pihome.example. Some labels are reserved and cannot be claimed; the form says so in plain words, as it does when a hostname is taken or your quota is full.

On the next screen you get the hostname's update token, shown exactly once. Save it before you leave the page - see Tokens.

The hostname page

Each hostname has its own page:

Records - the A and AAAA values in DNS now, and the last-known values when not publishing.
Manual update - set addresses by hand. You are signed in as the owner, so no token is needed; the token field is there if you want to update exactly as a device would. Either way the update goes through the same path as a device update and lands in history the same way. A blank field leaves that address family unchanged, and leaving both blank publishes the address you are connecting from.
Token - regenerate (the old token dies at once) or revoke, plus the optional token rules: maximum age and allowed sources.
TTL - how long resolvers may cache the records. Default 300 seconds (5 minutes); settable per hostname between your tier's minimum (300 on the free tier) and 86,400 seconds (one day). Lower values show changes sooner and cost more queries.
Notify on IP change - an email when an update actually changes the address. Off by default; no email for updates that change nothing.
SRV records - extra records that point programs at a service on a specific port - a game server, for example. See "SRV records" below.
Certificates - publish the one TXT record a certificate check asks for. See "Certificates" below.
Delete - removes the hostname and its records and frees the quota slot. The token dies with it.

Offline

On tiers that include it, a hostname can be switched offline: records withdrawn, the hostname stops resolving, but hostname, token, and history stay in place. Updates sent while offline are authenticated and recorded, addresses kept as last-known; switch back online and those are republished. For a machine that is away or retired for a while, when you want the hostname dark but kept.

Wildcard

On tiers that include it, a hostname can answer for every name under itself: with the wildcard on, anything.mypi.pihome.example resolves to the same addresses as mypi.pihome.example and follows every update. (A specific name claimed under the hostname later answers for itself.) The wildcard has no token of its own - the hostname's token moves both. Switching it off removes only the wildcard answers.

Redirect

On tiers that include it, a hostname can be put in redirect mode instead of address mode: visits to http://mypi.pihome.example go to a target you choose, via a 302 redirect. A path after the hostname is carried onto the target, and so is the query string. While redirecting, device updates are held as last-known; switching back to address mode republishes them.

Two limits:

Plain HTTP only. An https:// link to your hostname would need a certificate for that name, and the service does not provide one.
Targets must be full http:// or https:// addresses, and never another legitdns hostname that is itself redirecting - the form refuses loops.

SRV records

An SRV record tells a program which host and port a service lives on, so the program can find it from the plain hostname. The classic example is a game server: run Minecraft on mypi.pihome.example on the usual port 25565, add an SRV record with service minecraft, protocol tcp, port 25565 and target mypi.pihome.example (the hostname itself), and players connect to mypi.pihome.example - the game looks up _minecraft._tcp.mypi.pihome.example and learns the port itself.

Each record has a service name (one word, like minecraft), a protocol (tcp or udp), a priority (when several records share a service, the lowest priority is tried first), a weight (how equal-priority records share the load), a port, and a target - the hostname the service actually runs on, which is very often the hostname itself. A hostname can currently hold up to 10 SRV records, and any of them can be removed from the same section of the hostname page.

SRV records are set in the panel only: device, router and token updates never change them. When a hostname is offline, its SRV records are out of the DNS together with its address records, and they come back when the hostname comes back.

Certificates

A certificate for your hostname (from Let's Encrypt, for example) proves you control the name. One way these checks work is DNS: the certificate tool shows you a value, and you publish it as a DNS TXT record at _acme-challenge. in front of your hostname - for mypi.pihome.example, the record name is _acme-challenge.mypi.pihome.example. legitdns publishes exactly that one record for you, and nothing else: it is the only TXT record the service sets.

Two ways to set it, on the hostname page or through the API:

In the panel: the Certificates section of the hostname page takes the value. It goes live at once, stays up for about an hour, and is then removed on its own - there is nothing to clean up. The section shows the value, when it was set, and how much time is left, and you can clear it early or replace it at any time.
From a script: the API takes the value with the hostname's update token - see the Update API page. Certificate tools that run a small script of yours at check time (certbot's manual hooks, acme.sh's manual mode) can call the API from that script, which is what makes renewals automatic.

Honest limits:

There is no legitdns plugin for certbot or acme.sh. The paste-in-the-panel way needs no plugin, and the API way needs only the small hook script on the Update API page.
One challenge per hostname at a time: setting a new value replaces the old one.
The hostname must be online. While a hostname is offline, its records - the challenge included - are out of the DNS, so a check cannot pass.
The value is a public record while it is up. Anyone can read it; that is how the check works, and it is not a secret.

History

Your updates across all your hostnames: time, channel, source address, what was set, whether it worked, and the reason when it did not. The channel is dyndns2 for routers and DynDNS2 clients, api for scripts and API calls, panel for manual updates, and prefix for the updates a hostname receives when its IPv6 prefix changes. Filter by hostname; 25 rows per page. When an update seems lost, this page is where the answer is.

If a hostname goes quiet

If a hostname that has been updating regularly stops updating for about a week, we send one email to the account address saying so, with the last time it checked in. It often means the device lost power, its router was replaced, or its updater stopped. Updates we hold - for example during maintenance - still count as the device checking in, so a quiet week on our side never triggers this email. When the hostname updates again the watch resets; if it goes quiet for another week later, we email again.

Settings: two-factor and referrals

The settings page holds account-level tools:

Two-factor authentication. TOTP with any standard authenticator app. Setup ends with 8 recovery codes - shown once, save them; each works exactly once if you lose the app. Signing in then takes password plus code. A password reset does not remove two-factor; the recovery codes are the way back in. Turning it off asks for a current code.
Referrals. Your invite link and code, with counts of friends invited and bonuses earned. When a friend signs up with it, verifies their email, and has a first hostname actually updating, you both get +1 hostname of quota. Your inviting bonus is capped at +10 in total; invited friends always get their +1 in full.