# Milestones
`burnout list` is built, on all three hosts. Nothing writes a drive yet.
[The roadmap](roadmap.md) says which phase is done and what comes next.
This file holds the decisions that shape the work, and the reason behind each
one.
It also holds the options that lost, because the reason a choice lost is the
part that a later reader needs.
Nobody has run any of this.
Two assumptions carry the whole Windows path, and they are named at the end.
Test them before you write real code.
---
## The rule that decides everything else
**Burnout never delegates to the host.**
It calls no `diskutil`, no `mkfs`, no `format`, and no `bootsect`.
It mounts nothing.
It opens the raw device, and it writes the partition table and the file
systems itself.
The goal is one process that behaves the same way on Windows, on macOS, and on
Linux.
The moment the code calls `diskutil` on one host and `mkfs.vfat` on another,
it inherits three sets of defaults, three sets of failure messages, and three
sets of bugs.
"The same process" then becomes a thing to maintain instead of a thing that is
true.
The rule also buys the tests.
Code that writes to a seekable target works against a file, so almost all of
Burnout runs in a test that touches no device.
[CONTRIBUTING.md](../CONTRIBUTING.md) refuses a test that opens a real device,
and this rule is what makes that refusal practical.
The operating system layer holds five operations only:
- List the drives.
- Unmount the volumes of a drive.
- Open the device.
- Flush.
- Close.
Two traits carry them, and not one.
One trait lists the drives, because that needs no drive and no handle.
One trait unmounts and opens one drive.
The handle that the open returns reads, writes, seeks and flushes, and the
drop of it closes the device.
A flush is an explicit call that can fail, because a drop reports no error and
a write is not complete before the flush returns.
Everything above that layer is one body of code.
---
## Two write modes
A drive gets one of two treatments.
The modes share the device layer, the progress reporting, and the safety
checks, and they share nothing else.
| | Raw mode | Windows mode |
| --- | --- | --- |
| For | Linux, BSD, any hybrid ISO, any `.img` | A Windows installer ISO |
| What it does | Copies the image byte for byte | Partitions, formats, writes files |
| The partition table | Comes from inside the image | Burnout creates it |
| Verification | Hash of the device against the source | A hash for each file |
A Linux ISO is already a bootable disk image.
It carries its own boot code, its own partition table, and its own EFI system
partition inside the file.
Writing it means a copy of the bytes, and nothing else.
A Windows ISO is not a bootable disk image.
It has no boot code for a USB drive.
A byte for byte copy of it gives a drive that most firmware refuses.
That difference is the reason Windows mode exists, and the reason a tool like
Rufus exists at all.
Raw mode is the first thing to build.
It is one code path, it exercises the whole device layer on all three hosts,
and it gives a useful tool before any Windows work starts.
---
## Burnout chooses the mode, and the person does not
Read the first 512 bytes of the image.
- A boot signature and a partition table there mean a hybrid image.
Use raw mode.
- No hybrid table, and `sources/install.wim` or `sources/install.esd` inside,
mean a Windows installer.
Use Windows mode.
`--mode raw|windows` overrides the result.
It exists for the day the guess is wrong, and a normal person never types it.
This is the general rule for the whole command line.
An option that the tool can decide for itself is a bug in the tool, not a
choice for the person.
---
## macOS install media is not planned
Linux and BSD ship a hybrid ISO, which is already a bootable disk image.
macOS is a third category, and it fits neither mode.
Burnout does not make a macOS installer. The roadmap keeps it as a later
maybe, and the reasons below say what it would cost.
**Apple ships no ISO.**
You get `Install macOS .app` from the App Store, or an
`InstallAssistant.pkg`.
Neither one is a disk image.
**A `.dmg` file is usually not a raw image.**
Apple compresses them, so a byte for byte copy gives a drive that starts
nothing.
An uncompressed read and write dmg is a real raw image, and raw mode writes one
like any other.
**The supported path is `createinstallmedia`.**
It is a closed binary inside the `.app`, it runs on macOS only, and it needs
root.
A call to it breaks the rule at the top of this file, and it does not exist on
Windows or on Linux, so the promise of one process on three hosts ends there.
**The file system is HFS+ or APFS.**
APFS has no complete public specification.
That is a different order of work from the exFAT writer, and it is not work
this project takes on.
**Apple silicon adds boot rules of its own**, and no tool can make media for a
Mac that is newer than the installer.
### What the code does instead
Detect the input and refuse with a sentence that helps.
- An `.app` bundle, an `InstallAssistant.pkg`, or a compressed dmg: stop, say
that Burnout does not make macOS install media, and name
`createinstallmedia`.
- An uncompressed raw dmg: treat it as any other raw image.
A clear refusal costs one message.
A drive that starts nothing costs an hour, and the person does not know why.
---
## The layout that Windows mode writes
One MBR partition table, and two partitions.
- **Partition 1. FAT32, about 1 GB.** Every file from the ISO except
`sources/install.wim` or `sources/install.esd`.
- **Partition 2. exFAT, the rest of the drive.** The install image, whole.
UEFI firmware reads FAT only, so every boot file sits on partition 1, and the
firmware never looks at partition 2.
Windows PE starts from partition 1 and then reads partition 2 itself.
MBR, and not GPT.
Burnout writes the table itself, so the spare EFI partition that `diskutil`
adds on macOS never appears.
MBR also leaves the door open for Legacy BIOS boot later, and that costs
nothing now.
### Why the install image does not get split
FAT32 holds no file of 4 GiB or more, and a current `install.wim` is usually
larger.
The usual answer is to split it into `install.swm` parts.
WinDiskWriterX does this, and it uses wimlib for the work.
Burnout writes no WIM file at all.
The second partition has no 4 GiB limit, so the image goes on whole.
This also handles `install.esd`, which the split approach never did.
The consequence is the licence.
wimlib is LGPL, and it is about seventy thousand lines of C to link on three
operating systems.
Burnout stays MIT, and the build stays simple, because it never needs wimlib.
### Why partition 2 is exFAT and not NTFS
NTFS was the first choice, and it was wrong.
**macOS cannot write NTFS.**
It mounts NTFS read only.
An NTFS partition gives a Windows path that works on two hosts out of three,
which defeats the point of the project.
exFAT has no 4 GiB file limit either, and Windows PE reads it.
Burnout writes the file system itself, so the host does not need to support
exFAT for anything.
Nothing mounts the drive on the machine that makes it.
---
## The Windows 11 options come from one text file
Windows Setup reads `autounattend.xml` from the root of the drive.
Burnout writes that file, and nothing else, to give the options that people
want:
- **Skip the hardware checks.** A `RunSynchronous` command in the `windowsPE`
pass adds the `LabConfig` keys for the TPM, Secure Boot, RAM, storage and
CPU checks.
- **Skip the Microsoft account.** `HideOnlineAccountScreens` in the
`oobeSystem` pass, and a command in the `specialize` pass that sets the
`BypassNRO` key. Setup then asks for a local account and its password, so
Burnout holds no password. On 25H2 with no network, the first alone stops at
the network page, and [the roadmap](roadmap.md) records that measurement.
A local account in `` lost, because it puts a password into a
file on the drive. WinDiskWriterX lists this as a thing it does not do.
- **Name the install source.** `` points
Setup at the image on partition 2. **This one is not optional.**
**Burnout writes this file on every Windows drive, whether anybody asks for an
option or not.**
[The spike](spike-layout.md) measured why.
Windows PE mounts the exFAT partition and reads it, and Setup still does not
look there, because Setup looks beside `setup.exe`.
With no `InstallFrom` path, Setup stops and says that a media driver is
missing.
So the file that carries the options is also the file that makes the layout
work at all.
Keep the rest of it small.
Write only the entries that the person asks for, and leave the rest of Setup
interactive.
The path holds a drive letter that Windows PE assigns for itself, and a
machine with another disk attached numbers things differently.
[The spike](spike-layout.md) measured that, and it closed it.
A fixed letter fails with `0x80070490` as soon as a second disk exists, so the
file carries a `RunSynchronous` search that finds the volume holding
`sources\install.wim` and pins it to `W:` with `diskpart`, and the path then
names `W:`.
`diskpart` cannot select a volume by label, so the search is by content and
not by name.
Two options lost, and both for the same reason.
- **An offline edit of the SYSTEM hive inside `boot.wim`.** This needs WIM
read, WIM write, recompression, and a registry hive writer.
It is the most work of any option by a wide margin.
- **The Server installation type.** WinDiskWriterX sets `installationtype` to
Server in the image metadata, and Setup then skips the checks.
It is clever and much cheaper than the hive edit, but it is still a write to
a WIM file, and the rule above says Burnout writes none.
Keep the Server trick in mind as a fallback for somebody who wants no
`autounattend.xml` on the drive at all.
A text file has one more property that the other two do not.
The person can read it, change it, or delete it, and the drive is then stock.
---
## Elevation
A raw device write needs root on macOS and on Linux, and Administrator on
Windows.
Burnout cannot avoid this, and it does not try.
**Burnout never asks for a password itself.**
On macOS and on Linux it starts itself again through `sudo`, and `sudo` asks.
The password goes to a program that already holds that trust.
A tool that reads a password into its own memory and passes it on is how this
kind of tool gets a vulnerability.
Three details in the restart:
- Use the path from `current_exe()`, and never `argv[0]`. The caller controls
`argv[0]`.
- Put `--` before the path, or `sudo` reads the Burnout options as its own.
- Pass a list of arguments, and never a command string. There is then no
quoting and no injection.
Pass `--elevated` on the restart, and refuse to elevate a second time.
Without that guard, any case where elevation appears to succeed while the
user id stays wrong asks for a password forever.
**The guard is an argument and not an environment variable.**
`sudo` clears the environment. `env_reset` is the default in `sudoers`, so a
variable set before the restart does not reach the second process, the guard
never fires, and the case it exists for is the case it misses.
Measured on Fedora Linux 44 with sudo 1.9.17p2:
$ BURNOUT_ELEVATED=1 sudo -- sh -c 'echo env=[$BURNOUT_ELEVATED] arg=[$1]' sh --elevated
env=[] arg=[--elevated]
$ echo outer=$(id -u); sudo -- id -u
outer=1000
0
The variable is gone and the argument is there.
`sudo -E` keeps the variable, and it is no answer: it works only where
`sudoers` gives that user the `SETENV` tag, so it turns a guard into a thing
that depends on somebody else's configuration.
A local person who types `--elevated` by hand gets a refusal that says
Burnout needs root. The flag opens nothing, which is why it can be one.
Try `sudo` first, then `doas`.
Do not use `pkexec`, which targets a desktop and changes the environment.
**On Windows, do not elevate.**
Detect the shortfall and print how to fix it.
Windows can elevate, through `ShellExecuteEx` with the `runas` verb, and the
result is worse than a clean failure: it starts a second process in a **new
console window**, the first terminal returns at once, the progress goes to a
window that nobody watches, that window closes at the end, and the exit code
never reaches the shell.
### Elevate at the right moment
parse the arguments no privilege
validate the image file no privilege
list the drives, find the target no privilege
------------------------------------------------
check the privilege, elevate here
------------------------------------------------
confirm the target with the person
write
`burnout list` runs with no privilege on all three hosts, so a person sees
their drives without a password.
Elevation comes after the image check, so nobody gives a password and then
learns that the path is wrong.
It comes before the confirmation, so the person confirms one time and not one
time for each process.
`--no-elevate` fails instead of asking, for a script.
When the input is not a terminal, do not try to elevate at all.
A `sudo` prompt inside a pipeline stops and waits for nobody.
### Build no helper
Do not ship a setuid binary, and do not ship a privileged background helper.
Either one lets any local user drive Burnout into a disk that the user cannot
open alone.
[SECURITY.md](../SECURITY.md) lists that as in scope.
The restart through `sudo` is safe because it leaves the decision with the
operating system.
---
## The shape of the command
A device name is the one thing that cannot be the same on three hosts.
`/dev/disk4`, `/dev/sdb` and `\\.\PhysicalDrive2` have nothing in common.
So a device path is never the target.
burnout list
burnout write ubuntu.iso 2
`list` prints a stable index, the maker, the size, and the connection.
The two commands above are the same on all three hosts.
`--device /dev/sdb` stays available for a script.
---
## Verification makes two different promises
Say which one ran.
Do not let one word cover both.
- **Raw mode** compares a hash of the written device against a hash of the
source file. This proves the drive holds the image.
- **Windows mode** built a file system that the source never had. A hash of
the whole device proves nothing there. The check is a hash for each file
that Burnout copied.
[SECURITY.md](../SECURITY.md) puts a verification pass that reports a success
it did not run in scope, so the report must name the check it performed.
---
## Both of these are now measured
[The spike](spike-layout.md) answered them on a running Windows 11 Setup.
1. **Windows PE reads exFAT.** It mounted the exFAT partition as `D:` and
walked its directory tree. The layout stands, and no file is split.
2. **Setup does not find the image across the partition boundary.** The
`InstallFrom` path is a requirement, not an insurance.
The `LabConfig` keys were measured at the same time, and they work: the screen
that refuses a machine with no TPM 2.0 never appears.
---
## Version 1
| In | Out |
| --- | --- |
| Raw mode for a hybrid image | Legacy BIOS boot |
| Windows mode, UEFI boot | Windows To Go |
| The mode chosen from the image | A write to one partition |
| `list` and `write` | A drive that holds many images |
| Refusing a macOS installer clearly | macOS install media |
| The `autounattend.xml` options | A graphical interface |
| Verification, named per mode | |
| Elevation on all three hosts | |
**Legacy BIOS waits.**
It costs a grub4dos download at run time, MBR and partition boot code, and a
test on hardware that gets rarer each year.
The MBR layout above means it fits later with no change to anything.
[P8 in the roadmap](roadmap.md#p8-legacy-bios-boot) does it, and it changed
one part of this: Burnout writes its own boot code, so no grub4dos and no
download come in.
**A write to one partition came in version 2.**
[P9 in the roadmap](roadmap.md#p9-a-write-to-one-partition) does it.
**Windows To Go came in version 3, for UEFI.**
It applies an image to a disk instead of copying an installer, so it is a
third write mode and not an option on the second one.
[P10 to P12 in the roadmap](roadmap.md#windows-to-go-p10-to-p12-toward-version-3)
do it.
**macOS install media waits longest.**
The section above says why. The roadmap keeps it, with a graphical interface and a drive that holds
many images, in
[Later, maybe](roadmap.md#later-maybe).
---
## The toolchain
Rust.
It gives one static binary for each host with no runtime, and the three device
layers are small enough to write directly against `SetupAPI` and the IO
control codes on Windows, IOKit and Disk Arbitration on macOS, and `sysfs` on
Linux.
`sysfs` and not `libudev`.
`libudev` is a C library under the LGPL, so the binary then needs it at run
time, and the sentence above about one static binary stops being true.
`sysfs` is a set of text files that the kernel writes, so the Linux code reads
them with the standard library alone, and the part of it that decides anything
is a pure function that the tests run on all three hosts.
If a stable name for a drive is ever needed, read the symlinks under
`/dev/disk/by-id/`, which is still the standard library and still not
`libudev`.
- `clap` for the command line.
- `indicatif` for progress.
- `fatfs` for FAT32. It is MIT, and it works over anything that seeks. A
device takes it only through a sector adapter, and Burnout repairs two
faults in the directories that its release 0.3.6 writes. The roadmap gives
both, under P3.
- `blake3` for the hashes.
- An exFAT writer, which this project writes. The format is documented, and it
is a few thousand lines. It is far less work than NTFS, and less work than a
WIM splitter.
Add a dependency only with a reason in the pull request.
Prefer MIT and Apache 2.0.
A copyleft dependency is not forbidden, and it does change what this project
can ship in one binary, so say so.
### One correction to carry over
WinDiskWriterX asks for Administrator rights only for Legacy BIOS boot,
because `diskutil` does the rest of the work.
Burnout partitions the raw device itself, so it needs root or Administrator on
every path, every time.