Difference between revisions of "Upgrading to UnRAID v6"

From unRAID
Jump to: navigation, search
(minor v6 edits)
Line 689: Line 689:
'''Make_bootable may fail on a Mac'''
'''Make_bootable may fail on a Mac'''
* It's rare, but there are a few reports where preparing the flash drive on a Mac did not succeed, reason unknown.  Taking the same flash drive to a Windows machine and preparing it there did succeed.
* It's rare, but there are a few reports where preparing the flash drive on a Mac did not succeed, reason unknown.  Taking the same flash drive to a Windows machine and preparing it there did succeed.
'''Docker containers losing their configurations'''
* If you find that the configuration settings for you docker containers are periodically getting lost, then it is likely that you have them stored on the cache drive (typically under an ''appdata'' folder), and the contents of this folder have been moved to the main array drives.  This will be because unRAID has automatically created a share corresponding to the folder name and assigned default settings which includes periodically running ''mover'' to put the contents on the main array disks.  To rectify this do the following:
** Go into the Shares tab and check the settings for the share corresponding to the folder storing Docker configuration files.  Change the ''Use Cache'' setting to '''only'''.
** Find which array disks have the folder corresponding to this share, and move the files back to the cache disk.  Make sure when doing this you use the disk shares (''cache'' and ''disk??'') and not the user share.

Revision as of 08:13, 14 July 2015

If this page looks too long for you, and you are running v5.0 to v5.0.6, many users recommend Frank's short and sweet instructions here -> Upgrading unRAID from Version 5 to Version 6.

This guide is designed to help users of previous versions successfully upgrade to unRAID v6.0 or later, using the many lessons learned by the unRAID community. The guide is intended to be comprehensive, covering most scenarios and pitfalls. However, the basic process is simple if you work through the sections one by one. There are a number of steps to follow below, that should help make the migration experience more predictable and less stressful. There is also information to help those who have customized their existing unRAID system beyond its basic NAS functionality.

It is recommended to read through this entire guide first, before beginning the upgrade.

Important changes are coming to this section. We will be recommending a clean install of v6, to anyone coming from ANY version prior to v5.0, including all v5 betas and all v4 releases. That means skipping upgrades to v4.7 and v5.0, and jumping directly to v6.0.

Before the upgrade

Basic hardware requirements

  • All unRAID v6 releases are 64 bit, and REQUIRE a 64 bit processor! So the first requirement is to make sure your CPU is 64 bit capable, which almost all modern CPU's are. Here's a simple test for your current unRAID system, that will quickly show whether you have a problem or not ...
  1. Login or Telnet into your unRAID console
  2. Type "grep --color lm /proc/cpuinfo" (type it without the quotes; color is preceded by 2 hyphens)
  3. Look for lm in the CPU flags listed
  4. If it is there, it is 64-bit capable. If it is not, sorry, you need new hardware!
  • One gigabyte of RAM is the minimum memory recommended (but more is better). It *may* be possible to run in less, but definitely not recommended.
  • Later, we will discuss the advantages of more memory, but more memory is NOT an absolute requirement to run v6. The ONLY absolute requirement is passing the 64 bit test.

Upgrade or Clean Install?

  • If you are upgrading from ANY release before v5.0, then it is recommended to do a 'clean' install, essentially a fresh start, with all your drives intact, but no configuration.
  • --- work in progress ---

Important Considerations

  • Version 4 and version 5 plugins are NOT compatible with the unRAID v6.x series! All of unRAID v6 is 64 bit, and requires 64 bit tools and plugins. All previous versions and plugins were 32 bit.
Naturally, you are nervous about tearing down a perfectly good system, that you have spent a lot of time tweaking, getting it to perform just the way you want. And it's normal to wonder how well the replacements to your current set of plugins will work. Docker Containers are the preferred plugin replacements, so to help you feel more comfortable, we suggest you visit the Popular unRAID Docker Template Repositories and Containers page, and check out all of the Dockerized alternatives (there are thousands more available besides those!). That should give you something to look forward to!
  • unRAID OS 6 requires a license key, even for free 'trial' usage. Please see the LimeTech registration keys page for a detailed discussion on the different unRAID license levels and their restrictions.
    • If you don't have a license, then you can obtain a free Trial license for 30 days, renewable for another 30 days when it expires. The unRAID GUI will guide you through this process when you boot it the first time.
    • There is no upgrade fee for existing licenses. Your v4 and v5 Pro and Plus licenses are good for v6.
    • There is now an automated process for obtaining a replacement license key for use on a new USB device.
    • Except for the Pro license, unRAID v6 imposes 'attached device' limits. An attached device is a device capable of storing data and is counted regardless of whether unRAID is configured to use the device.
    Users who already have unRAID licenses are unlikely to be impacted by the 'Attached Devices' limits as the number of allowed devices is significantly higher than earlier versions.
    Users with the free Trial license should make sure that they conform to the limits on 'attached devices'.
  • For most users, it is strongly recommended to re-format your flash drive, essentially starting over with a clean slate. (You can always restore specific items from your v4 or v5 backup if absolutely necessary.) But if you are a veteran unRAID user who refuses to re-format, then there is an alternate no-format procedure near the bottom. But again, we strongly recommend re-formatting!
  • Very important warning: if you think there is a possibility that you may revert back to your old version, then you MUST NOT format any drives with the XFS and BTRFS file systems that are only supported on v6! Once you prepare a drive with XFS or BTRFS, then you cannot go back without removing the drive from your system and reformatting it with ReiserFS.

The Critically Important Backup

  • One way or another, we are going to destroy the contents of your unRAID boot drive! You will either re-format it (strongly recommended!) or you will delete most of it!
  • Whether you are upgrading or doing a clean install of v6, it is wise to make readable copies (pictures, screen captures, notes, etc) of your current settings, especially all drive assignments, but also users, passwords, share settings, network and server identity settings. And don't forget copies of all of your plugin settings, to make it easier to set them up in v6. Make sure that these are saved somewhere you can access, when the unRAID server is not available.
  • Make a COMPLETE backup of the entire unRAID flash drive. And make sure that the backup is copied OFF your server, preferably onto the workstation you will use to prepare it for v6.
Note: Always make sure that the array is stopped before backing up your flash. One of the items recorded on the flash is the current state of the array. If you copy the flash files while the array is started, then later restore these files and boot unRAID, this unRAID session will see that the previous last known state was 'Started', and assume it was not stopped and shut down correctly, and therefore begin a parity check (plus warn you of an unclean shutdown). Knowing this, you can ignore the warning, and cancel the parity check, if you don't want it to run right then.
  • Once the backup is complete, it's time to Perform the upgrade! Continue with next section. Only if you are a veteran unRAID user who refuses to re-format, an expert user who is confident they can deal with any issues that may arise, then you can proceed to the alternate no-format procedure.

Performing the upgrade

Install the unRAID upgrade

The official upgrade instructions are on the Getting Started page (Preparing your USB flash device section), and at the bottom of any of the V6 Change Notes. This section is directly derived from them, but you may wish to refer to them for more detail.
Experienced users may consider skipping a step or two. We recommend that you not skip the step to run make_bootable, as it does not 'damage' your existing flash file system in any way. It only upgrades the syslinux boot support.
  • Format and label it
    • If you haven't already, plug your unRAID flash drive into a Windows or Mac system. A Windows batch file or Mac script needs to be run, otherwise this upgrade could have been done at an unRAID console or Telnet session.
    • If using Windows, then open 'My Computer' (XP) or 'Computer' (Vista or later) and right-click your Flash device. Click 'Format...', set the volume label to UNRAID and then click 'Start'. Important: the volume label must be set exactly to UNRAID (all caps, 6 letters). The format is usually FAT32 or similar.
    • If using Mac, then open Disk Utility, select the device and click the Erase tab. Select Format: MS-DOS (FAT) format, Name: UNRAID, and then click Erase. Important: the name (volume label) must be set exactly to UNRAID (all caps, 6 letters).
  • Copy unRAID files
    • If you have not already downloaded the v6 distro, go to the LimeTech downloads page, and download the latest unRAID v6 zipped distro.
    • Current v6 zipped releases contain files in the root, a syslinux folder with boot files, and a config folder with basic (but empty) configuration files for a new system. Extract all of the distro to your flash drive, making sure that you extract the files preserving the folder structure. For example, syslinux.exe should end up in the syslinux folder, not in the root.
  • Make it bootable
    • Using any file manager or explorer, browse to your unRAID flash device and open it, so that you can see the make_bootable files on it.
    • Run the make_bootable script/batch file
      • If in Windows XP, double-click make_bootable (make_bootable.bat). It should open a DOS window, and run syslinux.exe.
      • If in Windows 7 or later, right-click on make_bootable (make_bootable.bat) and select Run as Administrator.
      • If using a Mac, double-click the file make_bootable_mac and enter your admin password when prompted.
      • Note: during the process of running this script, the flash device may seem to disappear and reappear.
  • Install the license key
    • You MUST have a license key, even for free 'trial' usage. If you don't have one, then on first boot, you will be taken to the LimeTech registration keys page, where you can purchase one or get a Trial key.
    • unRAID v6 requires that the license key (the .key file) be in the config folder, NOT in the root.
    If you have multiple unRAID license keys, then you can put all of them into the config folder, and unRAID will work out which of them matches the GUID of the USB stick you booted with.
  • Restore saved configuration files
    Note that if you want to start over, that is, start with a completely fresh system (a 'clean' install), you do not have to restore your current configuration. Just remember though that you will have to re-configure everything, including identification and network settings, user shares, users and passwords, etc. Since you will need to re-assign all of your drives, make sure you know which drives are which, ESPECIALLY which drive is the parity drive! If you assign a drive that already has data on it from v4 or v5, then unRAID OS 6 will recognize it and the data should be intact.
    • If this is a 'clean' install (a fresh system with no array assignments or other configuration) -
      • Then the only thing you have to copy is the license key, already done above.
      • It may be safe to copy network.cfg and ident.cfg, but no others! These 2 files would get your system quickly back on the network, with its old name.
      For reference, the section Files on flash drive can help you decide which files and folders to keep and which ones cannot be kept.
    • If this is an 'upgrade' install (an existing system with functioning array and saved configuration) -
      • Very important, you will be copying the files from only 2 folders of your saved v4 or v5 backup, and no others!.
      For reference, the section Files on flash drive can help you decide which files and folders to keep and which ones cannot be kept.
      • However, we need to make sure that we do NOT restore the go file from your saved v4 or v5 backup unless you have never changed it from the default one. Rename the go in your saved v4 or v5 backup to something like go_v5 or go.v5 or go.bak, anything but go! Do not proceed until you are sure that your old go file has been renamed!
      • Copy ONLY the files from your saved v4 or v5 config folder to the flash drive's config folder. Note that you may need to grant permission to overwrite existing files.
      If you have copied any plugin or package files into your config folder (such as cache_dirs.sh), do NOT copy them to your new config folder!
      • Then copy ONLY the files from your saved config/shares folder to the flash drive's config/shares folder.
      • Do NOT restore any other files or folders, especially any plugin files!
      If you were to copy other folders, you might accidentally copy a 32-bit plugin which is incompatible with v6.
    • If correctly done, you should have a go file in your config folder that has a size of 71 bytes.
  • Done!
    • We are done now, but ... Important! PLEASE remember to properly Eject or Safely Remove your flash drive! If on a Mac, close the terminal window and Eject the device.
    • If there were no error messages or other issues, your unRAID flash drive is now bootable, prepared with unRAID v6, and ready to plug back into your unRAID system!

Boot and test

  • Plug the flash drive back in to your unRAID server, boot it up, and test. If your server was working fine before and auto-starting the array, then it should do so again.
    • If it fails to boot to the boot menu, then you probably skipped running make_bootable!
    • Another possibility is that the BIOS settings for the unRAID server have lost the option to boot from the USB drive. If so you will need to go into the BIOS settings for the server and reset them to boot from the unRAID USB drive..
  • If for any reason it fails to boot correctly, see the Troubleshooting section at the end.
  • If you don't have a license, then on first boot, you will be taken to the LimeTech registration keys page.
  • Did it boot? There are a very few reports that first boot was not successful, and they had to boot a second time, successfully.
  • If this is an upgrade, not a clean fresh install, then access to existing array disks and shares should be the same as before, from any station.

New Permissions

  • Very important! If you have ever run a version of unRAID prior to v5.0-rc9, then you must run the New Permissions tool, on the Tools tab. If your array is up and running now, then NOW is when you should run it! If you still need to assign the drives, then do it once the array is running correctly. But don't forget, or your files and folders may not be fully accessible. It does not matter if this is a 'clean' or 'upgrade' install, because it is your data files and folders that need their permissions corrected. Even if you have run the New Permissions tool before, if it was prior to v5.0-rc9, then you need to run it again.

Meet the new GUI

  • Version 6 has an all new GUI (Graphic User Interface) for managing your server! It looks very different to the LimeTech GUI that was standard with version 5. This new GUI is based on the Dynamix GUI that was developed for version 5 as an independent plugin. With version 6, the functionality of this GUI has been integrated into the base unRAID OS and expanded even further to be able to completely manage your unRAID server.
  • All settings and configuration can be done from the new GUI. Monitoring your system is easier now through the Dashboard tab; the enhanced Main page; the Stats tab; and the new Notifications system. And extensive help is widely available, through the Help button.
  • Plugins and Docker containers can now be installed and managed through the GUI. Uninstalling one is now as simple as clicking on a "Remove" button.
  • On your workstation, browse to the web management Main page, same as in v5 at //tower (for Mac: //tower.local ), replacing tower with either your server's name or your server's static IP address. From now on, we will refer to the 'unRAID web management pages' as the 'webGui', or 'GUI' for short.
  • It is worth taking some time to explore this improved GUI to gain a sense of what can be done through it.
  • The new Help feature, mentioned above, is accessed through the Help button on the Tab bar at the top. This button is a "toggle" and turns the Help 'on' and 'off'. This feature can help you as you begin to tailor v6 to your personal preferences, such as in setting up the built-in features of email notifications, UPS settings, and many others. 'Help' will provide you with a full description of what each setting choice means or exactly what information is required, in the case of a parameter box.
  • On the Main screen, you will see the same green, blue, grey, and red balls as before, but just to their left is a little triangle. If it points up, then the drive is probably spun down and you can click on this to spin it up. If it points down, then the drive is probably spinning and you can click on this to spin it down. Click on the ball itself to see other options available for that drive. The Cache drive has special options for it, and the flash drive has special options just for it, including a syslinux.cfg editor!
  • Certain tabs only appear when you enable the relevant capability via the Settings tab. Examples of this are User Shares, Dockers and VMs.
  • Many of the main tabs have multiple sub-tabs so do not forget to look at these as well.
  • Visit all of the available tabs now, and check the system out...

Configuring the Settings

If you have restored your config folder, most settings should still be the same, but a few may not be working any more, some have changed, and there are many new settings.

Take some time to go through all of the Settings pages, and modify them as desired. Make sure you click the Apply button before leaving a Settings page to save any changes you have made (the Apply button is normally disabled until you change a setting).

Important! Clicking the Done button does not save any changes. You must click the Apply button to save your changes.

Among the numerous improvements in v6 is the new Help feature, with extensive help that is turned on or off by clicking on the Help button in the upper right. While help is not available everywhere, you will probably be amazed at how much there is!

Here are suggestions and comments concerning various settings, both new and old.

  • Date and Time
    • NTP settings should be correct, but the timezone setting may not be. You will probably need to fix it.
  • Disk Settings
    • Most of them should be correct
    • Note the new setting Default file system, which defaults to XFS. Until v6, it had always been ReiserFS, but XFS is now the recommended choice for new formats. The other new file system choice is BTRFS. For file system comparative info, see the File systems section near the bottom.
    Very important reminder: if you think there is a possibility that you may want to revert back to v4 or v5, then you MUST NOT format any drives with the new v6 file systems XFS and BTRFS! If you want to keep the ability to revert back, make sure that you change Default file system to ReiserFS. Once you prepare a data or Cache drive with XFS or BTRFS, then you cannot go back to v4 or v5 without removing the drive from your system and reformatting it with ReiserFS.
    • There is a new setting Tunable (poll_attributes), which controls how often SMART info, temps, and spin status are checked in the background. It defaults to 30 minutes, and that is long enough that the displayed state is sometimes significantly out of sync with the real state. It is suggested to change it to '600' (for 10 minutes) or '180' (for 3 minutes) or '60' (for 1 minute). This is not the same as how often the display is updated, that is controlled by a Display Setting, Page update frequency.
  • Docker
    This is where you enable Docker support. Although Docker use is not mandatory, especially if you intend to use unRAID purely as a NAS, in practice most users will want it enabled as the primary way to run extra apps on the unRAID server.
    • To use Dockers, change Enable Docker to Yes, type a location, file name and size for the Docker image file (holds the Docker system stuff). Click the Apply button.
      • A valid location might be /mnt/cache/docker.img or /mnt/disk1/docker.img, but not anything in the User Shares (i.e. any path containing /mnt/user.)
      • The default value for the size is currently 10GB which is enough for light use, and enough to experiment with, but if you are expecting to make heavier use of Docker containers, we recommend starting with a larger size such as 20GB or 30GB. If necessary, it is easy to grow the size of the Docker image file later, not quite so easy to shrink it.
    • Important Note: the Docker image file and various Docker folders are often saved to the Cache drive, but there is one thing you need to be careful of. Most users have User Shares turned on, and if you do then the Mover process is going to try to move files and folders from the Cache drive to a data drive. It assumes that any top level folder on any data drive or the Cache drive is a Share folder.
      To avoid that, here are the rules for the Mover:
      • it does not move files at the root of the Cache drive
      • it does not move root folders IF those folders are configured as Cache-Only shares
      • it does not move root folders whose name begins with a period. (In Linux by convention, file or folder names beginning with a period are considered 'hidden'.)
    • What we recommend is to configure the Docker image file in the root of the Cache, where it will be safe, and configure all Docker folders as Cache-Only shares. If you forget, the Mover may move them off the Cache drive!
    • If needed, you can also use the Scrub command here. Scrub is a file checking and cleanup tool for the BTRFS Docker volume.
  • Identification
    • There's a new setting, for Model. Those with multiple unRAID systems can add a Model comment or identifier.
  • Network Settings
    • The old network settings are here and should be correct, but there are important new ones! It's best to leave them alone, until you understand them. In general, if a plugin, Docker Container, or VM needs a change here, you will be instructed about what changes to make.
  • Global Share Settings
    • This used to be called something like User Share Settings, but it's essentially the same thing. Individual User Share settings are not configured here, only global settings for the User Share system and for the Cache drive.
    • The array needs to be stopped when changing the Global Share Settings.
    • Other Cache drive settings are found by clicking on the Cache drive itself, on the Main page.
    • If you are looking for the Mover settings, they are under Scheduler, see below.
  • UPS Settings
    • Brand new! UPS support is now included in unRAID, for APC and APC compatible models (such as many models from CyberPower, Tripp Lite, Belkin, and other brands). If you have previously installed the apcupsd plugin, it's no longer needed, an equivalent is now built in.
    • To get it started though, you will need the appropriate cable connected, and you will need to set the UPS Cable and Type and adjust the timings to your requirements, then set the UPS daemon to start. Click the Apply button to start the service.
    • Turn on the help! Click the Help button in the upper right to view a lot of configuration help.
    • This thread may be helpful with the timings settings, and the APCUPSD User Manual has a wealth of information. See this for the notifications possible.
    • At any time (once it is running), you can click the UPS Status button to view considerable information and status numbers about your UPS unit.
    • Try a cut-the-power test - flip the circuit breaker, or switch off a power strip it's plugged into, or unplug the power cord of the UPS unit, wait 10 seconds, and check the syslog for the appropriate messages. To see the latest syslog messages, click the Log button in the upper right corner. Restore power to the UPS, and check the log messages again. WARNING: if you pull the plug, your UPS will not be grounded, creating a "floating ground" which can be dangerous. Therefore pulling the plug is not recommended; it's safer to flip a circuit breaker or plug UPS into a power strip and switch that off.
    • Note: This first version of the UPS support is only for those UPS models that use the APC signaling protocols. unRAID users have discovered that many UPS models from CyberPower, Tripp Lite, Belkin, and other brands use almost the same APC protocols, and are therefore supported too (but see this). If your UPS worked with the apcupsd package in v5, then it should work with the internal UPS support in v6. A future release will support other brands, using the NUT interface.
  • VM Manager
    This is where you enable the VM Manager. It is recommended that you enable the VM Manager at this point even if you do not initially intend to use VMs so that you can see what the GUI looks like. You can always disable it later.
  • Network Services
    • AFP, NFS, and SMB settings are essentially the same, but the help is much improved. A vsftpd FTP server is included, but there's only one setting, the allowed users.
  • Confirmations
    • This has several toggles for whether Reboot, Powerdown, and Stop have "Are you sure" confirmation boxes, and whether you are warned about Settings pages with un-applied changes.
  • Display Settings
    • Lots of settings for the Dynamix webGui, check and adjust them to suit your preferences. Sorry, help may not be fully available yet.
    • The "Page update frequency" setting governs how often the webGui is updated, how often disk status and numbers and temps are kept current. It defaults to 'Real-time' which keeps them very current, but unfortunately impacts system performance. Changing it to 'Regular' causes the screen to be updated every 10 seconds, and changing it to 'Slow' results in updates every 60 seconds. 'Disabled' stops the updates, resulting in the fastest system performance, but you will have to manually reload the screen or click the 'Refresh' button. Fast screen updates especially impact the speed of parity checks/builds and drive rebuilds.
    • Check the disk temperature thresholds and disk utilization levels. These settings generate warning notifications if exceeded, and if they are too low for your general usage, you will get more notifications than desired.
    • It is best to leave the temp setting at Celsius, as that is how they are reported by the drives and sensors. If you do change it to Fahrenheit, make sure you adjust the disk temperature thresholds too, or you will receive a LOT of 'over temp' warnings!
    • As always, make sure you click the Apply button!
  • Notification Settings
    • This is where you set up email for notifications, and this is where you control the notifications, which messages go to the webGui, which ones are emailed, and which ones are sent to other notification agents.
    • Lots of settings here! Make sure you have Help turned on!
    • You can setup custom notifications to go to third party services, with built-in support for Pushbullet, Pushover, Prowl, and Boxcar. For more information, please see 3rd Party Notification Services.
  • Scheduler
    • Currently, the items that can be scheduled here are the periodic parity check and the Mover. There may be more in the future.
    • Enable the parity check and set the scheduling as desired.
    • The general recommendation is for a monthly parity check.
    • If you prefer a more custom schedule, select 'Every' (instead of 'Monthly'), then customize as desired. I prefer every other month, so I selected 'Every' then checked alternating months.
    • The Mover settings only show up if you have enabled User Shares. Mover settings are essentially the same as before, set the frequency and days and time when you want it to run, and whether you want Logging enabled. There's also a Move Now button, to manually start the Mover at any time.
  • User Utilities
    • This is where plugins you add will put their settings pages, system plugins such as CacheDirs, System Temp, S3 Sleep, etc.
    • You may wish to proceed now to the Dynamix Plugins section below, some of which will add their settings icons here.
    • Some like System Temp already have good help available.

More Tips

  • CPU speed and power saving workaround
    • The newer Linux kernels have automatic CPU frequency step down when more CPU speed is not needed, saving power and heat. But, if your CPU is an Intel Haswell or possibly an Ivy Bridge, including most Xeon's, then there is a frequency scaling issue with the intel_pstate driver, and it needs to be disabled.
    • It's nothing serious, just means the CPU won't power down to lower frequencies when idle, so you may pay a little more in power costs. It will not hurt you in any other way.
    • To regain the CPU frequency stepping down, edit syslinux/syslinux.cfg on the flash drive, and insert intel_pstate=disable in the append lines.
    • Easy way to edit syslinux.cfg - browse to your unRAID Main screen, click on your Flash drive, and drop down to the Syslinux Configuration section! Make sure you click on the Apply button.
    • You will want to change these:
    append initrd=/bzroot
    append initrd=/bzroot unraidsafemode
    append /xen --- /bzimage --- /bzroot
    append /xen --- /bzimage --- /bzroot unraidsafemode
    • To these:
    append intel_pstate=disable initrd=/bzroot
    append intel_pstate=disable initrd=/bzroot unraidsafemode
    append intel_pstate=disable /xen --- /bzimage --- /bzroot
    append intel_pstate=disable /xen --- /bzimage --- /bzroot unraidsafemode
    • You can monitor the current CPU frequency for each core on the Dashboard.
  • Cache Pool
    • This is a new feature of v6, where you can now assign multiple drives as a Cache Pool, not just a Cache drive. It uses BTRFS features to provide data redundancy, so that your data on the Cache Pool will be just as safe as data on the parity protected data drives. See the Cache Pool illustration.
    • To use it, you first have to make room for more Cache drives, by adjusting the slot counts. Browse to the Main screen and Stop the array, then decrease the slot count for data drives and increase the slot count for Cache drives, then assign your Cache drives. When you Start the array, you should be able to format them. Then you will probably have to Stop the array once more and Start it again, to make the new Cache Pool fully available. Use it just like you use a single Cache drive, at /mnt/cache.
    • Drives in a Cache Pool must all be formatted with BTRFS, so if you have a current Cache drive, you may have to move all files off it first.
    • By the way, there is a guide to BTRFS usage, called the Btrfs Quick-Start Guide. It's unfortunately very outdated, and most of its procedures are now performed automatically from the webGui, but it does have a lot of related technical info.

Research and decision making

We suggest you start by watching the LimeTech demo video of unRAID OS 6!

Plugins, Dockers, and VMs

Previously, you enhanced your unRAID system with plugins and addons and scripts, but those are generally no longer compatible with unRAID v6. Only a few scripts are still compatible, such as Preclear and UnMENU (but not most UnMENU addons). Instead, v6 introduces a number of technologies that are both exciting and a little daunting. Much or all of it may be new to you, so there is going to be a learning curve, but we promise you that it will be worth it. We will try to point to the best reading, the best guides ...

In v5, if you wanted to run a Plex Media server on your unRAID machine, you installed the Plex plugin. In v6, you can still do that, but there are new technologies available that have special advantages that are worth learning about. unRAID v6 adds easy to use Docker containers, which are independent environments for loading mostly pre-configured applications, ones that can be stopped and started independently, and can completely crash without affecting ANYTHING ELSE. unRAID v6 also adds support for true virtualization via the KVM hypervisor, now included with unRAID. By creating or using pre-made virtual images, you can add independent environments that can run almost anything, such as Ubuntu, Mint, Debian, Windows XP/7/8/10, etc! So now you have 3 choices for your Plex server, install the Plex plugin, or a Plex Docker, or a VM with Plex. Decisions, decisions ... No hurry though, we suggest you learn more about them all first.

Simplistically, plugins are the light weight tools, and VM's are the heavy weights where you need a complete OS and not just an app. Docker containers are the hybrids with some of the best features of both.

Here's what is recommended by LimeTech and the unRAID community:

  • In version 6, plugins are intended to only be used as part of the basic NAS function. Anything which is unrelated to this core NAS functionality is intended to be installed either in a Docker Container or in a virtual machine (VM) environment, because they provide much better isolation and stability. Plugins are still useful, but for system level facilities, and to extend the NAS functionality.
  • If you choose, you can still install applications as plugins, but it is no longer recommended, the Docker approach is preferred. For example, you can install Plex as a plugin, but what happens if it crashes? As a plugin, it would probably crash your unRAID server too. But if you had installed Plex in a Docker, then only the Container would be down, and could be restarted, while your unRAID NAS was unaffected!

Very good reading -

Learning about Dockers

There is a lot that could be introduced and explained here, but we are going to point to what has already been written!

Learning about Virtual Machines

And there is a lot that could be discussed and explained here, but we are going to point to what has already been written!

Hardware Recommendations
  • In general, the more features you install, the more memory you will need. The System Requirements section of the unRAID V6 Manual has a pretty good discussion of CPU, memory, and other needs for successfully handling your projected system requirements, whether you stay lean and mean, install various Dockers, or add VM images. The section is young yet, so as experience grows, it will probably be refined over time.
  • Dockers will use far less RAM than VM based solutions.
  • LimeTech's Hardware Recommendations for System Builders page is a great resource, when you are considering what you want to do with your v6 system, and whether you may need to upgrade any of your hardware, add more memory, etc.
  • V6 RAM usage - A few users mention their RAM usage

Adding software to your server

General recommendations

  • Start by installing the system plugins you need, those not already built-in. They are probably listed in the Dynamix Plugins section and the Other Plugins section below it.
  • If you have not already done so, turn on Docker support, and add the Community Applications plugin. It will automatically load all of the unRAID community repositories and all of their containers, and with one click keep them updated (they are growing and improving every day).
  • Decide what Docker containers are right for you, and install and configure them, one at a time.
  • If you want to load operating systems such as Windows or anything else that's very graphical, install a selected VM or two.
  • You may want to investigate the capabilities of passing hardware through to a VM to get best performance. Note however this only works if your hardware has support for the relevant virtualization capabilities so you may need to do some research to see if this is possible on your system.


The Plugins page is a powerful addition to version 6 and serves a dual function, both to add, update, and remove plugins, AND to upgrade the GUI and the unRAID Server OS itself! The Installed Plugins page lists all of the plugins currently installed, plus the Dynamix webGui and the unRAID server, with all of their versions. The Install Plugins page is for adding new plugins.

  • To check to see if any updates are available for installation, simply click on the Check for Updates button. If any are available, you will see an Update button, to download and install its package. NOTE: if you do update the base unRAID Server OS through this page, you will have to reboot the server to complete the update!
  • The Install Plugins tab is the preferred method to install plugins in v6. Doing it this way allows you to manage your plugins through the GUI rather then using the command line in a Linux shell or in a Windows Explorer session. You will need the URL of the plugin to install it, or you will have to download the .plg file and save it to the Flash drive, but NOT to a plugins folder! Using the URL is definitely the easier of these two methods! Some of the most popular plugins are a part of Dynamix, and covered in the next section. If you want to see how this install process works, pick one of them and install it now.
  • Once you install a plugin, look on the Settings page for the plugin's configuration icon, in the User Utilities section. You will be able to use the GUI to configure any plugin that has been designed to be used with v6. Many plugins do require configuration after installation, so always check on the Settings page for the configuration page of any plugin that you install. Make sure you turn on the new Help feature, by clicking on the Help button in the upper right. Not every plugin has added Help, but if it's there, it's very 'helpful'!
  • To remove a plugin, click the check box to the left of the plugin's Remove button, then click the Remove button.
  • To see the change log for a plugin, click on the little blue circle with the i, next to the version.

Dynamix Plugins

  • Installation
    • To install Dynamix plugins, please see Dynamix - V6 Plugins, where they are all listed with their installation URL's. Use cut-and-paste to copy the URL of the plugin you want, and paste it into the Install Plugins page.
    • Note: in v5, you copied plugins to a plugins folder. Do NOT do that in v6! Always insert the plugin URL in the Install Plugins box, or browse to where you stored it. Just don't store it in a plugins folder!
    • Note2: the original Dynamix Disk Health and Email Notifications plugins are now built in!
  • CacheDirs - forces dir entries to stay cached, allowing drives to spin down
    • It is called Dynamix Cache Directories on the Plugins page, and Folder Caching on the Settings tab.
    • If you have been running CacheDirs from the go file, that won't be necessary any more, and you will want to install this plugin instead to get the same benefits.
    • After you install the Cache Directories plugin, go to the Settings page, click the Folder Caching icon, first enable the Folder caching function, then configure it as desired, and click the Apply button.
    • If you were running it in v4 or v5 and want to find the old settings you have been using, refer to your go file in the config folder of your v4 or v5 backup, and look for the cache_dirs command line.
    • It defaults to including all top level folders, if you don't specify the Included folders. There is a small bug in the current version that may cause some folders to not be cached some of the time, if set to All folders (nothing set in Included folders). It is therefore strongly recommended (you're probably tired of all these 'strong recommendations'!) that you do select the exact folders you want cached. Just click in the field box, and a list of all top level folders will be presented for you to check or leave unchecked. Only check those that it would be useful to cache, because caching takes memory, no need to waste it!
    • CacheDirs has a couple of small but hidden side-effects that may or may not be suitable for your v6 installation. Both of these system tweaks were added originally to CacheDirs to allow users to run successfully in only 512MB. That's rarely necessary any more.
      • CacheDirs modifies the process virtual memory limit, uses ulimit to set it to '50000' for 64 bit systems like unRAID v6 ('5000' for others). The Linux system default is 'unlimited'.
      Since v6 users generally have plenty of memory, and to avoid any possible side-effects, it is suggested to add the parameter -U 0 (that's a capital U and a zero) to the User defined options field on the Folder Caching settings page. Setting it to zero keeps CacheDirs from modifying it.
      • CacheDirs modifies vm.vfs_cache_pressure, a system parameter governing how aggressively the file and folder dir entries are kept in a cache. The Linux system default is '100', which is considered a "fair" value. Lower values like '1' or '10' or '50' will keep more dir entries cached, '200' would allow them to be more easily dropped, resulting in more drive spinups. The most aggressive would be '0', but unfortunately it may introduce a small risk of out-of-memory conditions, when other memory needs cannot be satisfied because dir entries are hogging it!
      By default, CacheDirs sets it to '10', which is a good value for most users. If you set it to '100', then it will remain the same as the Linux default value.
      If you wish to change it, add a -p # (that's a lowercase p and a number) to the User defined options field on the Folder Caching settings page. For example, to set it to more aggressively protect your cached dir entries, enter -p 1 in the options field. To avoid any possible side effects, add the parameter -p 100, which will restore it to the system default.
    • Most users should leave Scan user shares set to No. Since the User Shares are created and managed in memory, it makes little sense to cache them in more memory!
    • Except for those already mentioned, the rest of the fields are fine with their default values.
  • S3 Sleep - puts the system in a low energy state if no activity (if your system supports it)
    • Reports are that if you had this running perfectly in v5, there is no guarantee it will work perfectly in v6, without changes, as there have been numerous system changes
    • Replacing the NIC has worked for some, namely an Intel gigabit adapter.
    • You may have to set up start and stop scripts to run specific commands before and/or after s3-sleep. Please browse through the entire Dynamix V6 Plugins thread.
  • System Temp - displays CPU and motherboard temps (if your system supports it)
    • You will need to click the Detect button first, to let it identify what sensors you have and what modules/drivers are needed and available.
    • Then click the Save button to save it. This will ensure that the selected drivers are automatically loaded upon a system reboot.
    • If you would like to use the drivers now, rather than after the next boot, click the Load Drivers button to make them active.
    • Now select the most appropriate sensor for each of the CPU and motherboard temps. Original documentation of your motherboard may be helpful here. Click Apply to activate the sensor display.
    • If your motherboard has fan controls, then these can be made viewable too. At the moment only a single fan can be displayed though.
    • Temps should now be visible on the bottom status line of the Main page.
    • Sensor creation can be undone by selecting Not used, then click Apply.
  • System Autofan - more sensor-based controls for system fans
  • Active Streams - show in real-time any open (shared) streams on your system.
    • Streams opened through SMB, AFP or Plex will be displayed in the table together with the receiver (user).
    • By default the IP address of the user is displayed in the overview. It is possible to associate a name with a particular IP address for easier recognition. The tab User Names manages creation of these relations. Any new IP address seen, will be automatically added to the list.
  • System Info - gives detailed information about your system hardware
  • System Stats - graphs your hard disk utilization and system resources

Other Plugins

The following lists the plugins that seem to be the ones that are most commonly installed based on mentions in the forum. It is not an exhaustive list of the available plugins.

  • Powerdown
    • Same Powerdown plugin as before, updated for v6. However, the built in powerdown has improved and you may not need this plugin any more, unless you use some of its added functionality.
    • A new feature was added, support for start and stop scripts to control special needs of certain plugins, scripts, and VM's. See the support thread.
    • Installation URL is https://github.com/dlandon/unraid-snap/raw/master/powerdown-x86_64.plg.
    • Support thread is here.
  • NerdPack
    • This plugin includes command line tools for advanced users. Since it includes screen, other users will also be interested in installing it, typically for use with PreClear but also for use when converting drive file systems or other long command line jobs.
    • Tools included are: iftop, iotop, screen & utempter, lshw, kbd, inotify-tools, cpio, unrar, bwm-ng, strace, git, lftp, subversion,.
    • Installation URL is https://raw.githubusercontent.com/eschultz/unraid6-nerdpack/master/NerdPack.plg.
    • Support thread is here.
    • A helpful guide to using screen is Screen Tips.
  • overbyrn plugins
    • overbyrn has v6 plugins for NZBGet, SSH (enhances the default SSH in v6 by allowing multiple users and finer access control), Denyhosts, Dropbox, Beets, LMS, and possibly pyload.
    • Make sure you install the V6 version of the plugins, not the v5 version!
    • To install, right-click on the v6 link for a plugin, copy the link address (begins with 'https' and ends with '.plg'), then paste it into the URL input box on the Install Plugins tab.
    • Support thread for all overbyrn plugins is here.
  • PhAzE plugins
    • PhAzE has v6 plugins for CouchPotato, Headphones, Maraschino, Sonarr, SABnzbd, SickBeard, SickBeard_alt, Emby Server, Plex Media Server, NZBmegasearcH, Mylar, Transmission, FlexGet, Serviio, Subsonic, BitTorrent Sync, FileBot, PlexConnect.
    • Make sure you install the v2 plugins, which are the defaults.
    • To install, right-click on the plugin link, copy the link address (begins with 'https' and ends with '.plg'), then paste it into the URL input box on the Install Plugins tab.
    • Support thread for all PhAzE plugins is here. It is currently 122 pages long, make sure you read every word! Just kidding!
  • SNAP - mount and share drives outside of the unRAID array
    This is now deprecated and is being superseded by the new Unassigned Devices plugin above.
    • Currently, SNAP does have at least one feature not yet in Unassigned Devices, the ability to schedule a script using cron. But further development appears to have stopped and it is likely this capability will shortly be added to the Unassigned Devices plugin.
    • Installation URL is https://github.com/dlandon/unraid-snap/raw/master/snap-x86_64.plg.
    • Support thread is here.
    • An old support thread (for v5!) is here, with much helpful information, but DO NOT install anything from this thread, as it will be 32 bit only!
    • For mounting NTFS drives, you will need ntfs-3g support via one of the plugins above that provide it.
  • There are more plugins not yet listed above. Please see the Plugins forum.

Obsolete Plugins

  • These DO NOT WORK with v6!
    • Control Panel - great for v5, but not compatible with v6
    • Boiler and Trolley
    • ANY plugin used in v4 or v5 without a v6 counterpart. They were ALL 32 bit, and cannot be used in v6.
    If it is not specifically stated that it has been updated for v6, then assume it will not work!
  • These are not needed, because they are now built in. Installing them may interfere with the built-in implementations.
    • Dynamix Disk Health
    • Any plugin or script providing email support
  • There may be others too


  • The reference information for Dockers (guides, tutorials, videos) is located above in the Learning about Dockers section.
  • Make sure you install the Community Applications plugin (in the Other Plugins section above). It will make it easy to see all of the Docker Containers available to you, and install them.
  • Here's a good 'getting started' post, for first-time Docker users.
  • PLEASE read the Docker FAQ, it will help you avoid some early pitfalls. While you are there, check out the link to the binhex Docker FAQ, as it has additional very helpful info for new Docker users.
  • Important Note: the Docker image file and various Docker folders are often saved to the Cache drive, but there is one thing you need to be careful of. Most users have User Shares turned on, and if you do then the Mover process is going to try to move files and folders off the Cache drive, to a data drive. It assumes that any top level folder on any data drive (including the Cache drive) is a Share folder. To avoid that, here are the rules for the Mover -
    • it does not move files at the root of the Cache drive
    • it does not move root folders IF those folders are configured as Cache-Only shares
    • it does not move folders whose name begins with a period (in Linux by convention, file or folder names beginning with a period are considered 'hidden' )
  • What we recommend is to configure the Docker image file in the root of the Cache, where it will be safe, and configure all Docker folders as Cache-Only shares. If you forget, the Mover may move them off the Cache drive! Some examples -
    • cache/docker.img
    • cache/appdata/Plex
    • cache/appdata/couchpotato --> make sure you set the appdata share to be Cache Only!
  • Convert from PhAze's Plex Plugin to needo's Plex docker - How one user moved their Plex installation to a Docker
    • This is a good example of the move from a plugin to a Docker.
    • It's a little dated though. If you install (as recommended!) the Community Applications plugin, then you don't need to install the template repository in his Starting Docker section. And it's probably best to create the Docker image at 10GB or 20GB, rather than his 4GB.

VM images

Go file items

  • Optimizations from the past
    • 'blockdev --setra 2048' loop
      • Unknown if this is advantageous in v6.
    • Others???
  • UnMENU
    • Because UnMENU is written in AWK, a scripting language, it is compatible with v6. However, many of the UnMENU addons are not, because they are 32 bit code. UnMENU has been updated to recognize what is not compatible, so the UnMENU Package Manager should only show you addons that ARE compatible.
    • Some of the nice features of UnMENU are now built into v6, such as email notifications and UPS support. Therefore, depending on your usage, UnMENU may not be as useful to you any more. MyMAIN is just as useful, still has features no other 'Main' screen has.
    • The installation instructions for UnMENU are on this page. To start the UnMENU server each time you reboot, add /boot/unmenu/uu near the bottom of the config/go file on your flash drive.
    • Support thread is here.
  • Console monitor configuring
    • The Linux command setterm has moved from /bin to /usr/bin, so if you had any setterm commands in your old go file (executed by /bin/setterm), you will need to adjust the path. Here is an example that sets the monitor to blank the screen after 10 minutes without activity, then go to standby mode (VESA based) after 30 minutes of no activity.
/usr/bin/setterm -blank 10 -powersave powerdown -powerdown 30
  • If you find that the text on the console is too limited with its default setting of 80 characters by 25 lines, you can change it to 80 characters by 60 lines by editing syslinux/syslinux.cfg on your flash drive. Add the parameter vga=6 to the append lines. Example:
append initrd=/bzroot vga=6
Easy way to edit syslinux.cfg - browse to your unRAID Main screen, click on your Flash drive, and drop down to the Syslinux Configuration section! Make sure you click on the Apply button.
Note: if you cut and paste either of the above sample commands, you will discover double blanks between the parameters. The extra blanks are harmless, just there to improve the visible separation on this wiki page.

Other packages

It still works to put packages into /boot/extra. They will be automatically installed at boot time. Remember, they MUST be 64 bit packages.

System Scripts

  • Preclear - thoroughly tests and prepares drives for unRAID
    • Script name is preclear_disk.sh. Works with v6, but make sure you are using the latest, at least Preclear v1.15.
    • Unofficial Faster Preclear - an alternate version modified to be dramatically faster in the post-read (carefully follow the instructions in the included readme.txt)
    • Preclear Plugin - in beta, but this plugin is now preferred; requires the manual installation of either preclear_disk.sh or Unofficial Faster Preclear.
    • [Not needed with Preclear Plugin] If you wish to use the screen module, you MUST use the 64 bit version, now available in the NerdPack Plugin, listed above.
    • The -A option is no longer needed, the correct alignment on large disks is automatically set.
    • Support thread is here.
  • CacheDirs - forces dir entries to stay cached, allowing drives to spin down
    • Script name is cache_dirs, version should be v1.6.9. Works with v6, but plugin recommended.
    • A Dynamix CacheDirs plugin (called Dynamix Cache Directories) is now available within the Dynamix webGui. If you have been running CacheDirs from the go file, that won't be necessary any more, but you will want to install the plugin to get the same benefits.
    • Please see the CacheDirs plugin above, in the Dynamix Plugins section.
  • Others???

Other Topics

File systems

unRAID OS 6 now has three file system choices for formatting unRAID drives with, with more promised in future versions. Except for the Cache Pool, you can format any drive with any file system, mix and match them as you wish. If you setup a Cache Pool, its drives must be formatted with BTRFS.

How do they compare? Here's a short summary of the differences:

  • ReiserFS seems to be reaching end-of-life, so there are likely to be support issues going forward on new Linux kernels. LimeTech needed to position themselves with an alternative for the future. Having said that, the reiserfsck tool seems to be capable of recovering from even extreme levels of corruption and has served unRAID users very well. There appears to be no immediate need to switch, so users can leave their drives in ReiserFS format for now, and consider switching to one of the newer file system types when it is convenient.
  • XFS is a mainline Linux file system that is widely used and can thus be considered to be well-tested and supported for the foreseeable future. The recovery tools also seem robust and stable. However, unRAID users do not yet have much experience with how well it will handle extreme file system corruption. Initial feedback has suggested that XFS is extremely stable and probably performs better than ReiserFS when used on data drives. XFS is now the default format for data drives in unRAID 6.0.
  • BTRFS is a more modern and advanced file system than XFS and has functionality to protect against 'bit rot' type data corruption (as well as other advanced features). It is not as well-tried as XFS and the recovery tools are not as good. Having said that, it looks like it could become a preferred filing system in the Linux world going forward, if the main Linux distributions decide to adopt it. If you want to make use of the new unRAID 'cache pooling' feature, then the BTRFS format becomes mandatory for the cache drive(s). BTRFS is now the default format for the cache drive(s) in unRAID 6.0 (although users who only want a single drive as their cache have reported they get better results with XFS).

There has been considerable discussion of this in the unRAID forums. Try searching there for "reiser xfs btrfs", and you will find a lot of opinions on all sides of the pros and cons of each file system.

How do you set or change the file system format of a drive?

  • If there are files on the drive, you don't(!) unless you don't care if you lose them. Formatting a drive removes all of the data currently stored on it. (However if you do this by accident, there are recovery tools that may or may not be able to recover most of the files.)
  • There is a global setting that you can change in the Disk Settings section of the Settings page, see above. It governs the default that all new drives will be formatted as, unless you change it for a specific drive. The unRAID v6 file system default now starts as XFS.
  • You can set how a specific drive will be formatted by clicking on the drive on the Main page, then changing the file system, PRIOR to starting the array and formatting it. If the array is currently started then you will not be able to change the format.

Converting Drives from ReiserFS to XFS

  • Should you or shouldn't you?
    • From the very beginning, all unRAID 32 bit releases have relied strictly on the Reiser file system, and it has been rock solid. As a journaled file system, it has done a very good job of recovering from power outages and resisting corruption. And if in extreme cases, corruption still occurred, its recovery tool has done an amazing job of recovering over 90% of files. The rest of the Linux industry has moved away from it, partly because its author murdered his wife and is now jailed, partly because support has necessarily tailed off, and partly because it has been surpassed by newer file systems. Recently, its primary maintainer made the questionable decision to rewrite parts of the code, and introduced a serious data corruption bug. While that bug has been patched, confidence in the Reiser file system has greatly dropped, as well as confidence in its maintainer. In addition, a number of users have suffered a serious CPU stall issue, where the only successful workaround is to convert all of their drives from ReiserFS to XFS, with absolutely no issues thereafter. Most v6 users do not have this problem, and are using ReiserFS trouble-free. LimeTech has reported they may have found a fix, so we await its arrival and testing. ** Fixed in 6.0Beta15 **
    • At this point, there is NO general recommendation as to converting existing Reiser drives, UNLESS you are having a known Reiser-related issue. Some feel it is a good idea to begin converting existing drives to XFS, but others do not think it is necessary, and may be an over-reaction to the previous now-fixed issues. At any rate, it does seem wise to consider a slow migration strategy, as drives are added.
    • It IS recommended that going forward, all data drives should be formatted with XFS, and the Default file system in v6 was changed by LimeTech to be XFS. In the future, that recommendation will probably change to BTRFS with its more advanced features, once it has gained a similar reputation for stability. But currently, LimeTech is shipping systems with drives that are formatted with XFS.
    • It's also recommended that a new Cache drive (or drives) should be formatted with one of the newer file systems. If you want to take advantage of the new Cache Pooling feature (using multiple Cache drives), then BTRFS is required.
  • A very important warning!
    Users are already taking advantage of the new file systems, buying large drives, formatting them with XFS, and migrating or consolidating data from older, often smaller drives onto their new XFS drives. There is a particular circumstance however, involving copying between a drive and a User Share, that can cause serious data loss. It is always safe to copy from disk to disk, but you should NEVER copy from disk to share or from share to disk if that disk might be a part of the share. If you are unsure, then don't do it! Copy from disk to disk, or from one share to a different share.
  • Suggested procedure
    • If after reading the above, you are still certain you want to convert all of your drives to XFS, then here are some recommendations.
    • A step-by-step method for converting all disks is found here, with additional discussion thereafter. The discussion includes comments on what are the best commands to use, but also see the rsync commands here.
    • The gist of it is:
    1. Prepare a new empty drive, formatted with XFS, that is as large or larger than the largest data drive
    2. Copy the entire contents of the largest Reiser-formatted drive to it, and check for a perfect copy
    3. Format that source drive with XFS, and continue with step 2, repeating steps 2 and 3 until done
    • When all drives are done, and the last Reiser drive re-formatted, you have a choice:
      • Correct all of the drive includes and excludes for all shares, plus all other drive references
      • Or use New Config to re-assign all drives back to their original drive number (marking parity as valid)
    • Methods and Tools
      • There are two main ways to do this, one from your favorite workstation using your favorite GUI tools, and the other from a console using command line tools.
      • Windows or Mac workstation
        • Advantage: use the tools you are comfortable with, the unRAID webGui for formatting drives and starting/stopping the array, and your favorite file manager for copying and verifying files and folders. And you can't mis-type a command at the command line!
        • Disadvantage: it's slower, as all data has to travel back and forth across the network between the two machines, instead of just between two drives.
        • Tools like Teracopy and Total Commander are easy to use, and have built in file verification options, but may not be able to transfer all possible file attributes and metadata.
      • Console or Telnet/PuTTY/screen session
        • Advantage: faster, no network involved in the data transfers
        • Disadvantage: command lines, they're trickier and must be typed exactly, and for many of us, they are not in our comfort zone
        • The rsync tool has file verification, and can transfer all file attributes and metadata.
        • It is strongly recommended that these commands be run at the console of your unRAID server or within a screen session (see the NerdPack plugin above). However, if you don't and the copying is interrupted, repeating the rsync command should pick up where it left off.
        • The recommended copy command is: (this copies all files and folders from one drive to another)
        rsync -avPX /mnt/disk15 /mnt/disk5
        The sample command above copies everything from Disk 15 to Disk 5, so you will need to modify the drive numbers as needed.
        • The recommended verification command is: (this verifies that all files and folders were perfectly copied)
        rsync -nrcvPX /mnt/disk15 /mnt/disk5
        The sample command above verifies everything copied from Disk 15 to Disk 5, modify the drive numbers as needed.
        • If for any reason the verification finds errors, then rerun the last command without the n parameter. For example:
        rsync -rcvPX /mnt/disk15 /mnt/disk5
        These verification commands use the c parameter (checksumming), so they take quite a bit longer than the straight copy of the first rsync command.

Files on flash drive

Here are the files and folders on the flash drive prior to v6.0.0, and those which must be deleted, and those which are safe to bring forward into v6.

All files and folders are listed as in the root of the flash drive (e.g. /bzimage, /config/super.dat). On the unRAID server, they are actually at /boot (e.g. /boot/bzimage, /boot/config/super.dat). Some files and folders may not exist in your installation, that's OK. unRAID v6 will add additional files and folders that may not be listed below.

bzroot - replace with v6.0.0
bzimage - replace with v6.0.0
license.txt - replace with v6.0.0
make_bootable.bat - replace with v6.0.0
make_bootable_mac - replace with v6.0.0
memtest - replace with v6.0.0
readme.txt - replace with v6.0.0

syslinux.exe - delete (all syslinux files have been moved to syslinux folder)
syslinux.cfg - delete; optional, move customizations into syslinux/syslinux.cfg
menu.c32 - delete
ldlinux.sys - delete
ldlinux.c32 - delete
*.key - move to /config

/custom - delete, including all files and folders
/extra - delete, including all files and folders
/logs - keep
/logs/* - keep or delete; may wish to archive old logs
/packages - delete, including all files and folders
/syslinux - keep
     syslinux.cfg - replace all older ones with v6.0.0 syslinux.cfg
/unmenu - keep or delete
/config - keep
     /plugins - delete, including all files and folders
     /plugins.stock - delete, including all files and folders
     /shares - keep all files; safe

     go - replace with stock go from v6.0.0 (optionally, add selected customizations from old go to new, after upgrade completion)
     ident.cfg - keep; believed to be safe
     network.cfg - keep; believed to be safe
     share.cfg - keep; however it's not backward compatible
     smb-extra.conf - keep
     drift - keep
     timezone - unknown, may not be compatible ??
     domain.cfg - keep
     docker.cfg - keep
     *.key - keep

     disk.cfg - delete if clean install or from earlier than v5.0-beta6
     super.dat - delete if clean install or from earlier than v5.0-beta6
     passwd - delete if clean install or from v5.0-beta2 or earlier
     smbpasswd - delete if clean install or from v5.0-beta2 or earlier
     secrets - delete if clean install or from v5.0-beta2 or earlier
     shadow - delete if clean install or from v5.0-beta2 or earlier

Alternate no-format procedure

  • This section is only for expert users who are certain they don't want to re-format, and are confident they can deal with any issues that may arise.
As stated above, our strong recommendation is to re-format your flash drive. If you plan to re-format the drive as recommended, then go back to the next section (Performing the upgrade), but if you are a veteran unRAID user who refuses to re-format, then the following information should be helpful.
  • Optional, create v5 folder
    • This is an optional step, not actually required if you made the complete flash backup as instructed above, but if you think you may want the option to quickly revert to your current v5 installation, then ...
    • On your unRAID boot drive, create a v5 folder and copy the following folders to it (if they exist) - config, syslinux, extra, packages, custom, plugins
    Note: as the backup note above says, make sure the array is stopped first, else a parity check may be started on first v6 boot.
    • Then also copy to the v5 folder the following files from the flash root - bzroot, bzimage, ldlinux.sys (it's a hidden file), readme.txt, make_bootable_mac, make_bootable.bat
    • If your syslinux files are still in the root of your flash drive, then move all of them to the v5 folder too.
    • To revert from v6 to this v5, you will copy these folders and files back where they came from
    • Reminder: as long as there is a possibility that you may revert back to v5, you MUST NOT format any drives with the XFS and BTRFS file systems which are new options with v6! Once you prepare a drive with XFS or BTRFS, then you cannot go back to v5 without removing the drive from your system and reformatting it with ReiserFS.
    • Once you have decided v6 is working for you (we don't think that will take very long!), then you can remove all of your v5 files, and consider formatting drives with XFS or BTRFS.
  • Remove v5 features completely
    • Because v5 plugins are NOT compatible with the unRAID v6.x series, they MUST be removed. Failure to do so is going to produce strange and unpredictable errors on v6. Later, you will be able to install 64 bit versions of them.
    • For reference, use the section above, Files on flash drive, to help you decide which files and folders to keep and which ones cannot be kept.
    • This procedure will remove UnMENU if you are using it. While you can add it back in v6, and it works fine, the 32 bit addons will not work. Much of the extra functionality of UnMENU is now included in the new GUI.
    • Delete the entire contents of the following folders (if they exist) - extra, custom, plugins, packages, config/plugins, config/plugins.stock
    Note: some of the folders above may have been created unbeknownst to you, and some of them may have files you did not put there! Make sure you check them, and delete any files you find in them!
    • The syslinux boot files used to be in the root of the flash drive, but have been moved to the syslinux folder. Delete any syslinux related files left in the root, such as syslinux, syslinux.exe, syslinux.cfg, menu.c32, mbr.bin, ldlinux.sys, and similar files, and any make_bootable files. If it exists, delete the contents of the syslinux folder.
    • Either replace your config/go file with the stock go file, or edit it and remove everything you have ever added (including UnMENU), except the bare minimum you are certain you require (you can add stuff back later!)
      • As you probably know, you can disable some line items by placing a pound sign (it acts as a comment symbol) at the beginning of the line, marking the entire line as a non-executable comment (easy to reverse!).
      • The stock go file is in the config folder of each distro, or you can cut and paste a copy of the following to config/go -
# Start the Management Utility
/usr/local/sbin/emhttp &
  • Perform the upgrade
    • Now you can proceed to Performing the upgrade, skipping the formatting and labeling steps of course.
    • Before you leave this section, check the notes below.
  • Additional Notes:
  1. There may be configuration details you wish to save and transfer to your new v6 installation, but it is best to start out with a completely vanilla v6 system, and test it and make sure it works correctly before beginning to add favorite tools and addons. You can always copy them back later, from your v5 backup.
  2. Experienced users may consider skipping a step or two. We recommend that you not skip the step to run make_bootable, as it does not 'damage' your existing flash file system in any way. It only upgrades the syslinux boot support. Of course, you will skip the formatting and labeling steps, if you are using this alternate no-format procedure.
  3. The v6 files are somewhat larger than the v5 files, so make sure there is sufficient room on the flash drive. This is a good time for some housekeeping, if you aren't going to re-format it.

Implementing Trim on SSD Drives

  • Many unRAID users are now adding SSD's to their system, especially as Cache drives to hold their Docker Containers and data. As demonstrated by this site, it's very desirable to either continuously or periodically Trim an SSD, for often greatly improved performance.
  • This is a temporary workaround to add a daily Trim for Cache drives that are SSD's and formatted with XFS or BTRFS, until LimeTech adds it themselves. As of this writing (v6.0-beta14b), it was not available yet.
  • It is not the preferred method, as it involves editing the go file, and LimeTech has begun actively discouraging that.
  • See How to Implement Trim on SSD Drives
  • Once LimeTech adds a Trim feature to v6, then you will need to remember to remove this entry from your go file.


Need help? Read me first!

For all V6 support, the 'read me' above has fairly complete guidelines. We really hope that users WILL read it first, as it should make it easier for helpers to help them.

As always, it starts by stressing the need for that syslog! In v6 there is a Diagnostics option on the Tools page that will capture all the system logs and key configuration and diagnostic information into a Zip file for downloading. Gathering this information should always be the first step when troubleshooting as it provides information about the current state of the system that may not survive a reboot. If you start a forum thread about a problem you are having, then attaching this Zip file is always a good idea to help those who are going to try and assist you.

It is requested that users who post about a problem but do not provide enough info, be informed of the Read me first! and the Diagnostics option.

Networking not working after upgrade

  • A few users may discover that after upgrading, networking no longer works, yet it worked fine before the upgrade. Usually, this is because they have multiple network NIC's. If you do have more than one network chipset (they could be onboard and/or addon cards), different Linux kernels may identify and set them up in a different order, and this can keep your unRAID server off the network after an upgrade.
  • By default, unRAID uses eth0 for network communications, in effect using whatever the kernel set up first as eth0. If you only have one NIC, then it's eth0 and everything is fine. Unfortunately, if you have more than one, the kernel has not always been consistent as to which one it identifies first, so your preferred NIC may be set up as eth1, not eth0. You should be able to see that in your syslog.
  • There are several ways to fix this. The easiest is to try moving the network cable to the other network connector. If it works, then it is the new eth0, and you will be back on the network almost immediately. However, if you prefer your server to use the same network chipset it already was using, then you will have to either remove the other network chipset (if it is an addon card), or disable it in the BIOS settings (if it is onboard).

Array will not start

  • If you have just upgraded and the system seems to be operational EXCEPT that you cannot get the array to start (it appears to begin starting, then reverts back to stopped), you should edit the disk.cfg file in the config folder of your unRAID boot drive. Look for a line matching the following:
  • If it is there, delete the line, save the file, reboot and try again to start the array.

unRAID not booting after upgrade

  • The BIOS of many computers tries to be 'helpful' when it notices a change in installed disk controllers or installed drives, and resets the BIOS order back to its defaults. Since this does not put the USB stick first in the boot order, it is actually a nuisance as you have to go into the BIOS settings to correct the boot order.
  • There is no consistency on BIOS boot settings about how the USB stick should be referred to. On many systems you need to treat as a HDD.
  • There have been cases (particularly on Mac's) where the make_bootable batch file does not write the boot files correctly. Trying it on another machine (or on a PC if you previously used a Mac) typically rectifies this problem.
  • You can ask in the unRAID forums if you seem to have a booting problem which is not one of the above. A screenshot of what happens will help with diagnosing what is happening.

Make_bootable may fail on a Mac

  • It's rare, but there are a few reports where preparing the flash drive on a Mac did not succeed, reason unknown. Taking the same flash drive to a Windows machine and preparing it there did succeed.

Docker containers losing their configurations

  • If you find that the configuration settings for you docker containers are periodically getting lost, then it is likely that you have them stored on the cache drive (typically under an appdata folder), and the contents of this folder have been moved to the main array drives. This will be because unRAID has automatically created a share corresponding to the folder name and assigned default settings which includes periodically running mover to put the contents on the main array disks. To rectify this do the following:
    • Go into the Shares tab and check the settings for the share corresponding to the folder storing Docker configuration files. Change the Use Cache setting to only.
    • Find which array disks have the folder corresponding to this share, and move the files back to the cache disk. Make sure when doing this you use the disk shares (cache and disk??) and not the user share.

Please Contribute

Knowledgeable users of the unRAID community are encouraged to correct and enhance this guide. Any insights you may have on upgrading to unRAID v6, and making the process smarter, faster, and easier are appreciated!

Feedback, suggestions, and corrections related to this guide can be given on the unRAID forum here.

Wiki page credits: bjp999, bonienl, dlandon, Frank1940, garycase, Harmser, itimpi, Jonp, limetech, lionelhutz, PhAzE, RobJ, SlrG, Squid, Stchas, trurl, Ulvan, WeeboTech, xxredxpandaxx, possibly others (please inform us of others to whom credit is due)