Interface
What other programs can rely on from lnk box.
lnk box
The commands other modules run, and what each may rely on from them.
lnk box forward <box> --socket <path> --proxy-port <local>
ssh -R to a Unix socket at <path> in the box's home folder, until it
drops: a SOCKS proxy there, the one on this machine's loopback at
<local>.
Its socket
The socket's folder is made first, only the box user's, and a socket
left there by a connection before removed. --port <p> instead: on
127.0.0.1:<p> of the box. --to is required: ssh's own SOCKS,
which reaches anything here, is never used.
lnk box run <box> -- <args>
lnk <args> on the box, its input and output passed through untouched,
its exit status. Read by lnk agent move and lnk agent create --on,
readying the box first (module add harness secret, sandbox ready --yes, agent route direct --default), by lnk agent show (when the
agent is on a box) and by lnk agent list (a box without the harness
module has no agents).
From lnk secret delete
lnk secret delete runs secret delete <NAME> --here --agent <id> on
each box a move sent the secret to, as the move noted first, the agent's
ID that of the agent whose own key it is. Its exit status says whether
it was reached. It never runs on a box lnk box list --json lists with
another resource than the one noted.
lnk box create <cloud> --yes
Makes a box in the cloud account, without asking, talking on stdout;
exit status 0 once it's up. It is then the newest (created) in
account of lnk box list --json --here. Read by lnk agent move, to
a cloud account with no box of yours, and with --image always.
--image
With --image <name>, the box's disk starts from that image of yours
there. lnk box create <cloud>, its name before, does the same for a
release.
lnk box size list --json
The reply contains pick, place, sizes, rates, disk_gb and
disk_type. The disk fields are the effective spec's rounded allocation
and kind, so a caller can price the same disk a launch will request. Each fitting
machine type's price is its hourly machine price. rates supplies the
provider's disk, address and transfer rates, or is null when unavailable.
A missing price remains unknown. Callers calculating a complete box cost
must include its actual disk size and address rather than treating a
machine-only quote as the whole cost.
lnk box list --json
[{"name", "account", "kind", "place", "id", "resource", "size", "ip"?, "state", "created", "found", "stopped_by_cloud"}],
link_box_contract::Listed, which the box module writes and every
reader reads: one entry per box, those this computer knows and those
each connected account has tagged as yours. --here asks no cloud;
--refresh asks each for each box's state.
Its fields
created is when this computer made it, in Unix seconds, 0 for one
found in a cloud; found is "here", or "cloud" for one found just
now. id is the cloud's instance id, which is the cloud's and not
Link's. resource is the box as Link names it, box:<its machine ID>,
null for a box from before IDs until Link reaches it.
stopped_by_cloud
A spot box its cloud stopped, as its adapter says. From an adapter that
can't say, a spot box this computer last saw running and found stopped,
as another computer's lnk box stop leaves it too.
Who reads it
lnk agent move (which boxes there are, and in which account: a cloud
account's name moves to its one box, unasked only when its created
isn't 0, made on this computer) and lnk agent list (which to ask).
The question it asks
What lnk box asks of the modules above it, in its own types.
box.removed
Once lnk box delete has deleted a box from its cloud, it asks each
module that answers box.removed to take back what it gave the box,
naming the box by its name and machine ID, in its envelope and its
protocol
(Questions).
Each answers with what it couldn't take back, a sentence each, which
lnk box delete prints as a warning. The box is gone either way.
A program that makes boxes
What a program that makes and sets up boxes may run, each read only for its exit status but where said.
Making and saving
lnk box create <cloud> --name <box> --yes [--spec <file>] [--image-hash <hash>]; lnk box image list <cloud> --hash <hash> --json ([] when none is ready); and lnk box image create <box> <image> --hash <hash> --yes.
Using a box
lnk box copy <box> <files> <folder>; lnk box run <box> -- <args>
(its input passed through); lnk box ssh <box> -- <command> (its
output passed through); lnk box stop <box>; lnk box delete <box> --yes; and lnk box list --here --json (which names are boxes).
On the box
Through lnk box run: module add sandbox, sandbox ready --yes, and
for a preview module add tunnel and tunnel open <port> --public | --account=<visitors>.