Virtual Unraid
Complete guide to creating a virtual Unraid server within an existing Unraid host system for testing and development purposes.
Video [IBRACORP Video Tutorial - Coming Soon]
Useful Links
Related Videos
- Unraid Server Setup
- Virtual Machine Management
- Storage Configuration
⚠️ 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.
Thank you for choosing to collaborate with IBRACORP 🙏
Please read our disclaimer https://docs.ibracorp.io/disclaimer
Credits
Role | Contributor |
---|---|
Writer / Producer | DiscDuck |
Video Recording and Voice | Sycotix |
Contributor | Hawks |
Testing / Proofreading | North, 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
- Download Unraid: Get latest version from unraid.net
- Format USB Stick: Use FAT32 file system
- Extract Unraid Files: Extract downloaded ZIP to USB root
Modify Boot Configuration
Edit syslinux.cfg
- Navigate to USB: Open USB drive in file explorer
- Open syslinux folder: Find syslinux.cfg file
- 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
-
Run make_bootable script:
- Windows: Run
make_bootable.bat
as administrator - Linux/Mac: Run
make_bootable_linux
ormake_bootable_mac
- Windows: Run
-
Alternative Method (Windows):
# From syslinux folder on USB
syslinux.exe -m -a -d /syslinux /dev/USB_DRIVE
Configure License
License Setup Options
- New License: Purchase separate license for virtual instance
- Trial Mode: Use 30-day trial for testing
- 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
- Enable VMs: Settings → VM Manager → Enable VMs
- Check IOMMU: Verify IOMMU groups are available
- VM Storage: Create or select storage location for VMs
Create Virtual Machine
VM Configuration
-
Add VM: Click "Add VM" in VM Manager
-
Select Template: Choose "Linux" template
-
Basic Configuration:
Name: Virtual-Unraid
Description: Virtual Unraid for testing
Template: Slackware (closest to Unraid) -
CPU Configuration:
CPUs: 2-4 cores
CPU Model: Host passthrough (recommended)
CPU Pinning: Optional for better performance -
Memory Configuration:
Initial Memory: 4096 MB (minimum)
Max Memory: 8192 MB (recommended) -
Machine Configuration:
BIOS: UEFI (recommended)
Machine: q35
Storage Configuration
Virtual Disk Setup
-
Primary vDisk:
Bus: VirtIO
Cache: Writeback
Format: qcow2
Size: 50GB (minimum) -
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
- USB Devices Section: In VM template
- Add USB Device: Select your prepared Unraid USB
- USB Controller: xHCI (USB 3.0)
VM Boot and Installation
First Boot
Initial Startup
- Start VM: Click start button
- VNC Console: Open VNC viewer
- Boot Menu: Select Unraid boot option
- Wait for Boot: Allow Unraid to fully load
Initial Configuration
Network Setup
- Check IP Assignment: Note assigned IP address
- Access Web Interface: Open browser to VM's IP
- Network Configuration:
Interface: eth0
IP Assignment: DHCP (initial)
Static IP: Configure later if needed
Array Configuration
Set Up Virtual Array
-
Assign Devices:
Parity: Largest virtual disk
Disk 1: First data virtual disk
Disk 2: Second data virtual disk
Cache: Optional SSD simulation -
Format Array: Initialize new array
-
Start Array: Begin array operation
Advanced Configuration
Static IP Configuration
Network Settings
-
Settings → Network: In virtual Unraid
-
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 -
Apply Changes: Restart networking
Performance Optimization
VM Performance Tuning
- CPU Pinning: Pin VM CPUs to specific host cores
- Memory Allocation: Use hugepages for better performance
- Storage Optimization: Use VirtIO drivers
- 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
-
Settings → Management Access: Enable SSH
-
SSH Configuration:
SSH Port: 22 (default)
Password Authentication: Enabled
Root Login: Enabled (for testing) -
Connect via SSH:
ssh root@virtual-unraid-ip
Troubleshooting
Common Boot Issues
EFI Boot Problems
- BIOS vs UEFI: Ensure consistent boot mode
- Boot Order: Check VM boot priority
- 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
- DHCP Issues: Check host DHCP server
- Bridge Configuration: Verify br0 bridge
- 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
- CPU Allocation: Increase CPU cores
- Memory: Add more RAM to VM
- Storage: Use SSD for VM storage
- VirtIO Drivers: Ensure VirtIO drivers loaded
USB Passthrough Issues
USB Not Detected
- USB Controller Type: Try different USB controller
- Host USB Policy: Check host USB settings
- 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:
- Edit VM Template: Go to VM tab
- Form View → XML View: Switch to XML editing
- 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
- Plugin Development: Test custom plugins safely
- Docker Configuration: Test container setups
- Network Changes: Test network configurations
- Storage Testing: Test different array configurations
Learning Environment
Educational Purposes
- Unraid Training: Learn without affecting production
- Disaster Recovery: Practice recovery procedures
- Configuration Testing: Test settings changes
- Version Testing: Test new Unraid versions
Backup Strategy Testing
Disaster Recovery
- Backup Procedures: Test backup and restore
- Migration Testing: Test hardware migrations
- Recovery Scenarios: Practice disaster recovery
- Configuration Backup: Test config preservation
Security Considerations
Network Isolation
Security Best Practices
- Separate Network: Use isolated network segment
- Firewall Rules: Restrict VM network access
- Access Control: Limit SSH and web access
- License Management: Keep licenses separate
Data Protection
Safety Measures
- Host Isolation: Prevent VM from affecting host
- Storage Separation: Keep VM storage separate
- Backup Strategy: Regular VM backups
- Snapshot Management: Use VM snapshots for testing
Best Practices
Resource Management
Efficient Resource Usage
- CPU Allocation: Don't over-allocate CPUs
- Memory Management: Leave sufficient RAM for host
- Storage Planning: Plan storage allocation carefully
- Network Bandwidth: Monitor network usage
Maintenance
Regular Maintenance Tasks
- VM Updates: Keep virtual Unraid updated
- Host Maintenance: Maintain host Unraid system
- Backup Verification: Verify VM backups regularly
- Performance Monitoring: Monitor VM performance
Documentation
Keep Records
- Configuration Documentation: Document VM settings
- Change Log: Track configuration changes
- Troubleshooting Notes: Document solutions
- 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:
- Liking and Subscribing to our Youtube channel
- Joining our Discord server
- Becoming a paid member on our IBRACORP website
- Donating via Paypal
Thank you for being part of our community!