Skip to main content

max / alloy

Tell the person at the machine what the blank boot is alloy-layer-components.service installs the console and terminal and then reboots, so a boot draws nothing and restarts itself. Installed machines carry `quiet loglevel=3` so kernel and audit output cannot overwrite tuigreet, and there is no plymouth, so that screen is genuinely blank: systemd's status lines are suppressed along with everything else, and the unit's Description reaches nobody. It happens twice, and the second one is the problem. d866e125 recorded the silence against the first boot after an install, where "it is still setting up" is at least a plausible reading. The measurement in c4b54dc found the other one: `bootc switch` discards the layer, so adopting a rebuilt image drops the console and the unit re-fires to install the new image's copy. That is the common case, it is the mechanism that makes a rebuilt console reach anyone, and the machine was working when the user typed the command. usr/bin/alloy-layer-notice writes to /dev/console, which is the whole point rather than a detail. The unit's output goes to the journal, and a machine with no console and no terminal is precisely one whose owner cannot read a journal. `quiet` filters kernel printk and leaves a userspace write to the console device alone, so this lands on a screen the cmdline has otherwise silenced. It also speaks on failure, guarded on $SERVICE_RESULT, because that is the state a user cannot get out of unaided: no console, no terminal, and the session they would fix it from is the one that will not start. It names the journal unit and says the next boot retries, which is true because both conditions are still met. Nothing about the notice may cost the machine its console. Both invocations carry systemd's `-` prefix, every write inside the script is `|| true`, and there is no `set -e` to undo them. Same argument as alloy-session's, one unit earlier, and tests/layer_notice.rs holds all three along with the wiring. The gate is asserted too, and it is not incidental: the copy claims this happens after adopting a rebuild, which is only true while ConditionPathExists reads /usr/bin/alloy off the filesystem. A stamp file would leave the machine without a console and the notice describing something that no longer happens. VERIFIED on a real boot, not reasoned about. Built the image, installed to a disk with bootc install to-disk, booted it under qemu and read the VGA framebuffer back: the notice is on screen in the console palette for the whole 36-second layering window, the machine reboots, and the second boot goes straight to the greeter because the gate is false. The Containerfile checks the script is executable and parses, beside the checks that neither binary leaked into the image.
Co-Authored-By
Claude Opus 5 (1M context) <noreply@anthropic.com>
Author: Max Johnson <me@maxj.phd> · 2026-08-15 19:13 UTC
Signed with PGP, not checked
Commit: 3bdb777129c1df20386f5fa75f28dfaba874e55a
Parent: c4b54dc
4 files changed, +259 insertions, -3 deletions
M Containerfile +5 -1
@@ -2330,7 +2330,11 @@
2330 2330 test ! -e /usr/bin/alloy \
2331 2331 || { echo "the image carries /usr/bin/alloy; alloy-layer-components.service will never fire and the console can never be fixed" >&2; exit 1; }; \
2332 2332 test ! -e /usr/bin/shop \
2333 - || { echo "the image carries /usr/bin/shop; an unowned file cannot be layered over" >&2; exit 1; }
2333 + || { echo "the image carries /usr/bin/shop; an unowned file cannot be layered over" >&2; exit 1; }; \
2334 + test -x /usr/bin/alloy-layer-notice \
2335 + || { echo "alloy-layer-notice is missing or not executable; the layering boot is a blank screen again" >&2; exit 1; }; \
2336 + sh -n /usr/bin/alloy-layer-notice \
2337 + || { echo "alloy-layer-notice does not parse; the layering boot is a blank screen again" >&2; exit 1; }
2334 2338
2335 2339 # The themes the console refuses to run without: with no theme file on any
2336 2340 # search path it does not fall back, it exits.
M etc/systemd/system/alloy-layer-components.service +18 -2
@@ -71,6 +71,17 @@
71 71 [Service]
72 72 Type=oneshot
73 73 RemainAfterExit=yes
74 + # The notice comes first, because the install is the long part and the blank
75 + # screen is what it is explaining. `quiet loglevel=3` on the cmdline plus no
76 + # plymouth means this boot shows nothing at all otherwise, including this
77 + # unit's own Description. See usr/bin/alloy-layer-notice.
78 + #
79 + # `-` on both notice lines: a prefix that makes systemd ignore the exit
80 + # status. Telling the user is worth less than installing the console, so a
81 + # broken notice must not be what stops the machine getting one. The script
82 + # takes the same care internally; this is the belt outside it.
83 + ExecStartPre=-/usr/bin/alloy-layer-notice start
84 +
74 85 # By bare name, not by NEVRA, and it matters later rather than here. rpm-ostree
75 86 # records a request under the string it was given, so a package layered by full
76 87 # name-version-release cannot afterwards be removed by its bare name — it
@@ -93,11 +104,16 @@
93 104 # quietly comes up with no console.
94 105 ExecStart=/bin/sh -c 'exec /usr/bin/rpm-ostree install --idempotent -y $(cat /usr/share/alloy/components)'
95 106 ExecStart=/usr/bin/systemctl reboot
107 + # Only on failure, which is the state the user cannot get out of on their own:
108 + # no console and no terminal, and the session they would fix it from is the one
109 + # that will not start. $SERVICE_RESULT is systemd's, and it is `success` on the
110 + # ordinary path where the reboot above is already under way.
111 + ExecStopPost=-/bin/sh -c '[ "$SERVICE_RESULT" = success ] || /usr/bin/alloy-layer-notice fail'
96 112
97 113 # A failure here leaves a machine with no console, which the user cannot fix
98 114 # from the session they cannot start. Failing loudly is the only honest option:
99 - # the journal names the unit, and the next boot retries because the conditions
100 - # above are both still true.
115 + # the journal names the unit, the console says so through the notice above, and
116 + # the next boot retries because the conditions at the top are both still true.
101 117 #
102 118 # No Restart=, though. A unit whose second ExecStart is `reboot` and that
103 119 # restarts on failure is a boot loop, and a boot loop on the one machine class
A crates/alloy/tests/layer_notice.rs +172
@@ -1,0 +1,172 @@
1 + //! The one boot with no console has to say so, and every way that regresses is
2 + //! silent.
3 + //!
4 + //! `alloy-layer-components.service` installs the console and terminal and then
5 + //! reboots, so a person sees a boot that draws nothing and restarts itself.
6 + //! That happens after an install and again after adopting a rebuilt image,
7 + //! because `bootc switch` discards the layer and the unit re-fires to install
8 + //! the new image's copy (measured, `build/layertest/README.md`). The second is
9 + //! the common case and the one nobody expects.
10 + //!
11 + //! `usr/bin/alloy-layer-notice` is what breaks the silence, and it sits in
12 + //! front of the only thing that gives the machine a console. So it is asserted
13 + //! on two axes at once: that it still speaks, and that it can never be the
14 + //! reason the components are not installed. The Containerfile checks the script
15 + //! is executable and parses; that needs a build. This runs with `cargo test`,
16 + //! which is where the unit and the script are actually edited.
17 +
18 + use std::path::PathBuf;
19 +
20 + fn repo(relative: &str) -> String {
21 + let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
22 + .join("../..")
23 + .join(relative);
24 + std::fs::read_to_string(&path)
25 + .unwrap_or_else(|error| panic!("reading {}: {error}", path.display()))
26 + }
27 +
28 + fn unit() -> String {
29 + repo("etc/systemd/system/alloy-layer-components.service")
30 + }
31 +
32 + fn notice() -> String {
33 + repo("usr/bin/alloy-layer-notice")
34 + }
35 +
36 + fn directives(prefix: &str) -> Vec<String> {
37 + unit()
38 + .lines()
39 + .map(str::trim)
40 + .filter(|line| line.starts_with(prefix))
41 + .map(str::to_string)
42 + .collect()
43 + }
44 +
45 + #[test]
46 + fn the_notice_is_a_posix_shell_script() {
47 + assert!(notice().starts_with("#!/bin/sh\n"), "{}", notice());
48 + }
49 +
50 + // The wiring. Everything else here can hold and the boot still say nothing.
51 + #[test]
52 + fn the_unit_speaks_before_it_installs() {
53 + let pre = directives("ExecStartPre=");
54 + assert!(
55 + pre.iter()
56 + .any(|line| line.contains("alloy-layer-notice start")),
57 + "the unit must announce itself before the install: {pre:?}",
58 + );
59 + }
60 +
61 + // On failure the machine is stuck in the state the user cannot fix from the
62 + // session that will not start, which is exactly when a journal line is the
63 + // wrong place to put the explanation.
64 + #[test]
65 + fn the_unit_speaks_again_when_it_fails() {
66 + let post = directives("ExecStopPost=");
67 + assert!(
68 + post.iter()
69 + .any(|line| line.contains("alloy-layer-notice fail")),
70 + "a failure must reach the console, not only the journal: {post:?}",
71 + );
72 + }
73 +
74 + // And only on failure. Without the guard the ordinary path prints a failure
75 + // notice on its way to a reboot it is already performing.
76 + #[test]
77 + fn the_failure_notice_is_guarded_on_the_service_result() {
78 + let post = directives("ExecStopPost=");
79 + let line = post
80 + .iter()
81 + .find(|line| line.contains("alloy-layer-notice fail"))
82 + .expect("the unit notices failure");
83 +
84 + assert!(line.contains("SERVICE_RESULT"), "{line}");
85 + }
86 +
87 + // The `-` prefix makes systemd ignore the exit status. Telling the user is
88 + // worth less than installing the console, and this file exists as much to keep
89 + // the notice harmless as to keep it present.
90 + #[test]
91 + fn no_notice_can_stop_the_components_being_installed() {
92 + for line in directives("ExecStartPre=")
93 + .into_iter()
94 + .chain(directives("ExecStopPost="))
95 + .filter(|line| line.contains("alloy-layer-notice"))
96 + {
97 + let (_, value) = line.split_once('=').expect("a systemd directive");
98 + assert!(
99 + value.trim_start().starts_with('-'),
100 + "a failing notice would fail the unit: {line}",
101 + );
102 + }
103 + }
104 +
105 + // Same belt inside the script, for the calls the unit's `-` does not cover:
106 + // nothing here may exit non-zero, and `set -e` would undo every guard at once.
107 + #[test]
108 + fn the_notice_cannot_fail_from_the_inside_either() {
109 + let script = notice();
110 + // Comments excluded, and the header names `set -e` to explain its absence.
111 + // Matching on the whole file would fail on the sentence arguing for the
112 + // rule, which is the noisiest way a test can be wrong.
113 + for line in script
114 + .lines()
115 + .map(str::trim)
116 + .filter(|line| !line.starts_with('#'))
117 + {
118 + assert!(!line.contains("set -e"), "set -e would defeat the guards");
119 + }
120 +
121 + for line in script
122 + .lines()
123 + .filter(|line| line.contains("> /dev/console"))
124 + {
125 + assert!(line.contains("|| true"), "an unguarded write: {line}");
126 + }
127 + }
128 +
129 + // The journal is precisely what a machine with no console and no terminal
130 + // cannot show anyone, so stdout is not a substitute. `quiet` filters kernel
131 + // printk and leaves a userspace write to the console device alone, which is
132 + // what makes this land on a screen the cmdline has otherwise silenced.
133 + #[test]
134 + fn the_notice_writes_to_the_console_rather_than_the_journal() {
135 + assert!(notice().contains("> /dev/console"), "{}", notice());
136 + }
137 +
138 + // The claim the copy makes about adopting a rebuild is only true while the gate
139 + // is read off the filesystem. A stamp file would say "done" after a `bootc
140 + // switch` dropped the layer, so the unit would not re-fire, the machine would
141 + // stay without a console, and the notice would be describing something that no
142 + // longer happens. The unit's own comment argues this; here it is enforceable.
143 + #[test]
144 + fn the_gate_still_reads_the_filesystem_rather_than_a_stamp() {
145 + let unit = unit();
146 + assert!(
147 + unit.contains("ConditionPathExists=!/usr/bin/alloy"),
148 + "the console's absence is what makes the unit re-fire: {unit}",
149 + );
150 + }
151 +
152 + // The copy may not promise a security property, name a duration it cannot keep,
153 + // or carry the house's banned marks. The first line is what a person reads off
154 + // a blank screen, so it says what is happening rather than what it is called.
155 + #[test]
156 + fn the_copy_says_what_is_happening_and_promises_nothing_else() {
157 + let script = notice();
158 + let spoken: Vec<&str> = script
159 + .lines()
160 + .filter(|line| line.trim_start().starts_with("say \""))
161 + .collect();
162 +
163 + assert!(
164 + spoken
165 + .iter()
166 + .any(|line| line.contains("installing its console")),
167 + "the notice must name what it is doing: {spoken:?}",
168 + );
169 + for line in &spoken {
170 + assert!(!line.contains('—'), "no em dash in shipped copy: {line}");
171 + }
172 + }
A usr/bin/alloy-layer-notice +64
@@ -1,0 +1,64 @@
1 + #!/bin/sh
2 + # alloy-layer-notice — tell the person at the machine what the blank boot is.
3 + #
4 + # alloy-layer-components.service lays the console and terminal down as layered
5 + # packages, then reboots. Two boots therefore show nothing a user can act on:
6 + # the first one after an install, and the first one after adopting a rebuilt
7 + # image, because `bootc switch` discards the layer and the unit re-fires to
8 + # install the new image's copy (measured, build/layertest/README.md). The
9 + # second of those is the common case and the one nobody expects, since the
10 + # machine was working when they typed the command.
11 + #
12 + # Installed machines boot with `quiet loglevel=3` so kernel and audit output
13 + # does not overwrite tuigreet (usr/lib/bootc/kargs.d/10-alloy.toml), and there
14 + # is no plymouth. So that boot is a genuinely blank screen: systemd's own
15 + # status lines are suppressed by `quiet`, and the unit's Description never
16 + # reaches anyone. Nothing tells the user, hence this.
17 + #
18 + # Writing to /dev/console rather than to stdout, and it is the point rather
19 + # than a detail. The unit's output goes to the journal, which is exactly where
20 + # a person with no console and no terminal cannot read it. `quiet` filters
21 + # kernel printk and does not touch a userspace write to the console device, so
22 + # this lands on the foreground VT whatever the cmdline says.
23 + #
24 + # `|| true` on every write, and no `set -e`. This script is on the boot path in
25 + # front of the only thing that gives the machine a console: a notice that fails
26 + # must never be the reason the components are not installed. Same argument as
27 + # alloy-session's, one unit earlier.
28 + #
29 + # Deliberately dependency-free: sh, printf, one redirect. It runs on a machine
30 + # that does not have its own console yet, so anything it reaches for is
31 + # something that can be missing.
32 +
33 + say() {
34 + printf '%s\n' "$1" > /dev/console 2>/dev/null || true
35 + }
36 +
37 + case "${1:-start}" in
38 + start)
39 + say ""
40 + say "Alloy is installing its console and terminal."
41 + say ""
42 + say "This runs once after an install, and again after you adopt a"
43 + say "rebuilt image. It takes a few minutes, and the machine restarts"
44 + say "by itself when it finishes."
45 + say ""
46 + say "Nothing is wrong. There is no login until it is done."
47 + say ""
48 + ;;
49 + fail)
50 + say ""
51 + say "Alloy could not install its console and terminal."
52 + say ""
53 + say "The next restart tries again. If it keeps failing, the reason is"
54 + say "in the journal, which you can read over ssh:"
55 + say ""
56 + say " journalctl -u alloy-layer-components"
57 + say ""
58 + ;;
59 + *)
60 + # An unknown argument is a caller bug, and the unit is the only caller.
61 + # Saying nothing is right: the alternative is a machine whose first
62 + # words to its owner are a usage message.
63 + ;;
64 + esac