REFERENCE

Prewarm

Reference for recording, listing, enabling, disabling, stopping, and removing prewarm profiles.

A prewarm profile is the data one recorded workload read from one base snap. Boxes created from that snap, or from any snap forked from it, use the profile automatically on their first runs. Boost First Runs shows when and how to use one.

Commands

sys9 run prewarm record <name> --snap <base-snap-id> [--max-runtime <duration>] -- <command...>
sys9 run prewarm ls
sys9 run prewarm inspect <name-or-id>
sys9 run prewarm enable <name-or-id>
sys9 run prewarm disable <name-or-id>
sys9 run prewarm stop <name-or-id>
sys9 run prewarm rm <name-or-id>

Record

--snap names the exact base. It must be an available snap that is not attached to a box.
--max-runtime defaults to 1m and accepts 1s to 12h. It counts only the time the workload runs.
The workload’s output streams to your terminal, so record rejects --json.
After a normal exit, an error exit, the runtime limit, or Ctrl+C, the CLI keeps waiting until the recorded data is saved and installed.

Exit codes follow the workload: its own non-zero code is returned as is, Ctrl+C returns 130, and reaching --max-runtime counts as success once the profile is ready.

States

recording: the workload is running.
finalizing: the workload ended and its recorded data is being saved.
ready: the profile can be used. A new profile is enabled as soon as it is ready.
error: saving failed. Record again with the same name and base.

Which profile a box uses

A box uses a profile when the profile is ready, enabled, and recorded on the box’s source snap or on one of that snap’s ancestors. With several candidates, the closest ancestor wins. Snaps on other branches of the fork tree never match.

Data that a later fork wrote itself is not part of the profile and is read the normal way.

Manage

enable turns a profile on and installs its data on the hosts currently serving your org.
disable stops new execs from using it at once.
stop ends a running recording from any terminal and keeps what was collected.
rm removes a ready or error profile. Stop a running recording and let it finish first.

A base snap cannot be deleted while a profile is recorded on it. rm keeps the snap and frees it for deletion.

Output

ls prints one line per profile with its state, whether it is enabled, how many hosts have it, the use count, and the last use. inspect adds the base snap, recorded size, and any per-host install error. ls, inspect, enable, and disable support --json.