Skip to content

PATTERN Cited by 1 source

Hex-comparison flag for iPXE config check

Intent

When a configuration substrate reads variables in an encoding the consumer can't compare directly (e.g. iPXE reads UEFI variables as hex, but the expected value is a string), expose a boolean flag indicating whether the live state matches the desired hex representation so the caller can short-circuit a show + parse + conditional set sequence into a single set command.

Small primitive — one boolean — that compresses a multi-step read-modify-write into a write that's idempotent when the state is already correct.

Context

Cloudflare's fleet automation runs from iPXE scripts that read UEFI variables to validate boot configuration. The structural problem (Cloudflare 2026-06-01 core boot-time post):

"Since iPXE reads this variable as HEX, it was reading the string output as hex. To check if the network boot setting was modified and to reduce boot time (so we don't have to print the variables before setting them), we implemented a boolean flag, uefi-same-hex, to indicate whether a configuration changed."

Without the flag, the natural pattern is:

# 1. Read current value as hex
imgexec <CfHIIConfig_App> show ${uefi-setting}
# 2. Parse hex output back to a comparable representation
# 3. Compare against expected
# 4. If different, set
imgexec <CfHIIConfig_App> set ${uefi-setting}=${uefi-value}

Steps 2-3 require either string parsing in iPXE (limited) or running the tool twice (cost). Both add wall-clock to every boot.

Mechanism

"This enabled us to run a single set command instead of first running show to compare, and then set if the configuration was not in the desired state."

# construct path to read the update variable
set buffer-var-guid 91468514-75bc-4bb5-8f33-91efff9e9b1f
set var-upd-path efivar/CfHIIVarUpd-${buffer-var-guid}

# Run the config change command
imgexec <signed CF UEFI configuration App> set ${uefi-setting}=${uefi-value}

# Compare the update variable with the expected value if it has changed.
# If it has changed, set the local variable to reboot the system
iseq ${uefi-same-hex} ${${var-upd-path}} || set has-changed ${uefi-diff-hex}

Three structural pieces:

  1. The flag is exposed by the configuration substrate. The tool that writes the config also exposes a hex-encoded "what would equality look like" reference value (uefi-same-hex) so iPXE can compare against the post-write state in a single read.
  2. Always issue the set. No conditional pre-check; the write is idempotent. If the live state already matches, the set is a no-op (or near-no-op).
  3. Use the flag to drive next-step behaviour, not the write itself. The flag is read after the set to decide whether the system needs to reboot to make a real change take effect. If the live state didn't actually change, no reboot.

Why this is small but load-bearing

The flag eliminates one round trip per boot and removes the need for iPXE-side string parsing of UEFI variable hex output. At fleet scale this compounds:

  • Per-boot saving: probably tens of milliseconds of execution time, but more importantly removes a fragile parsing step.
  • Removes a code path — there's only one path now (always set, then compare flag), simplifying the iPXE script and reducing places it can fail.

The pattern is part of a broader Cloudflare 2026-06-01 discipline of moving everything onto iPXE so a single BIOS firmware image serves all SKUs with configuration deployed through the existing release pipeline.

Composition with other patterns

Generalisation: encoded-state comparison flag

The general lesson: when read encoding and write encoding differ, expose a comparison primitive at the encoding boundary rather than forcing the consumer to translate.

Substrate Native read encoding Comparison primitive
iPXE on UEFI hex uefi-same-hex boolean (Cloudflare 2026-06-01)
Etcd watch binary protobuf mod_revision integer for version compare
Kubernetes API JSON resourceVersion for optimistic concurrency
HTTP cache bytes ETag header for content equality
Database optimistic lock rows version column for compare-and-set

Whenever the consumer's natural comparison would require translation, exposing a comparable primitive at the substrate level is faster + less fragile than translating client-side.

When to use

  • Fleet automation runs from a substrate (iPXE, embedded shell, constrained runtime) that can't easily parse the read encoding.
  • The configuration tool can be extended to expose a comparison primitive cheaply.
  • Per-boot wall-clock savings matter (boot is on the critical path).

When not to use

  • The consumer is rich enough to do the comparison itself (full programming language with parsing libraries).
  • The configuration substrate is closed and can't be extended.
  • The wall-clock cost of show+parse+conditional-set is negligible for the use case.

Risks

  • Flag staleness — the flag's reference value (uefi-same-hex) must track the actual desired hex representation. If they drift, the comparison gives wrong answers. Treat the flag's reference as part of the declarative configuration.
  • Always-set side effects — issuing the set even when no change is needed must be safe (idempotent, no extra wall-clock, no audit-log noise). Cloudflare's set is cheap; not every substrate's would be.
  • Flag-driven behaviour vs actual change — the flag indicates whether the comparison matched, not whether the underlying hardware state will change. Cloudflare uses it for reboot decisions; using it for other decisions (audit, alerting) needs care.
Last updated · 542 distilled / 1,571 read