Guide - How to install an unRAID VM on an unRAID host


Recommended Posts

If you prefer to get your information via video, check out this guide by IBRACORP: 
It follows pretty closely with mine below, but they also show how to take advantage of the USB Manager plugin so your VM flash drive can be the same brand as your host flash drive.





This guide will help you install unRAID in a VM on an unRAID host. This can be useful if you want to test the functionality of new versions before upgrading your main system, or if you need to develop plugins that work across versions. Limetech does not officially support running unRAID in a VM, so this should not be used for production data.


Note that you will need a valid license key for the unRAID VM. And since Unraid licensing is tied to a physical USB flash drive, you cannot boot the VM from an img file. Also, the VM's flash drive has to be a different manufacturer than the host's flash drive.

A note on versions

To run unRAID 6.4.0-rc5 or greater in a VM

The guide below works if you want to run unRAID 6.4.0-rc5 or greater in a VM. This version added the ability to boot via EFI, which means the VM can boot directly from a flash drive instead of a vdisk. The guide assumes the host is running 6.3.5, but other versions will likely work as well.


To run unRAID 6.2.0-rc1 to 6.4.0-rc4 in a VM
Starting with 6.2.0-rc1, it became possible to change the label of the flash drive to something other than "UNRAID", which means we no longer have to pass an entire USB controller through to the VM. See these instructions.


To run anything(?) older than 6.2.0-rc1 in a VM
See this excellent blog post by CHBMB on the Linuxserver.IO team. This pioneered the process of running unRAID in a VM under unRAID.

Let's Begin


Prepare the host system (if it is older than 6.4.0-rc10b)

  • Create a folder on your hosts' flash drive to store an image file. We'll use "custom" in this example.
  • Download this image file and place in flash\custom as "unraid.png"
  • Add this line to your flash\config\go file:
cp /boot/custom/unraid.png /usr/local/emhttp/plugins/dynamix.vm.manager/templates/images
  • We'll reboot the host in the next section, so that line will run on startup.
  • Note that starting with 6.4.0-rc10b, unRAID includes this icon by default. When you upgrade the host to 6.4.0-rc10b or higher, you'll want to remove that line from your go script and delete the image file from your flash drive.
  • Also note - this thread by SpaceInvaderOne documents an alternate method of getting additional icons for VMs


Prepare the flash drive for the VM

  • On your Windows or Mac desktop, use the unRAID USB creator tool to create your flash drive (or see the manual instructions in the next post)
    • Note that the VM's flash drive has to be a different manufacturer than the host's flash drive.
    • If your main system is named "Tower", be sure to specify a different name for the VM. Perhaps "TowerVM".
    • Click the option to "Allow EFI boot"
    • Write the image to the VM's flash drive
  • Make a few edits
    • Change the label of the flash drive from "UNRAID" to "UNRAID-VM"
    • Edit syslinux/syslinux.cfg on the flash drive and add unraidlabel=UNRAID-VM to the "append" line, like this:
  label unRAID OS
     menu default
     kernel /bzimage
     append unraidlabel=UNRAID-VM initrd=/bzroot
  • Make the same change to the "label unRAID OS GUI Mode" and "label unRAID OS Safe Mode" areas as well
  • On the same flash drive, copy the newly updated syslinux/syslinux.cfg over the existing EFI/boot/syslinux.cfg no longer needed
  • Create a file called startup.nsh in the root of the flash drive which contains the single line below. This prevents unRAID from getting stuck at the EFI shell.
  • Make note the manufacturer of the flash drive while it is still accessible. You'll need it later.
  • Insert the flash drive into your server and reboot. If the system tries to boot from the new "UNRAID-VM" flash drive, you'll need to adjust settings in the bios to get it to consistently boot from the original "UNRAID" flash drive instead. Once that is done, boot the host into unRAID.


Setup the VM on the host

  • On the host system, go to Settings -> VM and make sure VMs are enabled. See the manual
  • Go to the VMs -> Templates tab and select the Slackware option
  • Click on the Slackware icon and change it to the Limetech unRAID icon
  • Change the name to something relevant, like UNRAID-VM
  • Give it access to perhaps 2 CPUs and 3.0 GB of RAM (initial and max should be the same). 
  • Choose the highest level Q35 Machine
  • Leave the BIOS at OVMF and the USB Controller at "2.0 (EHCI)"
  • Add a vdisk for a cache drive and at least one data drive. Parity is optional, depending on what kind of testing you want to do. You can create all the vdisks from this interface, just provide a size, set the type to RAW and the bus to SATA. Hit the plus sign to add more drives. Note that the vdisks have random names in the VM, it might help you identify which is which through their filesizes.  i.e. make the parity slightly larger than the data drives, and make the cache drive different as well.
  • Leave the graphics/sound/network settings at their defaults.
  • In the USB Devices area, put a check mark next to the UNRAID-VM flash drive. Unfortunately, you can't see the label here so you'll have to identify it by manufacturer. If the VM's flash drive and the host's flash drive have the same manufacturer, the VM's drive will not be visible.
  • Create and start the VM
  • Back on the VMs -> Virtual Machines page you can click the unRAID icon and then choose "VNC Remote" to watch the VM boot. Note the IP address is displayed right before the login prompt.


Configure the VM

  • Point a web browser at the IP address identified in the last step
  • Optionally, go to Settings -> Identification and set the description to something like "unRAID as guest"
  • Since this is a test system, you'll probably want to go to Settings -> SMB Settings -> Workgroup Settings and set Local Master to No.
  • If you have a UPS on the host system (and you do, right?) go to Settings -> UPS (on the VM) and set the UPS cable to "Ether", UPS type to "net" and Device to the IP address of your host. Configure the runtime settings so the VM turns off before the host, and set "Turn off UPS" to no. Then start the UPS daemon.
  • Add the array devices and cache drive that were setup previously and start the array
  • Add Community Applications
  • From here, add dockers and plugins as needed for testing.
  • Note that you can update the unRAID VM as you would a normal bare-metal system, by going to Tools -> Update OS
  • Regarding system temps:
    • If your system has IPMI, you can install the "IPMI support" plugin in the guest VM and configure it to talk to the BMC IP address to get system temps and fan speeds.
    • If your system does not have IPMI then the Unraid VM will not have access to the sensors needed for the Dynamix System Temp plugin, so you will need to rely on the host OS to report temps.




Nested Virtualization

  • If you want to experiment with nested virtualization, on the host system go to Main -> Boot Device -> Flash -> Syslinux Config and add "kvm_intel.nested=1" to your "append" line (and reboot).
  • It should look something like this:
label unRAID OS
  menu default
  kernel /bzimage
  append initrd=/bzroot kvm_intel.nested=1


Related feature requests / bug reports

  • We need an unRAID VM template and icon
  • Requested improvements to the USB creator tool
  • With the second flash drive in your system, you will see an "SG_IO: bad/missing sense data" or "/dev/sdX: No such file or directory" error message on the console of the host system.  It is just cosmetic, here is the bug report. No longer an issue.
  • When defining the VM, if the client's flash drive has the same manufacturer as the host's flash drive, it will not be shown in the list of devices. Ideally, only the host's drive would be suppressed here, not all drives by that same manufacturer.
  • Like 5
Link to comment

If you don't have access to the USB creator tool, you can still setup the flash drive manually

  • The hardest part about this is finding the download file for the RC's. You'll need to look at the plugin code for either STABLE or NEXT and find the url in this area of the file:
      <FILE Name="/tmp/">
  • Follow the instructions here for the basic setup: 
  • When you get to the part about running make_bootable, first edit the make_bootable.bat file, changing line 32 from:
    set tag=UNRAID
    set tag=UNRAID-VM
    Then run the script as administrator and answer 'Y' at this prompt:
    Permit UEFI boot mode [Y/N]


  • Note: if you decline this, then you will need to manually rename the "EFI-" directory to "EFI"

  • To prevent conflicts with an existing server named "Tower", edit the config/ident.cfg file and change the server name to TowerVM:


  • Now continue with the "Make a few edits" portion of the guide above

Edited by ljm42
Link to comment

OK, I got issues with my Unraid VM and have no clue what's causing them.  Basically my network speed on the VM is abysmal


Downloading a file on the host, maxes out my internet connection.

root@server:~# wget
--2017-09-24 22:01:42--
Resolving (
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 79649012 (76M) [application/octet-stream]
Saving to: ‘bzroot’

bzroot            100%[===================>]  75.96M  7.20MB/s    in 12s     

2017-09-24 22:01:55 (6.10 MB/s) - ‘bzroot’ saved [79649012/79649012]

On my Unraid VM

root@linuxserver:~# wget
--2017-09-24 14:02:05--
Resolving (
Connecting to (||:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 79649012 (76M) [application/octet-stream]
Saving to: ‘bzroot’

bzroot              100%[===================>]  75.96M   227KB/s    in 5m 32s  

2017-09-24 14:07:37 (234 KB/s) - ‘bzroot’ saved [79649012/79649012]


Started to look at this a few months ago, but life got in the way....


Here's where I got last time with some help from @peter_sm


Still haven't tried downgrading the host to v6.3.5, not changed any hardware, nor any of my network topology, so at a real loss as to what is going on..... 


Occurs whether I use v6.3.5 - v6.4rc7 on the VM regardless of if I use a UEFI or non-UEFI method, on any version of the host from v6.4rc1 onwards which is non-uefi (Not tried UEFI on the host although I suppose I should)

Edited by CHBMB
Link to comment

For me, that wget command completed in 6.2s on the 9f VM and 8.2s on the 6.3.5 host. Strange that the VM was faster, but I suppose I'd need to download multiple times to draw any real conclusions about that.


Since everything is working for you now I won't try to downgrade my VM to test the speed on 8q. I'm glad it is good for you now!

Link to comment
  • 4 months later...

Just a quick note in case somebody else gets stuck on this: I was having trouble getting my VM to see the USB stick, which was plugged into a USB3.0 port.  I had to change the emulated controller from the default ehci USB2.0 to be an xhci USB3.0 one (either nec or qemu works, though a quick google seems to show qemu is preferred) to get it to work.

  • Like 1
Link to comment

Also, if you're like me and get the "bright idea" to give your vdisks serial numbers in the XML to distinguish them instead of using different sizes and upsetting your OCD, don't be like me and put spaces in the serial number or you'll waste a few hours figuring out that unraid doesn't like that.  Probably best to avoid other special characters too and just stick with alphanumerics.

Link to comment
  • 3 weeks later...

This USB thing seems to be not that easy to solve.


During my first steps with an Unraid VM I couldn't get past the assignment of my USB UNRAIDVM01 device. "/dev/sdb" is the USB host stick and "/dev/sda" should become the USB client stick. "Unassigned Devices" does recognize both USB sticks, "Tools > System Devices" does recognize both USB sticks but I can't find the USB stick on the VM page. I tried all three possible USB Controllers. None worked.


What's wrong here?


Thanks in advance.








Edited by hawihoney
Link to comment

The way I get around things. Firstly, don't use the same manufacturer of USB stick, gets confusing, second name each USB something different. Thirdly me bare metal is non-UEFI boot and my VM is UEFI boot, my BIOS is set to only boot from my non-UEFI stick, everything else is deactivated.

Sent from my Mi A1 using Tapatalk

Link to comment

One stick is called UNRAID, the other one UNRAIDVM01. Unraid host boots with the correct stick. I bought a ton of these USB sticks because they are very handy. Will order a different one, but in the meantime:


Anywhere in the Linux system must be that matching information. What bus/device is what /dev/sd? device. With that information I can add a hostdev section into the xml file. Any idea?


Used both alternatives and trashed my Unraid host. Good luck I do have lots of backups.


Bus 002 Device 005: ID 0781:5571 SanDisk Corp. Cruzer Fit
Bus 002 Device 004: ID 0781:5571 SanDisk Corp. Cruzer Fit

sda           8:0    1  14.7G  0 disk
└─sda1        8:1    1  14.7G  0 part
sdb           8:16   1  14.7G  0 disk
└─sdb1        8:17   1  14.7G  0 part /boot

usb-SanDisk_Cruzer_Fit_4C530001120215120411-0:0 -> ../../sda
usb-SanDisk_Cruzer_Fit_4C530001120215120411-0:0-part1 -> ../../sda1
usb-SanDisk_Cruzer_Fit_4C530001220213122434-0:0 -> ../../sdb
usb-SanDisk_Cruzer_Fit_4C530001220213122434-0:0-part1 -> ../../sdb1

[0:0:0:0]    disk    SanDisk  Cruzer Fit       1.00  /dev/sda
[1:0:0:0]    disk    SanDisk  Cruzer Fit       1.00  /dev/sdb

[   12.648072] usb 2-1.2: new high-speed USB device number 4 using ehci-pci
[   12.727521] usb-storage 2-1.2:1.0: USB Mass Storage device detected
[   12.727960] scsi host0: usb-storage 2-1.2:1.0
[   12.792076] usb 2-1.3: new high-speed USB device number 5 using ehci-pci
[   12.871523] usb-storage 2-1.3:1.0: USB Mass Storage device detected
[   12.871982] scsi host1: usb-storage 2-1.3:1.0


Link to comment

Found an old USB stick and after some reboots because of wrong IP (had to add bridge mode in network settings and br0 in VM settings and br0 in my UNRAIDVM01 settings) an unRAID trial is running.


The reboot however is not stable. When both sticks are in I get 101 errors on both sticks. BIOS is set for the main servers USB only - nothing else. I need to remove the second stick until base unRAID is running.


Thanks by now. You got me up and running for the first steps. Now I need to figure out more.


Edited by hawihoney
Link to comment
  • 8 months later...

I've just installed Unraid 6.9.0-beta30 using this method. I must say, great write up! Thanks a million, I can now start testing my translating work. As for the 'EFI/boot/syslinux.cfg' file it now only has this line: 'include /syslinux/syslinux.cfg'. No reason to overwrite the file. Furthermore, the Unraid icon now seems to be included and can be selected when creating a VM without any additional steps.


I did run into 2 hiccups caused by 1) my own stupidity/laziness and 2) something strange my system does. I am leaving those two points here for future troubleshooters.


Wrong machine model
Anyone following this guide thoroughly will probably select the correct Q35, I just scrolled down and selected the bottom one. I ended up with selecting Q35-2.4 and that just didn't work for me. I got 'Guest has not initialized the display yet' over VNC. I didn't really look into any errors it might have given and just switched over to Q35-4.2 which worked beautifully for me.


Make sure your bootable flash drive is actually passed through

For some reason my system has trouble passing through USB devices. They are connected in the sense that if I try to attach them via hotplug I get an error saying that they're already connected. However they're not actually recognised by the guest. I have to detach them and then reattach them in order to get them to work. For my Windows and Linux boxes I just hotplug them after boot at the moment.


Hotplugging, of course, doesn't work for a bootable flash drive. I just ended up passing through an entire USB controller to get the VM to boot of my flash drive.


  • Like 1
Link to comment
  • 1 month later...

I have 2 baremetal UNraid with their license.

(the second one is a fusion of a NAS + desktop pc) it works well but i lose some performance for gaming and I tired so I want to move the UNRAID to the first box (already with unraid but as VM) to isolate version and permissions.

How can i move my license to the VM without even use pendrive? I supose it is fine somehow to dump my pendrive to a img file and then load the img file to the VM? but then license will fails?

what should I do?

Edited by segator
Link to comment
  • 1 month later...
On 12/15/2020 at 11:35 AM, segator said:

I have 2 baremetal UNraid with their license.

(the second one is a fusion of a NAS + desktop pc) it works well but i lose some performance for gaming and I tired so I want to move the UNRAID to the first box (already with unraid but as VM) to isolate version and permissions.

How can i move my license to the VM without even use pendrive? I supose it is fine somehow to dump my pendrive to a img file and then load the img file to the VM? but then license will fails?

what should I do?


If you follow this guide, it will tell you how to setup the VM's flash drive so the VM will be able to boot from it.

Link to comment
  • 3 weeks later...
On 2/21/2021 at 3:12 AM, segator said:

the guide explains how to use real pendrive, I prefer to use a simple img file instead another USB :)


On 2/21/2021 at 6:46 AM, jonathanm said:

Not possible, the USB unique guid is what the unraid license is validated against, so an image file can't be licensed.


Ah, I guess that was assumed in the guide, but not specifically stated. I modified the second paragraph to hopefully make it clear that the VM requires a physical USB flash drive.

Link to comment
  • 1 month later...

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.
Note: Your post will require moderator approval before it will be visible.

Reply to this topic...

×   Pasted as rich text.   Restore formatting

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.