Debian Unattended USB

Turn a USB stick into a guarded, one-key Debian server installer.

The Windows builder downloads Debian's current stable amd64 netinst image, verifies its official SHA-512 checksum, adds an unattended installation payload, writes a UEFI-bootable FAT32 USB, and verifies the copied files. On the target computer, nothing is erased until a person explicitly chooses YES and exactly one internal disk passes the configured model-and-size guard.

Caution

This project intentionally erases disks. Read the target guard shown by the builder and boot menu. A typo in broad matching values can destroy the wrong disk.

Why this exists

Routine Debian server installs should be repeatable without making disk selection casual. This project combines automation with deliberate stop points:

official Debian ISO -> SHA-512 verification -> guarded USB write
       -> no-timeout Y/N boot menu -> exact target match -> GPT + LVM install

The generated installer:

• tracks Debian's current stable amd64 netinst image instead of bundling an ISO;
• boots in UEFI mode with Secure Boot disabled;
• defaults to NO and waits forever for a Y/N decision;
• requires exactly one non-USB target matching a model substring and size range;
• installs a headless Debian system with GPT, an EFI System Partition, /boot, and LVM;
• installs SSH, standard utilities, build tools, Python, Git, tmux, htop, and unattended upgrades;
• applies all available package updates during installation;
• creates a named administrator with an Ed25519 SSH key and passwordless sudo;
• disables root login and SSH password authentication;
• clears old USB logs at the beginning of each confirmed attempt;
• keeps installer diagnostics on the USB and offers safe retry/restart choices;
• removes the customized initrd from the USB after a successful install, then powers off.

Requirements

• Windows 10 or 11
• Windows PowerShell 5.1 or newer, opened as Administrator
• A 2 GB or larger USB drive
• A 64-bit x86 target computer with UEFI firmware and wired internet access
• Secure Boot disabled on the target computer
• An Ed25519 SSH public key (*.pub), never the private key
• The target disk's model text and a narrow decimal-GB size range

The builder itself only supports Windows because it uses Get-Disk, Clear-Disk, and Format-Volume to guard and prepare the USB.

Quick start

Clone the repository:

git clone https://github.com/devilsnerve/debian-unattended-usb.git
cd debian-unattended-usb

Open PowerShell as Administrator and inspect the connected disks:

Get-Disk | Format-Table Number, FriendlyName, SerialNumber, BusType, Size

Then run the builder. Every value below is an example—replace the USB number and target guard with values for your hardware:

.\New-DebianUnattendedUsb.ps1 `
  -UsbDiskNumber 3 `
  -SshPublicKeyPath "$env:USERPROFILE\.ssh\id_ed25519.pub" `
  -TargetDiskModel "Samsung SSD" `
  -TargetDiskMinGB 450 `
  -TargetDiskMaxGB 550 `
  -Hostname "debian-node" `
  -AdminUser "admin"

The script displays the selected USB and target guard, then asks one destructive confirmation question. Only Y continues. The USB identity is checked again immediately before it is erased.

By default, a random console password is generated and saved privately under your Windows Downloads directory. To choose one interactively instead:

$password = Read-Host "Console password" -AsSecureString

.\New-DebianUnattendedUsb.ps1 `
  -UsbDiskNumber 3 `
  -SshPublicKeyPath "$env:USERPROFILE\.ssh\id_ed25519.pub" `
  -TargetDiskModel "Samsung SSD" `
  -TargetDiskMinGB 450 `
  -TargetDiskMaxGB 550 `
  -AdminPassword $password

Install Debian

1. Insert the completed USB into the target computer.
2. In firmware settings, enable UEFI boot and disable Secure Boot.
3. Choose the UEFI entry for the USB.
4. Review the GRUB menu. It has no countdown and selects NO by default.
5. Press Y only when you are ready to erase the guarded target disk.
6. Wait for the computer to power off.
7. Remove the USB and power the computer back on.

Connect using the private half of the public key supplied to the builder:

ssh admin@debian-node.local

If .local name resolution is unavailable, use the machine's IP address. To open a root shell after connecting:

sudo -i

There is no direct root password by design.

Target guard

The installer enumerates Linux block devices and accepts a target only when all conditions match:

Check	Required result
Boot mode	UEFI
Device path	Not USB
Removable flag	0
Model	Contains TargetDiskModel literally
Size	Between TargetDiskMinGB and TargetDiskMaxGB
Match count	Exactly one disk
Boot choice	Explicit Y
USB state	Armed or explicitly retried; not completed

Use a specific model substring and a tight size range. Do not use a generic value such as SSD when multiple internal drives could match.

Logs and recovery

The installer updates these files on the USB while it runs:

• AUTO_INSTALL_STATUS.txt
• AUTO_HOOK.log
• AUTO_SYSLOG.log
• AUTO_PARTMAN.log
• AUTO_INSTALL_FAILURE.log after an early guarded-hook failure

Old attempt logs are removed only after the target and USB state have been authorized. If a run is interrupted, boot the USB again and choose YES to retry or R to restart. After success, INSTALL_COMPLETE locks out another installation.

Installer logs can contain hardware identifiers, network addresses, and hostnames. Review them before attaching them to a public issue.

See Troubleshooting for boot, storage, login, and SSH problems.

Security notes

• The repository contains no SSH key, password, ISO, or built installer image.
• Your public key and console password are placed in the customized initrd on the generated USB. Keep an unused or failed USB private. A successful installation deletes that customized initrd.
• SSH accepts keys only. Direct root login and SSH password login are disabled.
• The administrator receives passwordless sudo. This is convenient for unattended servers but gives any process running as that user a direct path to root.
• The installed LVM layout is not encrypted. Full-disk encryption conflicts with a fully unattended boot unless a separate key-release design is added.
• SHA-512 verification detects a corrupted or mismatched ISO. For stronger provenance checking, independently verify Debian's signed checksum manifest.

Contributing

Disk-erasing code deserves unusually careful review. Read CONTRIBUTING.md before proposing a change, and include the failure behavior for every modification to a disk guard or installer hook.

License

Released under the MIT License.

Debian is a trademark of Software in the Public Interest, Inc. This project is independent and is not an official Debian installer image.

If this project saves you a manual reinstall, consider starring it and sharing the hardware you successfully tested.