Difference between revisions of "UnRAID OS version 6 Upgrade Notes"

From unRAID
Jump to: navigation, search
m (Limetech moved page UnRAID 6 3/Upgrade Instructions to UnRAID OS version 6 Upgrade Instructions without leaving a redirect)
 
(19 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
= Prerequisites =
 
= Prerequisites =
  
Before upgrading to version 6.3, please ensure you have made a complete back up of your USB flash device.  You can do this by copying the entire contents of the "Flash" share to a separate computer.
+
Before upgrading, we highly recommend making a complete back up of your USB flash device.  You can do this by copying the entire contents of the "flash" share to a separate computer.
  
== From version 5.x or earlier ==
+
= From version 6.3 =
  
Please see [http://lime-technology.com/forum/index.php?topic=41061.0 this forum post] for information on upgrading.
+
#Boot your server up and login to the web interface
 +
#Click the ''Plugins'' tab
 +
#Click the "Update" button next to unRAID Server OS
 +
#Once the upgrade is complete, reboot your server for it to take affect
 +
 
 +
= From version 6.2 =
 +
 
 +
#Boot your server up and login to the web interface
 +
#Click the ''Plugins'' tab
 +
#Click the ''Check for Updates'' button
 +
#Click the "Update" button next to unRAID Server OS
 +
#Once the upgrade is complete, reboot your server for it to take affect
 +
 
 +
Note: if ''Check for Updates'' shows no update, see below.
 +
 
 +
== Possible upgrade issues ==
 +
 
 +
Having problems after the update?  See below for common issues and solutions.
 +
 
 +
=== The new release does not show up after clicking ''Check for Updates'' button ===
 +
 
 +
In this case, manually install the update as follows:
 +
 
 +
#Navigate to Plugins/Install Plugin tab
 +
#Select/copy this text <code>https://raw.githubusercontent.com/limetech/unRAIDServer/master/unRAIDServer.plg</code>
 +
#Paste into URL field and click Install
 +
 
 +
=== My array / docker apps are taking a really long time to start after the upgrade ===
  
== From version 6.0 or 6.1 ==
+
There is a one-time update procedure that each container will need to go through in order to point it towards the new Docker Hub API going forward, even if the container itself truly isn't in need of an update. This process will happen automatically the first time your containers are started after upgrading. The Docker change log describes it like this:
  
Due to changes to both VM manager and Docker, there are special steps you must perform as part of the upgrade process. Note, these steps only apply if you are making use of Docker or VMs in your existing setup.
+
<blockquote>
 +
Docker 1.10 uses a new content-addressable storage for images and layers.
 +
A migration is performed the first time docker is run, and can take a significant amount of time depending on the number of images present.
 +
</blockquote>
  
=== Docker Containers ===
+
See [https://github.com/docker/docker/releases/tag/v1.10.0 here] for more information from Docker on this.
  
There is a one-time update procedure that each container will need to go through in order to point it towards that new API going forward, even if the container itself truly isn't in need of an update (see [https://github.com/docker/docker/releases/tag/v1.10.0 here] for more information from Docker on this).  This process will happen automatically the first time your containers are started after upgrading. 
+
=== My containers aren't working right after the upgrade ===
  
 
If you run into any issues with your containers after this procedure completes (such as the "layers from manifest don't match image configuration" error), you will need to rebuild your docker image file.  To do this:
 
If you run into any issues with your containers after this procedure completes (such as the "layers from manifest don't match image configuration" error), you will need to rebuild your docker image file.  To do this:
Line 23: Line 53:
 
#From the ''Template'' drop down, select one of your previous templates (prefixed with "my-") and then click ''Apply''
 
#From the ''Template'' drop down, select one of your previous templates (prefixed with "my-") and then click ''Apply''
 
#Repeat the previous step for each of your containers
 
#Repeat the previous step for each of your containers
#You will not need to reconfigure your apps after this is complete
+
#You will '''not''' need to reconfigure your apps after this is complete
 
 
=== Virtual Machines ===
 
 
 
'''NOTE:  before upgrading, please be sure to backup any VMs you have AND set disable them from auto-starting.  This will give you the opportunity to perform the post-upgrade procedures before starting them.'''
 
 
 
'''After upgrading, any edits you make to your VMs will not be present if you roll-back to 6.1.x at a later point in time.  When you roll-back, your VM configurations (XML) will be in the state they were prior to the upgrade.  This also means that new VMs you create in 6.2 will NOT show up under VM manager if you roll back to 6.1.x.  This doesn't affect virtual disk image, only the VM configurations themselves.'''
 
  
==== Pre-upgrade instructions ====
+
=== My VMs get an error of "cannot get interface MTU..." ===
  
A change that was made in version 6.2 eliminated the customization of the bridge name used for virtual machines. Users that have a custom bridge name set will need to revert it back to the default of 'br0' '''before upgrading'''.  To see if you have a customized network bridge, open the ''Settings'' -> ''Network Settings'' page of the web interface.  If the bridge name is anything other than 'br0', change it back to 'br0' and click apply.
+
A change that was made in version 6.2 eliminated the customization of the bridge name used for virtual machines. Users that have a custom bridge name set will need to fix their VMs to point to the new default of 'br0'.  To fix this, perform the following steps:
  
If you found you have a custom-name for your network bridge and you also have VMs on the system, it is very likely that these VMs are also set to use the custom-named bridge and therefore they must be updated as well.  To do this, you will need to perform the following steps after you have restored the default network bridge name:
+
#Navigate to the VMs tab.
 
 
#Shutdown all VMs running on the system.
 
 
#Edit each VM and turn on ''Advanced View'' mode.
 
#Edit each VM and turn on ''Advanced View'' mode.
 
#Locate the network section and from the dropdown, select br0 and then click apply.
 
#Locate the network section and from the dropdown, select br0 and then click apply.
 
#Once all VMs are set to use the 'br0' bridge, go to the ''Settings'' -> ''VM Manager'' page, turn on ''Advanced View'', and set the default network bridge on this page to also be 'br0' and click apply.
 
#Once all VMs are set to use the 'br0' bridge, go to the ''Settings'' -> ''VM Manager'' page, turn on ''Advanced View'', and set the default network bridge on this page to also be 'br0' and click apply.
  
Your VMs should now be ready for use under 6.2.
+
=== VNC access to my VMs is not working or performing poorly ===
 
 
==== Post-upgrade instructions ====
 
 
 
To ensure that your VMs take advantage of all these changes and continue to function properly, the following one-time actions should be performed before starting your VMs for the first time but ''after'' you upgrade.
 
  
'''NOTE: Any custom XML edits you have made will be lost after performing this procedure.'''
+
VMs created in earlier releases of unRAID Server OS may be set to use an outdated graphics device driver for VNC access. To fix this, perform the following steps:
  
#For each VM, go to the VMs tab, click the VM's icon, and select the Edit option
+
#For each affected VM, go to the VMs tab, click the VM's icon, and select the Edit option
 
#Turn on "Advanced View" in the top right of the Edit VM page
 
#Turn on "Advanced View" in the top right of the Edit VM page
 
#If you are using VNC for the primary graphics card, adjust the VNC Video Driver field to QXL
 
#If you are using VNC for the primary graphics card, adjust the VNC Video Driver field to QXL
 
#Click Apply
 
#Click Apply
  
==== OVMF VM Booting Issues ====
+
=== My OVMF VM doesn't boot correctly ===
  
 
OVMF-based virtual machines that were created under version 6.1 or earlier will most likely require a one-time process to boot up properly on the new release.  If you are presented with an EFI shell instead of your OS booting appropriately, type the following commands in order to boot your VM:
 
OVMF-based virtual machines that were created under version 6.1 or earlier will most likely require a one-time process to boot up properly on the new release.  If you are presented with an EFI shell instead of your OS booting appropriately, type the following commands in order to boot your VM:
  
*fs0:
+
#fs0:
*cd efi/boot
+
#cd efi/boot
*bootx64.efi
+
#bootx64.efi
  
 
If this doesn't work, try changing the first command from fs0: to fs1:.  If that doesn't work, please post in the [http://lime-technology.com/forum forums] for further assistance.  This procedure should only need to be performed the first time you boot OVMF VMs that were previously created using unRAID 6.1 or earlier.
 
If this doesn't work, try changing the first command from fs0: to fs1:.  If that doesn't work, please post in the [http://lime-technology.com/forum forums] for further assistance.  This procedure should only need to be performed the first time you boot OVMF VMs that were previously created using unRAID 6.1 or earlier.
  
== From version 6.2 ==
+
=== Trying to start my VM gives a "Invalid Machine Type" error ===
 +
 
 +
If you receive this error, simply edit your VM in the webGui and without making any changes, click "Apply".  This will update the VM's machine type to the latest version and your VM should start without the error.
 +
 
 +
=== Poor VM performance after upgrading ===
 +
 
 +
Some users have replied that their VMs perform poorly after updating to 6.3.  One possible solution could be to update the machine type version for your VM.  To do this, edit your VM from the VMs tab in the webGui.  Turn on "Advanced View" in the top right and look for the '''Machine''' option.  Toggle the version to the latest revision and then hit apply (do not change the prefix selected, only the version; e.g. if previously you were on i440fx-2.5, try changing to i440fx-2.7, but don't change to Q35-2.7).  Try starting your VM and see if performance improves.
 +
 
 +
=== Poor VNC performance after upgrading ===
 +
 
 +
If your VM has poor VNC performance after upgrading, please try changing the VNC Video Driver.  You can do this from the Edit VM page.  It is recommended to first try Cirrus, then vmvga (if available for your VM type).
 +
 
 +
= From version 6.1 or earlier =
 +
 
 +
Please ensure your system meets these requirements before upgrading:
 +
 
 +
#Your server must be running version 6.1 or later.
 +
#Your USB flash device must have at least 128MB of free space.
 +
#If you have customized your network bridge name previously, it must be changed back to the default of 'br0' before upgrading.
 +
#VMs set to use a custom-named bridge will also need to be edited to point to the 'br0' prior to the upgrade.
 +
 
 +
== Checking your existing version ==
 +
 
 +
To check which version of unRAID is presently running on your server, simply log into the web interface and look in the top right corner of the browser.
 +
 
 +
== Checking for sufficient free space ==
 +
 
 +
The upgrade process will check for this automatically, but if you wish to be proactive, you can review your boot device's free space under the Flash section on the ''Main'' tab of the web interface.
 +
 
 +
== Checking your network bridge name ==
 +
 
 +
To see if you have a customized network bridge, open the ''Settings'' -> ''Network Settings'' page of the web interface.  If the bridge name is anything other than 'br0', change it back to 'br0' and click apply.
 +
 
 +
== Checking your VM network bridge settings ==
 +
 
 +
If you found you have a custom-name for your network bridge and you also have VMs on the system, it is very likely that these VMs are also set to use the custom-named bridge and therefore they must be updated as well.  To do this, you will need to perform the following steps after you have restored the default network bridge name:
  
No special steps are necessary to upgrade from version 6.2 to 6.3.
+
#Shutdown all VMs running on the system.
 +
#Edit each VM and turn on ''Advanced View'' mode.
 +
#Locate the network section and from the dropdown, select br0 and then click apply.
 +
#Once all VMs are set to use the 'br0' bridge, go to the ''Settings'' -> ''Network Settings'' page, turn on ''Advanced View'', and set the default network bridge on this page to also be 'br0' and click apply.
  
= Installing the update =
+
Your VMs should now be ready for use under the latest version.
  
 
#Boot your server up and login to the web interface
 
#Boot your server up and login to the web interface
Line 77: Line 133:
 
#Once the upgrade plugin has been installed, reboot your server
 
#Once the upgrade plugin has been installed, reboot your server
  
LINK TO PLUGIN
+
https://raw.githubusercontent.com/limetech/unRAIDServer-6.2/master/unRAIDServer.plg
 +
 
 +
== Post installation procedures ==
 +
 
 +
Once rebooted under version 6.2 for the first time, it may take several minutes (potentially longer) to start the array if Docker containers have been previously configured.  This is due to a one-time upgrade procedure that will be applied to the containers in your Docker image file.  This procedure is automatically performed for you and does not have to be manually enabled.
 +
 
 +
In addition, OVMF-based virtual machines that were created under version 6.1 or earlier will most likely require a one-time process to boot up properly under version 6.2.  Upon booting an OVMF-based VM under 6.2, if you are presented with an EFI shell instead of your OS booting appropriately, type the following commands in order to boot your VM:
 +
 
 +
*fs0:
 +
*cd efi/boot
 +
*bootx64.efi
 +
 
 +
If this doesn't work, try changing the first command from fs0: to fs1:.  If that doesn't work, please post in the [http://lime-technology.com/forum forums] for further assistance.  This procedure should only need to be performed the first time you boot OVMF VMs under version 6.2 that were previously created using unRAID 6.1 or earlier.
 +
 
 +
= From version 5.x or earlier =
 +
 
 +
Please see [http://lime-technology.com/forum/index.php?topic=41061.0 this forum post] for information on upgrading.

Latest revision as of 22:34, 12 January 2018

Prerequisites

Before upgrading, we highly recommend making a complete back up of your USB flash device. You can do this by copying the entire contents of the "flash" share to a separate computer.

From version 6.3

  1. Boot your server up and login to the web interface
  2. Click the Plugins tab
  3. Click the "Update" button next to unRAID Server OS
  4. Once the upgrade is complete, reboot your server for it to take affect

From version 6.2

  1. Boot your server up and login to the web interface
  2. Click the Plugins tab
  3. Click the Check for Updates button
  4. Click the "Update" button next to unRAID Server OS
  5. Once the upgrade is complete, reboot your server for it to take affect

Note: if Check for Updates shows no update, see below.

Possible upgrade issues

Having problems after the update? See below for common issues and solutions.

The new release does not show up after clicking Check for Updates button

In this case, manually install the update as follows:

  1. Navigate to Plugins/Install Plugin tab
  2. Select/copy this text https://raw.githubusercontent.com/limetech/unRAIDServer/master/unRAIDServer.plg
  3. Paste into URL field and click Install

My array / docker apps are taking a really long time to start after the upgrade

There is a one-time update procedure that each container will need to go through in order to point it towards the new Docker Hub API going forward, even if the container itself truly isn't in need of an update. This process will happen automatically the first time your containers are started after upgrading. The Docker change log describes it like this:

Docker 1.10 uses a new content-addressable storage for images and layers. A migration is performed the first time docker is run, and can take a significant amount of time depending on the number of images present.

See here for more information from Docker on this.

My containers aren't working right after the upgrade

If you run into any issues with your containers after this procedure completes (such as the "layers from manifest don't match image configuration" error), you will need to rebuild your docker image file. To do this:

  1. Stop Docker from the Settings > Docker page
  2. Click the checkbox and then click the button to delete the image
  3. Start Docker again and the image will be recreated
  4. Go to the Docker tab and click Add Container
  5. From the Template drop down, select one of your previous templates (prefixed with "my-") and then click Apply
  6. Repeat the previous step for each of your containers
  7. You will not need to reconfigure your apps after this is complete

My VMs get an error of "cannot get interface MTU..."

A change that was made in version 6.2 eliminated the customization of the bridge name used for virtual machines. Users that have a custom bridge name set will need to fix their VMs to point to the new default of 'br0'. To fix this, perform the following steps:

  1. Navigate to the VMs tab.
  2. Edit each VM and turn on Advanced View mode.
  3. Locate the network section and from the dropdown, select br0 and then click apply.
  4. Once all VMs are set to use the 'br0' bridge, go to the Settings -> VM Manager page, turn on Advanced View, and set the default network bridge on this page to also be 'br0' and click apply.

VNC access to my VMs is not working or performing poorly

VMs created in earlier releases of unRAID Server OS may be set to use an outdated graphics device driver for VNC access. To fix this, perform the following steps:

  1. For each affected VM, go to the VMs tab, click the VM's icon, and select the Edit option
  2. Turn on "Advanced View" in the top right of the Edit VM page
  3. If you are using VNC for the primary graphics card, adjust the VNC Video Driver field to QXL
  4. Click Apply

My OVMF VM doesn't boot correctly

OVMF-based virtual machines that were created under version 6.1 or earlier will most likely require a one-time process to boot up properly on the new release. If you are presented with an EFI shell instead of your OS booting appropriately, type the following commands in order to boot your VM:

  1. fs0:
  2. cd efi/boot
  3. bootx64.efi

If this doesn't work, try changing the first command from fs0: to fs1:. If that doesn't work, please post in the forums for further assistance. This procedure should only need to be performed the first time you boot OVMF VMs that were previously created using unRAID 6.1 or earlier.

Trying to start my VM gives a "Invalid Machine Type" error

If you receive this error, simply edit your VM in the webGui and without making any changes, click "Apply". This will update the VM's machine type to the latest version and your VM should start without the error.

Poor VM performance after upgrading

Some users have replied that their VMs perform poorly after updating to 6.3. One possible solution could be to update the machine type version for your VM. To do this, edit your VM from the VMs tab in the webGui. Turn on "Advanced View" in the top right and look for the Machine option. Toggle the version to the latest revision and then hit apply (do not change the prefix selected, only the version; e.g. if previously you were on i440fx-2.5, try changing to i440fx-2.7, but don't change to Q35-2.7). Try starting your VM and see if performance improves.

Poor VNC performance after upgrading

If your VM has poor VNC performance after upgrading, please try changing the VNC Video Driver. You can do this from the Edit VM page. It is recommended to first try Cirrus, then vmvga (if available for your VM type).

From version 6.1 or earlier

Please ensure your system meets these requirements before upgrading:

  1. Your server must be running version 6.1 or later.
  2. Your USB flash device must have at least 128MB of free space.
  3. If you have customized your network bridge name previously, it must be changed back to the default of 'br0' before upgrading.
  4. VMs set to use a custom-named bridge will also need to be edited to point to the 'br0' prior to the upgrade.

Checking your existing version

To check which version of unRAID is presently running on your server, simply log into the web interface and look in the top right corner of the browser.

Checking for sufficient free space

The upgrade process will check for this automatically, but if you wish to be proactive, you can review your boot device's free space under the Flash section on the Main tab of the web interface.

Checking your network bridge name

To see if you have a customized network bridge, open the Settings -> Network Settings page of the web interface. If the bridge name is anything other than 'br0', change it back to 'br0' and click apply.

Checking your VM network bridge settings

If you found you have a custom-name for your network bridge and you also have VMs on the system, it is very likely that these VMs are also set to use the custom-named bridge and therefore they must be updated as well. To do this, you will need to perform the following steps after you have restored the default network bridge name:

  1. Shutdown all VMs running on the system.
  2. Edit each VM and turn on Advanced View mode.
  3. Locate the network section and from the dropdown, select br0 and then click apply.
  4. Once all VMs are set to use the 'br0' bridge, go to the Settings -> Network Settings page, turn on Advanced View, and set the default network bridge on this page to also be 'br0' and click apply.

Your VMs should now be ready for use under the latest version.

  1. Boot your server up and login to the web interface
  2. Click the Plugins tab
  3. Click the Install Plugin tab
  4. Copy and paste the below link into the field and click install
  5. Once the upgrade plugin has been installed, reboot your server

https://raw.githubusercontent.com/limetech/unRAIDServer-6.2/master/unRAIDServer.plg

Post installation procedures

Once rebooted under version 6.2 for the first time, it may take several minutes (potentially longer) to start the array if Docker containers have been previously configured. This is due to a one-time upgrade procedure that will be applied to the containers in your Docker image file. This procedure is automatically performed for you and does not have to be manually enabled.

In addition, OVMF-based virtual machines that were created under version 6.1 or earlier will most likely require a one-time process to boot up properly under version 6.2. Upon booting an OVMF-based VM under 6.2, if you are presented with an EFI shell instead of your OS booting appropriately, type the following commands in order to boot your VM:

  • fs0:
  • cd efi/boot
  • bootx64.efi

If this doesn't work, try changing the first command from fs0: to fs1:. If that doesn't work, please post in the forums for further assistance. This procedure should only need to be performed the first time you boot OVMF VMs under version 6.2 that were previously created using unRAID 6.1 or earlier.

From version 5.x or earlier

Please see this forum post for information on upgrading.