Remote admin#

The remote admin channel lets an admin on another computer change a team node’s keys, teams and limits, over TLS with pinned keys and a signed grant for every change. This page is for node administrators and the admins they enroll.

How it works#

A team node serves its meter and admin API on -admin-listen. The default, 127.0.0.1:8790, is reachable from the node’s own machine only. You can still reach it from elsewhere with an SSH tunnel:

ssh -L 18790:127.0.0.1:8790 node

If you set -admin-listen to an address other machines can reach, such as 10.0.0.5:8790, the node serves it only over the remote admin channel. If the channel is not set up, Lockpin refuses to start and says what to run. An address that listens on every interface (:8790, 0.0.0.0:8790, [::]:8790) is refused in team mode.

The channel needs the node’s sealed store (-capabilities FILE). lockpin node install always sets it. See Run a team node.

What protects it#

TLS 1.3, hybrid key exchange only. The node accepts X25519MLKEM768 and SecP384r1MLKEM1024. A client that offers only a classical key exchange, or an older TLS version, is refused.
Mutual TLS with pinned keys, and no certificate authority. Each side holds an ML-DSA-65 key. The node knows each admin’s key fingerprint from lockpin-admins.txt. Each admin pins the node’s fingerprint with -node-fp. A connection from a key not on the list is refused, and so is a node whose fingerprint differs from the pinned one.
A grant for every change. A grant is signed by the admin and names the node, the admin, the exact method, path and body, a nonce the node issued, a sequence number and an expiry.
- It works once. The node forgets the nonce when it uses it, and each sequence number must be higher than the admin’s last one.
- It lasts at most 5 minutes. lockpin admin call makes 2-minute grants. The node allows 60 seconds of clock difference.
- It carries two signatures, ML-DSA-65 and Ed25519. Both must verify.
Public keys only on the node. The node holds no admin’s private key. Each admin’s private keys stay in a sealed store on the admin’s own computer.

Reading (GET, HEAD) needs the TLS identity only, not a grant.

Before you begin#

A team node is installed. See Run a team node.
You can run commands as an administrator on the node.
Each admin has Lockpin installed on their own computer.
To enroll a team admin, the team exists in the node’s keys file.

Set it up#

On the node, as an administrator, make the node’s channel identity:
```
lockpin admin node-id
```
It stores the identity in the node’s sealed store and prints sha256:.... Give that fingerprint to each admin. Run the command again at any time to print it again.
On each admin’s own computer, make the admin’s keys:
```
lockpin admin keygen -name alice
```
It seals the private keys on that computer and prints one line of public keys, lockpin-admin-v1 alice .... Send the line to the node’s administrator. The name may hold letters, digits, ., _ and -. -sealed FILE picks another store than the default Lockpin/lockpin-admin.sealed in your config folder.

On the node, as an administrator, enroll the admin with one of:

lockpin admin enroll "LINE" -role owner
lockpin admin enroll "LINE" -role admin
lockpin admin enroll "LINE" -role admin -team backend

Both commands take -data DIR for a node folder other than this system’s default.

Check the setup, then restart the node with its private address:

lockpin doctor -capabilities FILE -keys FILE -admin-listen 10.0.0.5:8790
lockpin node install -args "-admin-listen 10.0.0.5:8790"

Use it#

From the admin’s computer, send one request at a time:

lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX GET /lockpin/api/teams
lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX POST /lockpin/api/teams '{"name":"ops"}'
echo '{"name":"ops"}' | lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX POST /lockpin/api/teams -

call fetches a nonce and the next sequence number from the node, signs a grant for this one request, sends it and prints the answer. A body of - is read from stdin. The command exits with an error if the node answers anything other than 2xx.

Who may do what#

Role	What it may do
`owner`	Everything, including making admins and handing over ownership.
`admin`, no team	Everything except making admins and handing over ownership.
`admin -team TEAM`	That team’s keys, invites, limits and allowance. A change outside the team is refused.

Over the channel the node refuses any change outside /lockpin/api/keys, /lockpin/api/teams, /lockpin/api/invites and /lockpin/api/workspace and the paths below them. Kept prompts (/lockpin/api/prompts) are every team’s, so over the channel only an owner or an admin with no team can read them.

The same rules apply to the admin page on the node’s own machine. There the page asks for an owner or admin lp_ key once per tab session and keeps it in that tab’s session storage only. An expired lp_ key is refused there with the command that renews it, and a service key is always refused. The channel’s own admin keys are not lp_ keys and do not expire.

What it does not do#

It does not let a remote admin raise a task’s budget, remove a cap, change the pause setting or the breaker, or raise or remove a team’s or the workspace’s limits or a team’s allowance. Those raises need the meter page on the node’s own machine. Tightening works over the channel.
It does not stop an agent that runs as the admin’s own user, on the admin’s computer, from using that computer’s admin key.
It does not serve the meter page to a browser. For the page, use an SSH tunnel to the loopback address.

Revoke an admin#

Delete the admin’s line in lockpin-admins.txt in the node’s folder. The node re-reads the file within a second and checks the admin on every request, so the admin stops working at once, on open connections too. A line that does not parse enrolls no one, and the node logs why.

Files#

File	Where	What it holds
`lockpin-admins.txt`	The node’s folder, beside the keys file	Each admin’s name, role, team and public keys.
`lockpin-admin-seq.json`	Beside it	Each admin’s last sequence number. If it is damaged, the node does not start. Deleting it lets every admin’s next grant start again from 1.
The node’s sealed store	The node’s folder	The node’s channel identity.
The admin’s sealed store	The admin’s computer	The admin’s private keys.

None of these files leaves the machine.

Troubleshooting#

Message	What to do
“the grant was issued in the future; check this computer’s clock”, or “the grant has expired”	The admin’s clock and the node’s differ by more than 60 seconds. Fix the clock.
“the node’s key is not the pinned one”	`-node-fp` is not the fingerprint `lockpin admin node-id` prints on the node.
“this client’s key is not enrolled on this node”	The node’s list does not have this admin’s key. Check `lockpin-admins.txt`.
“the grant’s nonce was not issued to this admin, has expired or was used”	Run the command again. It fetches a fresh nonce.
“a change over the remote admin channel needs a grant”	The request was sent without `lockpin admin call`.
Lockpin will not start	The message names what is missing: the sealed store (`-capabilities`), the node’s identity (`lockpin admin node-id`) or an enrolled admin (`lockpin admin enroll`). `lockpin doctor` reports the same.

A node that issues capability heartbeats to other nodes cannot serve them over the channel, since other nodes fetch them over plain HTTP. Keep the issuer’s -admin-listen on loopback and let the other nodes reach it through an SSH tunnel. See Several nodes.

Verify#

On the admin’s computer, read the node’s teams:

lockpin admin call -node https://10.0.0.5:8790 -node-fp sha256:HEX GET /lockpin/api/teams

Make a small change, such as creating a team, and check it on the node with lockpin teams list.