Skip to content

inner

inner

Generate the scripts that run inside a slot's test container.

Two scripts per slot, both written to the shared results mount so the container executes real files — the historical bash -c string with its three levels of quote-escaping is gone:

  • the outer script runs as root: copy the read-only source mount into a writable workspace, prove the init system matches the slot's contract, then drop to the slot's test user;
  • the inner script runs as the test user: export the capability contract, bootstrap a Python 3.12 venv plus uv, sync the repo's locked dependency groups, and walk the configured phases.

A slot that boots systemd under krun also gets the units its systemd runs the outer script through (boot_units).

Command phases abort the slot on failure (set -e); pytest phases record the first failing exit code and keep going, so a single run surfaces every failing suite.

TEST_UID = 1000 module-attribute

BOOT_TIMEOUT_SECONDS = 300 module-attribute

MASKED_UNITS = ('systemd-firstboot.service', 'console-getty.service') module-attribute

outer_script(config, slot_name, *, boots_systemd=False)

Root-side container entry: workspace prep, init-system proof, user drop.

boots_systemd is the runner's call: the slot may boot systemd, and its image ships it. There this script is the slot service's ExecStart (see boot_units), not the container command; the flow is otherwise the same.

Source code in src/terok_util/matrix/inner.py 
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def outer_script(config: MatrixConfig, slot_name: str, *, boots_systemd: bool = False) -> str:
    """Root-side container entry: workspace prep, init-system proof, user drop.

    *boots_systemd* is the runner's call: the slot may boot systemd, and its
    image ships it.  There this script is the slot service's ``ExecStart``
    (see [`boot_units`][terok_util.matrix.inner.boot_units]), not the
    container command; the flow is otherwise the same.
    """
    spec = SLOTS[slot_name]
    lines = [f"#!{spec.bash_path}", "set -e -o pipefail", ""]
    if config.krun:
        lines += _krun_dev_std_symlinks()
        if spec.kind is SlotKind.CONTAINER:
            lines += _krun_real_disk(spec.user)
        if spec.runs_nested_podman(config.flavor):
            lines += _krun_relax_devices()
            lines += _krun_mount_mqueue()
            lines += _krun_podman_binds(spec.user, bind_runroot=not boots_systemd)
    lines += [
        f"cp -a {SOURCE_MOUNT} {WORKSPACE_DIR}",
        f"chown -R {spec.user}:{spec.user} {WORKSPACE_DIR}",
    ]
    if spec.kind is SlotKind.CONTAINER:
        lines += _init_system_proof(slot_name, boots_systemd)
    if spec.runs_nested_podman(config.flavor):
        lines += _resolv_conf_strip()
    lines += ["", f"install -m 0755 {RESULTS_MOUNT}/inner-{slot_name}.sh /tmp/inner.sh"]
    if boots_systemd:
        lines += _start_user_manager(spec.user)
    lines += [*_user_drop(spec.user, spec.kind), ""]
    return "\n".join(lines)

inner_script(config, slot_name, scope='all')

Test-user-side flow: env contract, venv + deps, configured phases.

Source code in src/terok_util/matrix/inner.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
def inner_script(config: MatrixConfig, slot_name: str, scope: str = "all") -> str:
    """Test-user-side flow: env contract, venv + deps, configured phases."""
    spec = SLOTS[slot_name]
    lines = [f"#!{spec.bash_path}", "set -e -o pipefail", ""]
    if spec.kind is SlotKind.CONTAINER:
        lines += [
            f'export PATH="${{PATH:+$PATH:}}{_ADMIN_TOOL_PATH}"',
            "export XDG_RUNTIME_DIR=/run/user/$(id -u)",
        ]
    if config.krun and spec.kind is SlotKind.CONTAINER:
        lines += _krun_tmpdir_export()
    lines += _env_contract(config, slot_name)
    lines += ["", f"cd {WORKSPACE_DIR}", ""]
    if spec.kind is SlotKind.NIX:
        lines += _nix_python_report(slot_name)
        lines += _plain_venv_bootstrap(f"python{PYTHON_VERSION}")
    else:
        if config.flavor == "podman":
            lines += _podman_report_and_preflight(slot_name)
        lines += _uv_or_venv_bootstrap()
    lines += _uv_sync(config.slot_groups(slot_name))
    lines += _phase_walk(config, slot_name, scope)
    return "\n".join(lines) + "\n"

boot_units(slot_name)

The units a booted slot runs through, keyed by path under the control dir.

crun's krun handler implements no exec, so nothing reaches a booted microVM through podman exec. Its systemd starts terok-matrix.target instead: the normal boot, then the outer script as a oneshot service. The service pipes the script's output to the console, which libkrun hands to podman's stdout as log records; the runner strips their prefix. Nothing reopens libkrun's krun-stdout port: systemd closed it on taking over PID 1, and libkrun panics when a port opens a second time. The service records its exit status on the results mount, because podman's own status is the VM's, and then ends the VM with a reboot, the way libkrun's own init ends it. A boot that does not reach multi-user.target in time ends the VM the same way.

Source code in src/terok_util/matrix/inner.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def boot_units(slot_name: str) -> dict[str, str]:
    """The units a booted slot runs through, keyed by path under the control dir.

    crun's krun handler implements no exec, so nothing reaches a booted
    microVM through ``podman exec``.  Its systemd starts ``terok-matrix.target``
    instead: the normal boot, then the outer script as a oneshot service.
    The service pipes the script's output to the console, which libkrun
    hands to podman's stdout as log records; the runner strips their prefix.
    Nothing reopens
    libkrun's ``krun-stdout`` port: systemd closed it on taking over PID 1,
    and libkrun panics when a port opens a second time.  The service
    records its exit status on the results mount, because podman's own
    status is the VM's, and then ends the VM with a reboot, the way
    libkrun's own init ends it.  A boot that does not reach
    ``multi-user.target`` in time ends the VM the same way.
    """
    shell = SLOTS[slot_name].bash_path
    login = " -l" if SLOTS[slot_name].requires_boot else ""
    service = [
        "[Unit]",
        f"Description=terok matrix: the {slot_name} slot's outer script",
        "After=multi-user.target",
        "SuccessAction=reboot-force",
        "FailureAction=reboot-force",
        "",
        "[Service]",
        "Type=oneshot",
        # A pipe, not the console, is the script's stdout, as in the plain shape:
        # nothing draws progress bars for a terminal nobody watches.
        f"ExecStart={shell}{login} -o pipefail -c"
        f' "{shell} {RESULTS_MOUNT}/outer-{slot_name}.sh 2>&1 | cat"',
        f"ExecStopPost={shell} -c 'echo \"$$EXIT_STATUS\" > {RESULTS_MOUNT}/{slot_name}.exit'",
        "StandardOutput=tty",
        "TTYPath=/dev/console",
    ]
    target = [
        "[Unit]",
        f"Description=terok matrix: the {slot_name} slot, booted",
        f"Requires=multi-user.target {SLOT_SERVICE}",
        "After=multi-user.target",
        "AllowIsolate=yes",
    ]
    boot_deadline = [
        "[Unit]",
        f"JobTimeoutSec={BOOT_TIMEOUT_SECONDS}",
        "JobTimeoutAction=reboot-force",
    ]
    return {
        SLOT_SERVICE: "\n".join(service) + "\n",
        BOOT_TARGET: "\n".join(target) + "\n",
        "multi-user.target.d/terok-matrix-boot.conf": "\n".join(boot_deadline) + "\n",
    }