DR SAN Linux runtime lab, 2026-10-04

Purpose
Observe real Open-iSCSI, TGT and DM Multipath in a disposable diskless Linux
VM. This is an original teaching experiment. It is not a production runbook.
Two guest-loopback portals access one RAM-backed 64-MiB file. The script
checks discovery versus sessions, path identity, capacity, parser diagnostics,
direct marker I/O, orderly logout, rejoin and cleanup. Nine groups passed twice.
No physical SAN, independent fabric, FC, abrupt failure, application workload,
benchmark, crash durability, reservations or fencing were tested.

Recorded environment
Alpine 3.24.2 aarch64; kernel 6.18.52-0-virt; Python 3.14.8;
open-iscsi 2.1.12-r0; multipath-tools 0.13.0-r0; scsi-tgt 1.0.97-r0.
Full package lists, command outputs and bounded conclusions are in evidence.json
and evidence-repeat.json. Upstream rolling documentation is not release-pinned
source code. Package versions identify the implementation actually executed.
The ISO SHA-256 matched its official HTTPS checksum; signature was not checked.

Replay prerequisites
Use only a new disposable VM with a RAM root and no data disks. Never use a
production initiator or a VM containing unrelated storage sessions. The script
refuses pre-existing SCSI/NVMe/virtio data disks, maps and storage daemons.
The marker is an additional explicit preparation step, not sufficient isolation.
Use an empty temporary host directory for the shared /mnt/dr directory.
Guest networking uses QEMU user NAT with no forwarded ports. The two iSCSI
portals are guest loopback only. No host disks are attached. Only the temporary
share is writable from the guest; do not share a project or home directory.

Recorded macOS bootstrap
The included boot.py and guest.py retain the exact temporary work path used:
/tmp/dr-san-runtime-work. They are evidence/replay helpers, not an installer.
Do not overwrite that path if it exists or belongs to another execution.
For a fresh replay, change both helpers' w paths to a NEW empty temporary
directory, and put setup.sh and run.py into its share/ subdirectory.
The host used an already installed UTM QEMU 7.2.0 framework. This is the tested
emulator, not a recommendation of the latest release. qemu-launch.c is an
original minimal CLI loader. It does not start UTM user VMs or modify UTM state.
On the recorded host it was compiled using:
clang -isysroot /Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk qemu-launch.c -Wl,-rpath,/Applications/UTM.app/Contents/Frameworks -o qemu-launch
Copy that executable to the selected work directory; review the framework paths
in boot.py. A normal qemu-system-aarch64 executable can replace the loader and
framework argument, but that alternative bootstrap was not executed here.

ISO preparation
Download the ISO and checksum URLs from acquisition.json over HTTPS into the
new work directory. Compare SHA-256 with both the official checksum and the
recorded hash. Preserve any mismatch and stop. Extract boot/vmlinuz-virt and
boot/initramfs-virt from the ISO using an ISO reader (macOS bsdtar was used).
The recorded kernel is EFI zboot. For this QEMU direct boot, its gzip payload
was extracted with Python: read offset,length using struct.unpack_from('<II',
kernel_bytes,8), then gzip.decompress(kernel_bytes[offset:offset+length]).
Check the resulting bytes at [56:60] equal b'ARM\x64', and compare SHA-256 with
acquisition.json.kernelExtraction.uncompressedSha256. Save as boot/Image.
Do not apply this format-specific extraction blindly to a different kernel.

Execution
Run boot.py to start the owned VM, log into its ephemeral root console, mount
only the temporary share and run setup.sh. Inspect share/setup.txt and require
successful installation and the marker /run/dr-san-disposable. Repositories are
Alpine v3.24 official main/community; replay at a later date may resolve newer
packages. Record actual versions and do not relabel them as the recorded run.
Then, using the included serial helper:
python3 guest.py 'python3 /mnt/dr/run.py --output /mnt/dr/evidence.json > /mnt/dr/run.txt 2>&1' 90
Require the DR_DONE marker to end in :0, no Python traceback, passed=9, failed=0,
and failure=null in the output JSON. The helper prints remote status; its own
exit code alone is not a guest-success assertion. Repeat with a separate output
filename. Compare the script hash and all nine groups, not timestamps or sdX
names. Verify capacity=67108864, degraded paths=1, restored paths=2 and matching
marker hashes before/after their relevant transitions. Inspect all stderr.

Cleanup and failed attempts
The script closes the owned map before logging out its exact target/portals,
deletes its target/node records, stops its foreground daemons in separate
process sessions, restores two saved configuration files and removes its
backing directory. Its WWID may remain in the guest multipath remembered-WWID
file. This is a disposable guest and is destroyed after the exercise.
If a run fails or times out, inspect the same owned VM before doing anything
else. Do not run broad logout/delete commands on an unrelated machine. Keep
failure logs. A previous attempt exposed a daemon process-group termination
problem; foreground daemons now start in separate sessions. Earlier parser
format errors were corrected before the two recorded successful runs.
After collecting evidence, confirm the three owned daemons and map are absent,
issue poweroff in the guest, and confirm that the exact QEMU PID in vm.json has
exited. Discard the temporary VM files only when their ownership is confirmed.

Teaching exercise
Predict the number of sessions, disks and map paths after each transition.
Explain why two 64-MiB devices yield one 64-MiB map. Explain why exit zero with
an invalid-keyword diagnostic is insufficient configuration validation.
Separate a successful login from restored path aggregation. Write a short RUN
handover naming the tested versions, the evidence and missing acceptance work.
No human workshop or independent specialist review is claimed.
