Secrets
zekno secret set, import, rm and ls, with values sealed and signed on your machine, and what the server keeps of them.
Pre-alpha and unaudited
The command-line tool, the runner and the core library have had internal reviews only. Do not use them for anything you could not afford to lose, and do not rely on them in production before an external audit.
zekno secret set, import, rm and ls
zekno secret set seals a value for one app on one server and signs it. It
takes effect on the next deploy. Before the value is asked for, zekno names
where it goes: Value for NAME (api on dev): .
- A secret value is never an argument. Leave it out and you are asked for it
with nothing shown as you type, or pipe it in with
--stdin. A value of several lines needs--stdin. With--stdin, one line break at the end is dropped. - An empty value is not stored. A value may be at most 64 KiB.
- A name uses letters, digits and underscore, and does not start with a digit. Names the runner uses to start Docker are reserved and refused.
zekno secret rm signs the removal of a secret; it also takes effect on the
next deploy. zekno secret ls lists names and versions. No command shows a
value.
zekno secret ls in shop's folder: the names of shop's secrets on prod-1, DATABASE_URL and SESSION_KEY, each with its version, and never a value.
zekno secret set DATABASE_URL --app api --server prod --stdin < database-url.txtzekno secret import <file> brings in a project's values from a file of
NAME=value lines, such as a .env file, all at once. It shows the names it
found, never a value, asks once, and stores each value sealed and signed, as
zekno secret set does one at a time:
$ zekno secret import .env
.env, for demo on prod
new DATABASE_URL, SESSION_KEY, STRIPE_KEY
replaces API_URL
left out PATH (zekno keeps this name), line 7 (not a valid name)
? Store 4 values? Values are never shown. (y/N)
✔ Stored 4 values for demo on prod. They take effect on the next deploy.
.env still holds them in plain text. Delete it, or keep it out of git.- What is read. One
NAME=valueper line. Blank lines and lines that start with#are skipped.exportin front of a name is allowed. A value may be in single quotes, taken exactly as written, or in double quotes, where\n,\r,\t,\\,\"and\$are the only escapes. A#after a space or a tab starts a comment. - What stops the import. A
$outside single quotes, a#inside a value without quotes, and a value without quotes that begins with=: put such a value in single quotes to keep it as it is. A value never spans lines: write a line break as\ninside double quotes. A name given twice stops it too. Any line that does not fit stops the whole import and nothing is stored: the message names the file and the line's number, and never repeats the line. - Names. A name that already has a secret gets a new version
("replaces"). A name that does not fit the rule of
zekno secret set, a reserved name, and an empty value are left out, and the rest is still offered. A reserved name is shown as written; any other name left out is shown by its line's number only (line 7above), since it may be the end of a value wrapped onto its own line. A value may be at most 64 KiB, and one import at most 256 values. - One question. Nothing is stored before the answer, and then every value
is stored at once, or none is.
--yesanswers the question in advance. With no terminal, the import stops unless you add--yes, and stores nothing.--appand--serverwork as for the other secret commands, and at a terminal are asked for when missing. - The file. It may be anywhere.
zeknoreads it once, at most 1 MiB, and never changes, copies or deletes it. It still holds the values in plain text afterwards: delete it, or keep it out of git. When the file you give is a link, or is in a folder that is one, the first line says where it leads:.env (a link to /home/ada/elsewhere/other.env), for demo on prod.
zekno secret import .env --app api --server prod --yesWhat the server keeps
With a runner that speaks protocol 3 (see An older or a newer runner), the server keeps each secret's latest record, sealed for its key as it was sent, and deletes the one it replaces. A deploy then sends a record only when the server lacks it: a secret set, or set again, since the last deploy. With nothing changed, a deploy sends no sealed value, and the app still starts with every secret.
Every deploy in the new format accounts for every secret the server holds for
the app: each one is listed at its latest version, or as removed. A secret is
left out only by zekno secret rm, which signs its removal. A deploy that
leaves one out is refused, and nothing of it runs.
A secret the server holds and this machine does not, because it was set from
another machine or lost here, is listed from the server's record. This
machine checks who set it against your team list, and its value never passes
through this machine. The deploy's result line counts it with the others, and
the panel of the terminal app's deploy screen names it. zekno secret ls
still lists only this machine's secrets.
An app deployed only in the older format has no records on the server: that format sends every record with each deploy, and the server keeps none. Its first deploy in the new format sends each record from this machine. A machine that does not have them stops, as below.
Set and rm work offline
zekno secret set and zekno secret rm never connect to anything. Each takes
the next version of a name as one above the highest it knows of: this
machine's records and removals of the name, and what the last deploy in the
new format read of the server for that app, kept on this machine (see
What is kept where). What was read of the server only raises
the version. Like a record here that cannot be checked, it counts only when it
is at most 1,000 above the highest version of the name that checks out on this
machine; a higher one is ignored. It never gives a value, and never decides
what a deploy lists: that comes only from records checked when the deploy is
signed.
zekno secret rm <NAME> signs the removal when this machine holds a secret of
that name. It also does when this machine holds a record of it that it cannot
check, or when the server held the name at the last deploy in the new format,
at a version above the highest of the name that checks out here, and no more
than 1,000 above it. It then says
Removed <NAME> from <app> on <server>. It takes effect on the next deploy.
Otherwise it signs nothing and says
<app> on <server> has no secret named <NAME>.
When a deploy stops for a secret
Before it signs, a deploy checks every secret it would list. In three cases it
stops, names the secret and signs nothing, with exit status 1. In each, the
two commands the sentence names work offline, and then the next deploy goes
through: zekno secret set <NAME> signs a version above any the server
reported, within the bound above, and the deploy
sends its record; zekno secret rm <NAME> signs a removal above it, and the deploy lists
the removal.
Set by someone who is no longer in the team, on this machine or on the server. In either deploy format:
<NAME> was set by someone who is no longer in the team, so <app> cannot be deployed with it. Set it again with `zekno secret set <NAME>`, or remove it with `zekno secret rm <NAME>`. Nothing was signed.This replaces the warning Left out a record: unknown_signer., after which
the deploy went on without the secret. Teammates are not built yet, so with
zekno alone nobody leaves a team today. A runner that speaks protocol 3
checks the same at every deploy, on the records it keeps too, and refuses a
deploy that uses such a secret (untrusted_secret).
Held by the server, and this machine cannot check who set it. In the new format only. For example, a secret of an app deployed only in the older format, on a machine that does not have its record:
<server> holds <NAME> for <app>, and this machine cannot check who set it. Set it again with `zekno secret set <NAME>`, or remove it with `zekno secret rm <NAME>`. Nothing was signed.Newer on the server than on this machine. In the new format only. This machine's latest record of the secret is older than the one the server holds, which was set from another machine since. Without this stop, the deploy would run the server's value and leave the one set here out without a word:
<server> holds a newer <NAME> for <app> than the one set on this machine. Set it again with `zekno secret set <NAME>` to replace it, or remove it with `zekno secret rm <NAME>`. Nothing was signed.With several such secrets, each has its line, in name order, and
Nothing was signed. ends the last one only. zekno deploy and
zekno rollback at a terminal show the commands without their backticks.
Anything else that cannot be checked, and stops nothing, is left out with a
warning, as before.