Activate a paid licence
din activate turns a paid licence key into the signed entitlement file that the field, the console and the plugin read. The free build needs none of this: with no entitlement file an install runs as the free tier.
The self-hosted plans from Starter to Small Business are on sale, monthly, from the pricing page, and each comes with a licence key, read from your account area after checkout. This page documents the command as it is in 1.0.42, this release. A free install never checks in. A paid install checks in with our licensing service (api.dinctrl.com) with its random install id: when you run din activate or --renew, and on its own at most once a day when the field or the console starts (or with din autostart on). Each signed check-in lasts 14 days.
Online
din activate <LICENSE_KEY>
din activate - # the key read from stdin, so it stays out of your shell history
din activate # re-activate with the key already saved in license.key
This needs curl. din activate checks the key in with the issuer (by default https://api.dinctrl.com, changed with --url <BASE> or DIN_BILLING_URL) and receives a signed entitlement in reply. The key is handed to curl on stdin, never on its command line, so it does not show in a process listing.
Or paste your key in Plan
No terminal needed. In the local console (din console), open Plan and billing, paste your key into Activate a key and press Activate. The console runs the installed din activate - on this machine with your key on its standard input, so the key is never on a command line and never in the console's log, and it shows what came back: your tier, what it turns on and when the current period ends, or the error din gave. The plan on that screen updates straight away, without a restart.
The box is on the local console only, and it is new in 1.0.32: on an earlier release use din activate - in a terminal. The public demo and a hosted console do not have it. Every other setting the console can change is described in Console settings.
Offline
din activate --file <PATH>
No network and no curl. The file is either the saved reply of a check-in (the JSON that POST /api/license/verify answered) or a bare signed envelope. On a machine that does have a network, the check-in din activate makes is:
printf '{"key":"%s","install_id":"%s"}' '<LICENSE_KEY>' '<INSTALL_ID>' | curl -sS -X POST -H 'content-type: application/json' --data-binary @- https://api.dinctrl.com/api/license/verify > reply.json
<INSTALL_ID> is the offline box's own id, from its ~/.din/install-id (see Your install id below). din activate --file creates it if it is missing, and when a file is refused it prints this command with the id filled in. A reply fetched for another install's id, or for none, still verifies, but one made for another install reads as the free tier here.
Carry reply.json to the offline box and pass it to --file. Where the bytes travelled does not matter: the signature is what is checked.
Nothing is written unless it verifies
Whatever arrives, from the network or from a file, is verified on your machine first, against the public key built into the program. It must verify, be in term, and say it is valid and entitled. Anything else is refused and nothing is written, so a bad activation never replaces a good file.
Before anything is sent, din activate checks that what you gave it has the shape of a DIN licence key. A typo or the wrong paste is refused on your machine ("this is not a DIN licence key (check for a typo)"), and nothing is sent or written.
What it writes
<prefix>/.din/entitlement.json(by default~/din/.din/entitlement.json), whichdin licensereads and whichdin field startanddin consolehand to the programs they start.- The same bytes to
~/.din/entitlement.json(or$DIN_HOME/entitlement.json), the default a field or console started any other way, and the plugin, read. - If
DIN_ENTITLEMENT(orDASH_ENTITLEMENT) names a file, that one file only. - After an online activation with a new key, the key is saved to
<prefix>/.din/license.key, so a laterdin activateon its own re-activates.
Each file is written mode 600, through a temporary file and a rename, so a reader never sees half a file.
Your install id
The first time din activate checks in, it creates a random install id for this install: 32 hexadecimal characters (128 random bits) in ~/.din/install-id (or $DIN_HOME/install-id), mode 600. It is made once and kept. Every check-in sends it with your key, and the licensing service signs it into the entitlement it answers with.
The install id is a random number. It is not derived from your machine, your user name, your network or anything else about you, and it names no person and no machine. The licensing service keeps the ids your licence has checked in from, to see how many installs use the licence. There is no install limit, and a check-in from a new install is never refused because of it.
The entitlement is tied to the install that fetched it. If you copy entitlement.json to another machine or user, it reads as the free tier there, and din license says "this licence was activated on another install; run din activate here". Run din activate on that install (with the key, or the saved license.key) and it gets its own.
When it takes effect
The field re-reads the entitlement on its rescan tick (every 5 seconds by default), so the paid features switch on within seconds without a restart. A din console that is already running picks it up too: reload the page. It then shows your plan, what it includes, your agents and when the plan renews. din license shows the tier, and who decided it, at any time, and din status shows your plan, when it renews and your agents.
Renewing
The signed entitlement on your install runs 14 days from the check-in that fetched it, whatever your plan's period, and each check-in fetches a fresh 14 days. It never runs past your key's own term. Each period's key runs a few days past its billing date, so a renewal that lands a day late does not drop you to free. Your subscription gets a new key each period. While it is live and paid, the licensing service answers the key you saved with the current period's entitlement and the current key; din activate checks that key on your machine and saves it in place of the old one, so the next renewal presents a key from this period.
din activate --renew # check the saved key in again; prints nothing when it works
--renew uses the saved key only (give it no key and no --file). When it cannot renew it prints one line saying why, writes nothing, and the entitlement you have stays in place.
To have it done for you, run din autostart on (per user, no admin). On a paid install the login entry also runs din activate --renew: with systemd, two minutes after login and then daily (a timer, din-renew.timer); with a plain XDG autostart entry, at each login. If autostart was already on before you activated, din activate adds the renewal to it and says so. din autostart off removes it all.
Without autostart, a paid install checks in when you start it: din field start and din console run the same check-in as --renew, quietly, once its last check-in is a day old (and again when the entitlement has run out). Without autostart there is no timer: nothing checks in until you start DIN or run din activate. After 7 days without a successful check-in, din license, din status, /din status and the console's banner warn: "renews automatically with din autostart on; offline for N days". After 14 days the install reads as the free tier, saying "the licence has not been renewed for 14 days; run din activate --renew (or din autostart on)". Run din activate --renew, or din activate with the new key from your account page, or --file with a saved reply, offline. If the entitlement has expired, activation says so ("renew, then activate again").
A hand-edited entitlement, another key's signature, or a lapsed term is read as the free tier. Nothing in your records is deleted on a lapse.
If a payment fails
A failed renewal payment does not switch anything off straight away. Your paid features keep working for 7 days from the first failed payment while the card is retried, and din license warns with the date:
WARNING Payment failed. Paid features continue until <date>; update your card at <account page>
The payment-failed email names the same date. Update your card or pay the open invoice at any point in those 7 days and nothing changes. If it is still unpaid after the 7 days, the next din activate --renew installs the licensing service's signed answer that the plan has ended: the install moves to the free tier, the paid entitlement file is kept beside it as entitlement.json.revoked-<time>, and din license says Ended: payment failed and the grace period ended (on <date>). Paying the invoice later restores the paid plan at the next din activate --renew.
A cancellation still runs to the end of the period you paid for, and a full refund of the first payment ends the licence at once. Only a signed answer from the licensing service ends anything: no network, or an answer that is not signed, changes nothing.