docker-woeusb/TECHNICAL_NOTES.md

Technical Notes - WoeUSB Docker

Loop Devices Requirement

WoeUSB requires loop devices (/dev/loop*) to mount and manipulate disk images. These devices are essential for the tool to function properly.

What are Loop Devices?

Loop devices are pseudo-devices that make files accessible as block devices. WoeUSB uses them to:

• Mount ISO images
• Create filesystem structures
• Copy Windows installation files

Automatic Creation

The Docker container automatically creates loop devices (/dev/loop0 through /dev/loop7) when it starts via the entrypoint script.

Manual Creation (If Needed)

If you need to manually create loop devices:

# Create a single loop device
sudo mknod /dev/loop0 b 7 0

# Create all loop devices (0-7)
for i in {0..7}; do
    sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true
done

Device Parameters

The mknod command syntax:

mknod /dev/loop<N> b 7 <N>

• /dev/loop<N> - Device path
• b - Block device type
• 7 - Major number (loop devices)
• <N> - Minor number (0-7)

Root Privileges

WoeUSB must run with root privileges because it needs to:

1. Create filesystem structures on USB devices
2. Partition disks and modify partition tables
3. Mount/unmount filesystems
4. Access raw block devices
5. Create loop devices with mknod

Container Root Execution

The container runs as root by default to:

• Create loop devices on startup via entrypoint
• Allow unrestricted device access
• Enable all filesystem operations

The container switches to the woeusb user for interactive shells, but maintains sudo access for WoeUSB execution.

Privileged Mode

The container runs in privileged mode (--privileged) to:

• Access host system devices (/dev/sdb, etc.)
• Create device nodes with mknod
• Perform low-level disk operations
• Mount filesystems

Security Note

Privileged containers have elevated access. Only run this container:

• On trusted systems
• With verified ISO files
• With correct target device identification

Filesystem Considerations

FAT32 Limitations

• Maximum file size: 4GB
• Some Windows installation images have install.wim > 4GB
• WoeUSB automatically splits large WIM files using wimlib

NTFS Support

• No file size limitations
• Requires UEFI:NTFS bootloader (automatically downloaded)
• Slightly less compatible with older systems

Device Mounting

The container mounts:

• /isos - Read-only ISO storage
• /output - Optional output directory
• USB devices via --device parameter

Troubleshooting

Loop Device Errors

Error: "Could not find loop device"

Solution:

# Inside container
for i in {0..7}; do sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true; done

Permission Errors

Error: "Permission denied" or "Operation not permitted"

Solutions:

1. Ensure container runs in privileged mode
2. Use sudo for woeusb commands
3. Check USB device is properly mounted

Device Busy Errors

Error: "Device is busy"

Solutions:

# On host system before starting container
sudo umount /dev/sdb* 2>/dev/null || true

# Inside container
sudo fuser -km /dev/sdb  # Kill processes using device

Environment Variables

RUFUS_UEFI_NTFS_VERSION

Controls which version of UEFI:NTFS bootloader to download:

environment:
  - RUFUS_UEFI_NTFS_VERSION=b30e3b387a3ca7a5e2fddebcc2c8f9538a89b868

Default is a tested stable version. Only change if you need a specific release.

DD_BLOCK_SIZE

Controls block size for dd operations (default: 4MiB):

environment:
  - DD_BLOCK_SIZE=4194304

Larger values may improve performance on fast USB 3.0+ devices.

Docker Compose Configuration

services:
  woeusb:
    privileged: true          # Required for device access
    devices:
      - /dev/sdb:/dev/sdb     # USB device passthrough
    volumes:
      - ./isos:/isos:ro       # Read-only ISO mount
      - ./output:/output       # Output directory

Why Privileged Mode?

Docker's --privileged flag is required because:

1. Standard containers cannot create device nodes
2. WoeUSB needs raw device access
3. Loop devices must be created dynamically
4. Partition table operations require elevated privileges

Build Process

The Dockerfile:

1. Uses Ubuntu 22.04 LTS base
2. Installs all WoeUSB dependencies
3. Creates non-root woeusb user
4. Configures passwordless sudo
5. Creates entrypoint script for loop devices
6. Sets up PATH for woeusb command

Performance Considerations

USB Speed Impact

Expected creation times:

• USB 2.0: 20-40 minutes (12 MB/s)
• USB 3.0: 10-20 minutes (60 MB/s)
• USB 3.1 Gen2: 5-15 minutes (120+ MB/s)

ISO Size Impact

• Windows 7: ~3-4 GB
• Windows 10: ~4-6 GB
• Windows 11: ~5-7 GB

Larger ISOs take proportionally longer to write.

Optimization Tips

1. Use USB 3.0+ devices when possible
2. Use NTFS for ISOs with large files (skips WIM splitting)
3. Keep ISO files on fast storage (SSD)
4. Ensure USB port is USB 3.0+

Compatibility

Supported Host Systems

• Ubuntu 18.04+
• Debian 10+
• Fedora 32+
• Any Linux with Docker 20.10+

Supported Windows Versions

• Windows Vista
• Windows 7, 8, 8.1
• Windows 10 (all builds)
• Windows 11 (all builds)
• Windows Server editions
• Windows PE

UEFI vs Legacy Boot

The created USB supports both:

• Legacy BIOS (MBR boot)
• UEFI (GPT boot with UEFI:NTFS)

References

• WoeUSB GitHub
• Linux Loop Devices
• Docker Privileged Mode
• UEFI:NTFS Project

---

Last Updated: January 25, 2026