Skip to main content

Virtual Unraid

Complete guide to creating a virtual Unraid server within an existing Unraid host system for testing and development purposes.

Virtual Unraid Server

Video [IBRACORP Video Tutorial - Coming Soon]

Useful Links

Related Videos

  • Unraid Server Setup
  • Virtual Machine Management
  • Storage Configuration
Important Warnings

⚠️ Data Loss Risk

Creating a virtual Unraid server involves advanced configurations that can potentially cause:

  • Data loss if misconfigured
  • System instability on the host
  • License conflicts between host and guest

Before proceeding:

  • Backup all important data
  • Have recovery plans ready
  • Test in non-production environment first
  • Understand the risks involved

This guide is intended for testing and development purposes only.

Disclaimer

Thank you for choosing to collaborate with IBRACORP 🙏

Please read our disclaimer https://docs.ibracorp.io/disclaimer

Credits

RoleContributor
Writer / ProducerDiscDuck
Video Recording and VoiceSycotix
ContributorHawks
Testing / ProofreadingNorth, Sycotix

Feature List

Virtual Unraid Capabilities

  • Full Unraid Experience within a virtual machine
  • Testing Environment for new configurations
  • Development Platform for plugin and Docker testing
  • Backup Unraid Instance for disaster recovery testing
  • Learning Environment without affecting production
  • License Testing before hardware migration
  • Container Development and testing platform
  • Storage Array Simulation for planning
  • Plugin Development environment
  • Docker Application Testing without main server impact

Prerequisites

Host System Requirements

  • Unraid 6.9.2 or later on host system
  • Hardware Virtualization enabled in BIOS/UEFI
  • IOMMU/VT-d support enabled
  • Sufficient RAM: 8GB+ for host, 4GB+ for virtual Unraid
  • CPU cores: At least 4 cores (2 for host, 2 for VM)
  • Storage space: 50GB+ for virtual Unraid
  • Spare USB stick: For virtual Unraid license
  • Valid Unraid license: Basic, Plus, or Pro

Knowledge Requirements

  • Basic understanding of Unraid
  • VM management experience
  • USB preparation skills
  • Network configuration knowledge

USB Preparation

Prepare Virtual Unraid USB

Download and Prepare Unraid

  1. Download Unraid: Get latest version from unraid.net
  2. Format USB Stick: Use FAT32 file system
  3. Extract Unraid Files: Extract downloaded ZIP to USB root

Modify Boot Configuration

Edit syslinux.cfg

  1. Navigate to USB: Open USB drive in file explorer
  2. Open syslinux folder: Find syslinux.cfg file
  3. Edit Configuration: Open in text editor

Add Custom Boot Parameters:

# Original append line (example):
append initrd=/bzroot

# Modified append line for virtual environment:
append initrd=/bzroot pcie_acs_override=downstream,multifunction vfio-pci.ids=

Alternative Boot Menu Entry:

label Unraid OS (Virtual)
menu default
kernel /bzimage
append initrd=/bzroot pcie_acs_override=downstream,multifunction acpi=off

Make USB Bootable

Install Bootloader

  1. Run make_bootable script:

    • Windows: Run make_bootable.bat as administrator
    • Linux/Mac: Run make_bootable_linux or make_bootable_mac
  2. Alternative Method (Windows):

    # From syslinux folder on USB
    syslinux.exe -m -a -d /syslinux /dev/USB_DRIVE

Configure License

License Setup Options

  1. New License: Purchase separate license for virtual instance
  2. Trial Mode: Use 30-day trial for testing
  3. Existing License: Transfer temporarily (requires USB swap)

GUID Configuration:

# Check USB GUID (on Linux/Mac)
lsusb

# Set specific GUID in config (if needed)
echo "GUID=YOUR_USB_GUID" >> config/ident.cfg

VM Creation on Host Unraid

Enable Virtualization

Host Unraid Configuration

  1. Enable VMs: Settings → VM Manager → Enable VMs
  2. Check IOMMU: Verify IOMMU groups are available
  3. VM Storage: Create or select storage location for VMs

Create Virtual Machine

VM Configuration

  1. Add VM: Click "Add VM" in VM Manager

  2. Select Template: Choose "Linux" template

  3. Basic Configuration:

    Name: Virtual-Unraid
    Description: Virtual Unraid for testing
    Template: Slackware (closest to Unraid)
  4. CPU Configuration:

    CPUs: 2-4 cores
    CPU Model: Host passthrough (recommended)
    CPU Pinning: Optional for better performance
  5. Memory Configuration:

    Initial Memory: 4096 MB (minimum)
    Max Memory: 8192 MB (recommended)
  6. Machine Configuration:

    BIOS: UEFI (recommended)
    Machine: q35

Storage Configuration

Virtual Disk Setup

  1. Primary vDisk:

    Bus: VirtIO
    Cache: Writeback
    Format: qcow2
    Size: 50GB (minimum)
  2. Additional vDisks (for array simulation):

    vDisk 2: 20GB (Parity simulation)
    vDisk 3: 10GB (Data disk 1)
    vDisk 4: 10GB (Data disk 2)
    vDisk 5: 10GB (Data disk 3)

Network Configuration

Network Setup

Network Source: br0
Network Model: VirtIO-net
MAC Address: Auto-generate

USB Passthrough

Attach Unraid USB

  1. USB Devices Section: In VM template
  2. Add USB Device: Select your prepared Unraid USB
  3. USB Controller: xHCI (USB 3.0)

VM Boot and Installation

First Boot

Initial Startup

  1. Start VM: Click start button
  2. VNC Console: Open VNC viewer
  3. Boot Menu: Select Unraid boot option
  4. Wait for Boot: Allow Unraid to fully load

Initial Configuration

Network Setup

  1. Check IP Assignment: Note assigned IP address
  2. Access Web Interface: Open browser to VM's IP
  3. Network Configuration:
    Interface: eth0
    IP Assignment: DHCP (initial)
    Static IP: Configure later if needed

Array Configuration

Set Up Virtual Array

  1. Assign Devices:

    Parity: Largest virtual disk
    Disk 1: First data virtual disk
    Disk 2: Second data virtual disk
    Cache: Optional SSD simulation
  2. Format Array: Initialize new array

  3. Start Array: Begin array operation

Advanced Configuration

Static IP Configuration

Network Settings

  1. Settings → Network: In virtual Unraid

  2. Interface Configuration:

    Interface: eth0
    IP Address: 192.168.1.150/24
    Gateway: 192.168.1.1
    DNS Servers: 8.8.8.8, 1.1.1.1
  3. Apply Changes: Restart networking

Performance Optimization

VM Performance Tuning

  1. CPU Pinning: Pin VM CPUs to specific host cores
  2. Memory Allocation: Use hugepages for better performance
  3. Storage Optimization: Use VirtIO drivers
  4. Network Optimization: Enable VirtIO-net multiqueue

Host Configuration:

<!-- Add to VM XML configuration -->
<vcpu placement='static' cpuset='2-3'>2</vcpu>
<cputune>
<vcpupin vcpu='0' cpuset='2'/>
<vcpupin vcpu='1' cpuset='3'/>
</cputune>

SSH Access Configuration

Enable SSH in Virtual Unraid

  1. Settings → Management Access: Enable SSH

  2. SSH Configuration:

    SSH Port: 22 (default)
    Password Authentication: Enabled
    Root Login: Enabled (for testing)
  3. Connect via SSH:

    ssh root@virtual-unraid-ip

Troubleshooting

Common Boot Issues

EFI Boot Problems

  1. BIOS vs UEFI: Ensure consistent boot mode
  2. Boot Order: Check VM boot priority
  3. USB Detection: Verify USB passthrough working

Solutions:

# Force legacy boot in VM template
<os>
<type arch='x86_64' machine='pc-q35-2.11'>hvm</type>
<loader>/usr/share/qemu/bios.bin</loader>
</os>

Network Issues

IP Address Problems

  1. DHCP Issues: Check host DHCP server
  2. Bridge Configuration: Verify br0 bridge
  3. VM Network Model: Try different network models

Manual IP Configuration:

# From Unraid console
ifconfig eth0 192.168.1.150 netmask 255.255.255.0
route add default gw 192.168.1.1

Performance Issues

Slow Performance

  1. CPU Allocation: Increase CPU cores
  2. Memory: Add more RAM to VM
  3. Storage: Use SSD for VM storage
  4. VirtIO Drivers: Ensure VirtIO drivers loaded

USB Passthrough Issues

USB Not Detected

  1. USB Controller Type: Try different USB controller
  2. Host USB Policy: Check host USB settings
  3. VM Template: Verify USB device mapping

Alternative USB Methods:

<!-- USB device passthrough by vendor/product ID -->
<hostdev mode='subsystem' type='usb' managed='yes'>
<source>
<vendor id='0x1234'/>
<product id='0x5678'/>
</source>
</hostdev>

Manual XML Configuration

Advanced VM Template

Custom XML Configuration

If VM template editor doesn't provide needed options:

  1. Edit VM Template: Go to VM tab
  2. Form View → XML View: Switch to XML editing
  3. Custom Configuration: Add advanced options

Example XML Modifications:

<domain type='kvm'>
<name>Virtual-Unraid</name>
<memory unit='KiB'>4194304</memory>
<vcpu placement='static'>2</vcpu>
<os>
<type arch='x86_64' machine='pc-q35-6.2'>hvm</type>
<loader readonly='yes' type='pflash'>/usr/share/qemu/edk2-x86_64-secure-code.fd</loader>
<nvram>/etc/libvirt/qemu/nvram/Virtual-Unraid_VARS.fd</nvram>
</os>
<features>
<acpi/>
<apic/>
<hyperv>
<relaxed state='on'/>
<vapic state='on'/>
<spinlocks state='on' retries='8191'/>
</hyperv>
</features>
<cpu mode='host-passthrough' check='none'>
<topology sockets='1' cores='2' threads='1'/>
</cpu>
<devices>
<!-- Custom device configurations -->
</devices>
</domain>

Use Cases and Applications

Testing Environment

Development Testing

  1. Plugin Development: Test custom plugins safely
  2. Docker Configuration: Test container setups
  3. Network Changes: Test network configurations
  4. Storage Testing: Test different array configurations

Learning Environment

Educational Purposes

  1. Unraid Training: Learn without affecting production
  2. Disaster Recovery: Practice recovery procedures
  3. Configuration Testing: Test settings changes
  4. Version Testing: Test new Unraid versions

Backup Strategy Testing

Disaster Recovery

  1. Backup Procedures: Test backup and restore
  2. Migration Testing: Test hardware migrations
  3. Recovery Scenarios: Practice disaster recovery
  4. Configuration Backup: Test config preservation

Security Considerations

Network Isolation

Security Best Practices

  1. Separate Network: Use isolated network segment
  2. Firewall Rules: Restrict VM network access
  3. Access Control: Limit SSH and web access
  4. License Management: Keep licenses separate

Data Protection

Safety Measures

  1. Host Isolation: Prevent VM from affecting host
  2. Storage Separation: Keep VM storage separate
  3. Backup Strategy: Regular VM backups
  4. Snapshot Management: Use VM snapshots for testing

Best Practices

Resource Management

Efficient Resource Usage

  1. CPU Allocation: Don't over-allocate CPUs
  2. Memory Management: Leave sufficient RAM for host
  3. Storage Planning: Plan storage allocation carefully
  4. Network Bandwidth: Monitor network usage

Maintenance

Regular Maintenance Tasks

  1. VM Updates: Keep virtual Unraid updated
  2. Host Maintenance: Maintain host Unraid system
  3. Backup Verification: Verify VM backups regularly
  4. Performance Monitoring: Monitor VM performance

Documentation

Keep Records

  1. Configuration Documentation: Document VM settings
  2. Change Log: Track configuration changes
  3. Troubleshooting Notes: Document solutions
  4. Recovery Procedures: Document recovery steps

Special Thanks

  • Lime Technology for creating Unraid
  • DiscDuck for developing this virtualization method
  • Hawks for extensive testing and feedback
  • To our fantastic Discord community for their input and support

Please support the developers and creators involved in this work to help show them some love. ❤️

Final Words

This guide was conceptualized and written by DiscDuck for IBRACORP, with contributions from the entire team.

Support Us

Our work sometimes takes months to research and develop.

If you want to help support us please consider:

Thank you for being part of our community!