fix loop dev

Signed-off-by: ale <ale@manalejandro.com>
2026-01-25 18:45:09 +01:00
commit 06841d5d53
--- a/25
+++ b/25
@@ -49,8 +49,29 @@ RUN chmod +x /app/sbin/woeusb
 # Add woeusb to PATH
 ENV PATH="/app/sbin:${PATH}"

-# Set the default user
-USER woeusb
+# Create entrypoint script to setup loop devices
+RUN echo '#!/bin/bash\n\
+set -e\n\
+# Create loop devices if they don'"'"'t exist (runs as root)\n\
+for i in {0..7}; do\n\
+  if [ ! -b /dev/loop$i ]; then\n\
+    mknod /dev/loop$i b 7 $i 2>/dev/null || true\n\
+  fi\n\
+done\n\
+# Switch to woeusb user if running interactive shell\n\
+if [ "$#" -eq 0 ] || [ "$1" = "/bin/bash" ]; then\n\
+  exec su - woeusb\n\
+else\n\
+  # Execute command as is (allows sudo usage)\n\
+  exec "$@"\n\
+fi\n' > /entrypoint.sh && \
+    chmod +x /entrypoint.sh
+
+# Don't set default user - entrypoint runs as root to create loop devices
+# USER woeusb
+
+# Set entrypoint
+ENTRYPOINT ["/entrypoint.sh"]

 # Default command
 CMD ["/bin/bash"]
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -2,6 +2,8 @@

 ## 🚀 Fastest Way to Get Started

+> **⚠️ Important**: WoeUSB requires root privileges and loop devices. The container automatically creates loop devices (`/dev/loop0-7`) on startup.
+
 ### Step 1: Prepare Everything
 ```bash
 # Create directories
@@ -96,6 +98,14 @@ sudo umount /dev/sdb*
 sudo woeusb --device /isos/windows.iso /dev/sdb
 ```

+### "Loop device not found"
+```bash
+# Loop devices are created automatically, but if needed:
+sudo mknod /dev/loop0 b 7 0
+# Or create all loop devices:
+for i in {0..7}; do sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true; done
+```
+
 ### Can't find USB device in container
 Edit `docker-compose.yml` and add your device:
 ```yaml
--- a/README.md
+++ b/README.md
@@ -10,6 +10,7 @@ A Docker containerized version of [WoeUSB](https://github.com/WoeUSB/WoeUSB) - A
 - [Usage](#-usage)
 - [Important Notes](#-important-notes)
 - [Troubleshooting](#-troubleshooting)
+- [Technical Notes](#-technical-notes)
 - [License](#-license)

 ## ✨ Features
@@ -36,6 +37,8 @@ A Docker containerized version of [WoeUSB](https://github.com/WoeUSB/WoeUSB) - A
 cd /path/to/docker-woeusb
 ```

+> **⚠️ Important**: WoeUSB requires loop devices and must be run as root inside the container. The setup automatically creates `/dev/loop0` through `/dev/loop7` devices when the container starts.
+
 ### 2. Create Required Directories

 ```bash
@@ -79,7 +82,21 @@ devices:
 docker-compose build
 ```

-### 7. Run the Container
+### 7. Verify Setup (Optional but Recommended)
+
+Run the verification script to ensure everything is configured correctly:
+
+```bash
+./verify-setup.sh
+```
+
+This will check:
+- Docker installation
+- Required files and directories
+- Loop device creation
+- Container functionality
+
+### 8. Run the Container

 ```bash
 docker-compose run --rm woeusb
@@ -143,7 +160,10 @@ ls -lh /isos
 # Check USB device
 lsblk

-# Create bootable USB
+# Verify loop devices exist (created automatically)
+ls -l /dev/loop*
+
+# Create bootable USB (must use sudo)
 sudo woeusb --device /isos/Windows10.iso /dev/sdb

 # Exit container when done
@@ -198,6 +218,22 @@ devices:
 docker-compose run --rm woeusb
 ```

+### Loop Device Not Found
+
+**Solution**: Loop devices are created automatically by the entrypoint script. If you still encounter issues, manually create them:
+
+```bash
+# Inside the container as root
+sudo mknod /dev/loop0 b 7 0
+sudo mknod /dev/loop1 b 7 1
+# ... up to loop7
+```
+
+Or create all at once:
+```bash
+for i in {0..7}; do sudo mknod /dev/loop$i b 7 $i 2>/dev/null || true; done
+```
+
 ### "Device is busy" Error

 **Solution**: Unmount the USB device first:
@@ -248,6 +284,10 @@ docker-woeusb/
 ├── Dockerfile              # Docker image definition
 ├── docker-compose.yml      # Docker Compose configuration
 ├── README.md              # This file
+├── QUICKSTART.md          # Quick start guide
+├── TECHNICAL_NOTES.md     # Detailed technical documentation
+├── woeusb-docker.sh       # Interactive helper script
+├── verify-setup.sh        # Setup verification script
 ├── WoeUSB/                # WoeUSB source files
 │   ├── sbin/
 │   │   └── woeusb        # Main WoeUSB script
--- a/TECHNICAL_NOTES.md
+++ b/TECHNICAL_NOTES.md
@@ -0,0 +1,246 @@
+# 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:
+
+```bash
+# 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:
+```bash
+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**:
+```bash
+# 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**:
+```bash
+# 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:
+
+```yaml
+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):
+
+```yaml
+environment:
+  - DD_BLOCK_SIZE=4194304
+```
+
+Larger values may improve performance on fast USB 3.0+ devices.
+
+## Docker Compose Configuration
+
+```yaml
+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](https://github.com/WoeUSB/WoeUSB)
+- [Linux Loop Devices](https://man7.org/linux/man-pages/man4/loop.4.html)
+- [Docker Privileged Mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities)
+- [UEFI:NTFS Project](https://github.com/pbatard/uefi-ntfs)
+
+---
+
+**Last Updated**: January 25, 2026
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -12,14 +12,14 @@ services:
    tty: true
    volumes:
      # Mount directory for Windows ISO files
-      - ./isos:/isos:ro
+      - ./isos:/isos
      # Mount directory for output/working files
      - ./output:/output
    devices:
      # This will require manual editing to add your specific USB device
      # Example: /dev/sdb, /dev/sdc, etc.
      # Uncomment and modify the following line:
-      # - /dev/sdb:/dev/sdb
+      - /dev/sdb:/dev/sdb
    environment:
      # Set RUFUS_UEFI_NTFS_VERSION if you need a specific version
      - RUFUS_UEFI_NTFS_VERSION=b30e3b387a3ca7a5e2fddebcc2c8f9538a89b868
--- a/verify-setup.sh
+++ b/verify-setup.sh
@@ -0,0 +1,295 @@
+#!/bin/bash
+# WoeUSB Docker Verification Script
+# Tests if the Docker setup is working correctly
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m'
+
+print_header() {
+    echo -e "${BLUE}==================================${NC}"
+    echo -e "${BLUE}  WoeUSB Docker Verification${NC}"
+    echo -e "${BLUE}==================================${NC}"
+    echo ""
+}
+
+print_test() {
+    echo -e "${YELLOW}[TEST]${NC} $1"
+}
+
+print_pass() {
+    echo -e "${GREEN}[PASS]${NC} $1"
+}
+
+print_fail() {
+    echo -e "${RED}[FAIL]${NC} $1"
+}
+
+print_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+check_docker() {
+    print_test "Checking if Docker is installed..."
+    if command -v docker &> /dev/null; then
+        DOCKER_VERSION=$(docker --version)
+        print_pass "Docker found: $DOCKER_VERSION"
+        return 0
+    else
+        print_fail "Docker is not installed"
+        return 1
+    fi
+}
+
+check_docker_compose() {
+    print_test "Checking if Docker Compose is installed..."
+    if docker compose version &> /dev/null; then
+        COMPOSE_VERSION=$(docker compose version)
+        print_pass "Docker Compose found: $COMPOSE_VERSION"
+        return 0
+    elif command -v docker-compose &> /dev/null; then
+        COMPOSE_VERSION=$(docker-compose --version)
+        print_pass "Docker Compose found: $COMPOSE_VERSION"
+        return 0
+    else
+        print_fail "Docker Compose is not installed"
+        return 1
+    fi
+}
+
+check_privileged() {
+    print_test "Checking if current user can run Docker..."
+    if docker ps &> /dev/null; then
+        print_pass "User can run Docker commands"
+        return 0
+    else
+        print_fail "User cannot run Docker (try: sudo usermod -aG docker $USER)"
+        return 1
+    fi
+}
+
+check_files() {
+    print_test "Checking if required files exist..."
+    local missing=0
+    
+    if [ ! -f "Dockerfile" ]; then
+        print_fail "Dockerfile not found"
+        missing=1
+    fi
+    
+    if [ ! -f "docker-compose.yml" ]; then
+        print_fail "docker-compose.yml not found"
+        missing=1
+    fi
+    
+    if [ ! -d "WoeUSB" ]; then
+        print_fail "WoeUSB directory not found"
+        missing=1
+    fi
+    
+    if [ ! -f "WoeUSB/sbin/woeusb" ]; then
+        print_fail "WoeUSB script not found"
+        missing=1
+    fi
+    
+    if [ $missing -eq 0 ]; then
+        print_pass "All required files present"
+        return 0
+    else
+        return 1
+    fi
+}
+
+check_directories() {
+    print_test "Checking if required directories exist..."
+    
+    if [ ! -d "isos" ]; then
+        mkdir -p isos
+        print_info "Created isos/ directory"
+    fi
+    
+    if [ ! -d "output" ]; then
+        mkdir -p output
+        print_info "Created output/ directory"
+    fi
+    
+    print_pass "Directory structure OK"
+    return 0
+}
+
+check_image() {
+    print_test "Checking if Docker image exists..."
+    if docker image inspect woeusb:latest &> /dev/null; then
+        print_pass "Docker image 'woeusb:latest' found"
+        return 0
+    else
+        print_info "Docker image not built yet (run: docker-compose build)"
+        return 1
+    fi
+}
+
+test_loop_devices() {
+    print_test "Testing loop device creation in container..."
+    
+    if ! docker image inspect woeusb:latest &> /dev/null; then
+        print_info "Skipping (image not built)"
+        return 1
+    fi
+    
+    # Test if container can create loop devices
+    if docker run --rm --privileged woeusb:latest \
+        /bin/bash -c "ls -l /dev/loop* 2>/dev/null | wc -l" &> /dev/null; then
+        local loop_count=$(docker run --rm --privileged woeusb:latest \
+            /bin/bash -c "ls -l /dev/loop* 2>/dev/null | wc -l")
+        if [ "$loop_count" -gt 0 ]; then
+            print_pass "Loop devices created successfully ($loop_count devices)"
+            return 0
+        else
+            print_fail "No loop devices found in container"
+            return 1
+        fi
+    else
+        print_fail "Could not test loop devices"
+        return 1
+    fi
+}
+
+test_woeusb_command() {
+    print_test "Testing if woeusb command is accessible..."
+    
+    if ! docker image inspect woeusb:latest &> /dev/null; then
+        print_info "Skipping (image not built)"
+        return 1
+    fi
+    
+    if docker run --rm woeusb:latest \
+        /bin/bash -c "which woeusb" &> /dev/null; then
+        print_pass "woeusb command found in PATH"
+        return 0
+    else
+        print_fail "woeusb command not found"
+        return 1
+    fi
+}
+
+test_sudo_access() {
+    print_test "Testing sudo access in container..."
+    
+    if ! docker image inspect woeusb:latest &> /dev/null; then
+        print_info "Skipping (image not built)"
+        return 1
+    fi
+    
+    if docker run --rm woeusb:latest \
+        /bin/bash -c "sudo echo 'test'" &> /dev/null; then
+        print_pass "sudo works in container"
+        return 0
+    else
+        print_fail "sudo does not work in container"
+        return 1
+    fi
+}
+
+check_usb_devices() {
+    print_test "Checking for USB devices on host..."
+    
+    local usb_devices=$(lsblk -d -o NAME,TYPE | grep disk | grep -v "loop\|ram" | wc -l)
+    
+    if [ "$usb_devices" -gt 0 ]; then
+        print_pass "Found $usb_devices block device(s)"
+        print_info "Available devices:"
+        lsblk -o NAME,SIZE,TYPE,MOUNTPOINT,VENDOR,MODEL | grep -E "disk|NAME" | grep -v "loop\|ram"
+        return 0
+    else
+        print_info "No external block devices found"
+        return 1
+    fi
+}
+
+check_iso_files() {
+    print_test "Checking for ISO files..."
+    
+    if [ -n "$(ls -A isos/*.iso 2>/dev/null)" ]; then
+        local iso_count=$(ls -1 isos/*.iso 2>/dev/null | wc -l)
+        print_pass "Found $iso_count ISO file(s):"
+        ls -lh isos/*.iso
+        return 0
+    else
+        print_info "No ISO files found in isos/ directory"
+        print_info "Copy your Windows ISO with: cp /path/to/windows.iso isos/"
+        return 1
+    fi
+}
+
+print_summary() {
+    echo ""
+    echo -e "${BLUE}==================================${NC}"
+    echo -e "${BLUE}  Summary${NC}"
+    echo -e "${BLUE}==================================${NC}"
+    echo ""
+    
+    if [ $1 -eq 0 ]; then
+        echo -e "${GREEN}✓ All critical checks passed!${NC}"
+        echo ""
+        echo "Next steps:"
+        echo "1. Copy your Windows ISO to isos/ directory"
+        echo "2. Identify your USB device with: lsblk"
+        echo "3. Run: ./woeusb-docker.sh"
+    else
+        echo -e "${RED}✗ Some checks failed${NC}"
+        echo ""
+        echo "Please fix the issues above before proceeding."
+    fi
+    echo ""
+}
+
+# Main execution
+main() {
+    print_header
+    
+    local failed=0
+    
+    check_docker || failed=1
+    echo ""
+    
+    check_docker_compose || failed=1
+    echo ""
+    
+    check_privileged || failed=1
+    echo ""
+    
+    check_files || failed=1
+    echo ""
+    
+    check_directories || failed=1
+    echo ""
+    
+    check_image
+    echo ""
+    
+    test_loop_devices
+    echo ""
+    
+    test_woeusb_command
+    echo ""
+    
+    test_sudo_access
+    echo ""
+    
+    check_usb_devices
+    echo ""
+    
+    check_iso_files
+    echo ""
+    
+    print_summary $failed
+    
+    exit $failed
+}
+
+main
--- a/woeusb-docker.sh
+++ b/woeusb-docker.sh
@@ -99,6 +99,7 @@ run_woeusb() {
    print_info "ISO: $iso_name"
    print_info "Device: $device"
    print_info "Filesystem: $filesystem"
+    print_info "Note: Loop devices (/dev/loop*) will be created automatically"
    echo ""
    
    docker run -it --rm --privileged \
@@ -106,7 +107,7 @@ run_woeusb() {
        -v "$(pwd)/output:/output" \
        --device="$device:$device" \
        woeusb:latest \
-        sudo woeusb --device --target-filesystem "$filesystem" "/isos/$iso_name" "$device"
+        /bin/bash -c "sudo woeusb --device --target-filesystem $filesystem /isos/$iso_name $device"
    
    print_success "Process completed!"
 }