Running an Enclave on a server¶
The quickstart tells you to run ekka enclave start in a terminal and leave
it there. That is right for your laptop while you are learning. It is wrong
for a server.
On a server you want the Enclave to come back after a crash, start again after a reboot, write its logs somewhere you can read them later, and answer one question clearly: is it running? A process you left in a terminal does none of that.
Five steps, about five minutes.
Use a service manager, not a background shell
nohup, &, screen and tmux all look like they solve this. Each one
survives your ssh session and nothing else. A reboot, an out-of-memory kill,
or a crash at 3am ends the Enclave silently, and the only sign is that your
plans stop running.
Use your operating system's service manager instead. On Linux that is
systemd, and ekka enclave install-service sets it up in one command.
To watch it run for five minutes before committing to a service,
tmux new -d -s ekka 'ekka enclave start' is fine. Do not leave a server
that way: run tmux kill-session -t ekka when you are done, then come back
and do step 4.
What you need¶
- A Linux server you can
sudoon. - The Enclave id. Run
ekka enclave listfrom your own machine, or ask whoever runs your organization. It looks like2055d4a5-4e55-4292-9f8e-64166f14871d. - About five minutes.
1 · Install the binary¶
curl -fsSL https://get.ekka.ai/install.sh | sh
sudo install -o root -g root -m 0755 "$(command -v ekka)" /usr/local/bin/ekka
ekka --version
2 · Make a user for it¶
The Enclave does not need to be root, so do not run it as root. Give it its own user and its own folder.
sudo useradd --system --no-create-home --shell /usr/sbin/nologin ekka
sudo install -d -o ekka -g ekka -m 0700 /var/lib/ekka
/var/lib/ekka is this Enclave's home. Its vault, its receipts and its
config all live there.
Do not put it under /home or /root
The service file we ship hides those folders from the Enclave on purpose,
as one of its safety settings. Pick a path outside them. /var/lib/ekka
is the one we recommend and the one the unit file already names.
3 · Sign in and claim the machine, once¶
sudo -u ekka EKKA_HOME=/var/lib/ekka ekka login --email [email protected]
sudo -u ekka EKKA_HOME=/var/lib/ekka ekka enclave start <enclave-id>
Wait for this line:
Then press Ctrl-C to stop it.
That felt like an ordinary start, but it did the important part: it claimed
this machine for that Enclave, created the vault, and wrote a complete
config file at /var/lib/ekka/enclave.env. You only ever do this once. From
here on, ekka enclave start needs no id and no arguments.
No keychain questions on a server
On a Mac the Enclave keeps its vault key in the OS keychain, which asks
you to approve access. A Linux server has no keychain, so the key is
sealed into a protected file next to the vault instead. Nothing pops up
and there is nothing to approve. You do not need to pass --custody.
4 · Hand it to systemd¶
That writes /etc/systemd/system/ekka.service, then enables and starts it. The
unit is generated from this machine: the Enclave home you enrolled in step
3, the account that owns it, and the path of the binary you installed in step 1.
Nothing to substitute.
The service runs the Enclave as the account that owns the Enclave home, with no extra privileges, restricted to that directory, and restarts it if it stops.
sudo ekka enclave install-service --dry-run # print the unit, write nothing
sudo ekka enclave install-service --no-start # write the unit, start it later
If your Enclave lives under a home directory
systemd's ProtectHome=true makes /home and /root invisible to a
service, so a unit with it turned on starts and then finds no enrolled
machine at all.
install-service notices, turns it off for you, tells you on screen, and
writes the reason into the unit. Moving the Enclave to /var/lib/ekka (step
2) is the stronger posture; re-run the command afterwards and it goes back
on.
5 · Check it two ways¶
One command asks the operating system whether the process is up. The other asks the Enclave whether it is actually working.
Then, from anywhere signed in to your organization:
Your server should show as online. That is the answer that counts, because it is govern saying it can reach the machine and give it work.
BUILD is which version that machine is running. ekka enclave status only
ever answers about the machine you are typing on, so for a server this row is
where you read it. A dash means the Enclave has not reported one, which means it
has never connected. On a machine that is offline, the build shown is the last
one govern saw, which tells you what it was running when it stopped.
Reading the logs¶
systemd captures everything the Enclave prints, so you never need to have been watching.
sudo journalctl -u ekka -f # follow, like tail -f
sudo journalctl -u ekka -S -1h # the last hour
sudo journalctl -u ekka -n 50 # the last 50 lines
Day to day¶
| What you want | Command |
|---|---|
| Restart it, after upgrading the binary | sudo systemctl restart ekka |
| Stop it, keeping the enrolment | sudo systemctl stop ekka |
| Stop it and keep it off after a reboot | sudo systemctl disable --now ekka |
| Stop giving it work, but leave it running | ekka enclave pause <id> |
| Give it work again | ekka enclave resume <id> |
The last two are worth understanding, because they answer different
questions. Use systemctl stop when you are working on the machine.
Use ekka enclave pause when you are working on the workload and want
the process left alone.
Upgrading¶
curl -fsSL https://get.ekka.ai/install.sh | sh
sudo install -o root -g root -m 0755 ~/.local/bin/ekka /usr/local/bin/ekka
sudo systemctl restart ekka
Your enrolment, vault and receipts are all in /var/lib/ekka and are not
touched by replacing the binary.
Name ~/.local/bin/ekka as the source, which is where the installer writes. On
a machine that already has /usr/local/bin/ekka on its PATH, $(command -v
ekka) resolves to the destination, so the copy is a no-op and you stay on the
old binary.
The restart is not optional. The running process keeps serving the binary it
started with, so until you restart it, ekka enclave list reports the old build
for this machine.
When it will not start¶
The Enclave never fails quietly. Every refusal starts with FATAL: and
names what is wrong, and systemd kept all of it:
One command answers most of them, by printing every setting the Enclave is actually using and where each value came from:
Two common ones:
FATAL: this Enclave has no vault. Step 3 did not finish. Run theekka enclave start <enclave-id>line again and wait forauthenticated; entering run loopbefore stopping it.- The unit starts, then stops, then starts again. Read the journal. The service is set to keep retrying, so a config problem shows up as a loop rather than a single failure.
Containers and immutable images¶
If the machine's disk is not yours to write to, skip step 3. Supply every
setting from outside instead, through environment variables. The release
tarball ships a template at share/templates/ekka.env.template listing
every required key, and share/docs/INSTALL.md covers that path in full.
You still need an Enclave that was enrolled somewhere: the Enclave signs with a private key that lives in its vault, and there is no environment variable for a private key.