Skip to Content

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.

An app's secretszekno secret ls

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 ls in shop's folder: shop's two secrets on prod-1, each with its version, and no value.
zekno secret set DATABASE_URL --app api --server prod --stdin < database-url.txt

zekno 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=value per line. Blank lines and lines that start with # are skipped. export in 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 \n inside 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 7 above), 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. --yes answers the question in advance. With no terminal, the import stops unless you add --yes, and stores nothing. --app and --server work as for the other secret commands, and at a terminal are asked for when missing.
  • The file. It may be anywhere. zekno reads 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 --yes

What the server keeps

With a runner that speaks protocol 3 or 4 (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 or 4 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.