Difference between revisions of "Upgrading to UnRAID v6"

From unRAID
Jump to: navigation, search
(Install the unRAID upgrade)
(Install the unRAID upgrade)
Line 69: Line 69:
 
== Performing the upgrade ==
 
== Performing the upgrade ==
 
=== Install the unRAID upgrade ===
 
=== Install the unRAID upgrade ===
 +
 
* '''Notes:'''
 
* '''Notes:'''
 
# the official upgrade instructions are on the ''[http://lime-technology.com/getting-started/ Getting Started] page ('''Preparing your USB flash device''' section)'', and at the bottom of any of the V6 [http://dnld.lime-technology.com/beta/unRAIDServer-6.0-beta14b-x86_64.txt Change Notes].  This section is directly derived from them, but you may wish to refer to them for more detail.
 
# the official upgrade instructions are on the ''[http://lime-technology.com/getting-started/ Getting Started] page ('''Preparing your USB flash device''' section)'', and at the bottom of any of the V6 [http://dnld.lime-technology.com/beta/unRAIDServer-6.0-beta14b-x86_64.txt 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.
 
# 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'''
 
* '''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 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 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).
 
** 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 files'''
 
* '''Copy files'''
 
** If you have not already downloaded the v6 distro, go to the [http://lime-technology.com/download/ LimeTech downloads] page, and download the latest unRAID v6 zipped distro.
 
** If you have not already downloaded the v6 distro, go to the [http://lime-technology.com/download/ 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.
 
** 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.
 +
 
* '''Making the USB drive bootable'''
 
* '''Making the USB drive 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.
 
** 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.
Line 86: Line 90:
 
*** If using a Mac, double-click the file '''make_bootable_mac''' and enter your admin password when prompted.
 
*** 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.''
 
*** ''Note: during the process of running this script, the flash device may seem to disappear and reappear.''
 +
 
* '''Restoring Saved Configuration files'''<p>Now we will restore your saved configuration files.</p><p>''Note that if you want to start over, start with a completely fresh system, 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!  You still need to copy your '''.key''' file to the '''config''' folder, but you can skip the other copying here.''
 
* '''Restoring Saved Configuration files'''<p>Now we will restore your saved configuration files.</p><p>''Note that if you want to start over, start with a completely fresh system, 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!  You still need to copy your '''.key''' file to the '''config''' folder, but you can skip the other copying here.''
 
** unRAID V6 requires that the '''.key''' file be in the '''config''' folder, not in the root.  Previous versions allowed it to be in the root of the flash drive, but that is no longer true.  If you have multiple '''key''' files, it is best to make sure that only the correct one is in the '''config''' folder with the '''.key''' extension.
 
** unRAID V6 requires that the '''.key''' file be in the '''config''' folder, not in the root.  Previous versions allowed it to be in the root of the flash drive, but that is no longer true.  If you have multiple '''key''' files, it is best to make sure that only the correct one is in the '''config''' folder with the '''.key''' extension.
Line 94: Line 99:
 
** Then copy ONLY the files from your saved '''config/shares''' folder to the flash drive's '''config/shares''' 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 correctly done, you should have a '''go''' file in your '''config''' folder that has a size of 71 bytes.
 
** '''Do NOT restore any other files or folders, especially any plugin files!'''  If correctly done, you should have a '''go''' file in your '''config''' folder that has a size of 71 bytes.
 +
 
* '''Final Prep'''
 
* '''Final Prep'''
 
** 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.'''
 
** 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.'''

Revision as of 09:23, 16 June 2015


If you are still running any unRAID version prior to v5, then this guide assumes that you will upgrade to v5 first. Please see Migrating from unRAID 4.7 to unRAID 5.0.

In practice it may well be possible to go straight from an unRAID release prior to the 5.0.x series to version 6, but this is not something that there is much experience of so it is not known what the pitfalls falls may be. This guide therefore does not try to cover such scenarios

If this page looks too long to you, many users recommend Frank's short and sweet instructions here -> Upgrading unRAID from Version 5 to Version 6. This guide is intended to be more comprehensive covering more scenarios and highlighting possible pitfalls which is the reason why it is a lot longer.

This page is designed to help users of unRAID v5 successfully upgrade to v6, by using the many lessons learned by the unRAID community. 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 that is likely to help those who are trying 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.


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" (without the quotes, color is preceded with 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.

Important Considerations

  • 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!
  • 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 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 listed below. But again, we strongly recommend re-formatting!
  • Very important warning: if you think there is a possibility that you may revert back to v5, 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 to v5 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 v5 boot drive! You will either re-format it (strongly recommended!) or you will delete most of it.
  • If you want to bring forward setting from your current system then screen shots of the relevant pages giving the current settings are a good idea. Of particular importance is the one that shows the current drive assignments as you do not want to accidentally assign a data disk as a parity disk (thus destroying its contents). Make sure that these are saved somewhere you can access them for reference 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, most users can skip the next section and proceed to Performing the upgrade. The next 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.

Alternate no-format procedure

As stated above, our strong recommendation is to re-format your flash drive. If you plan to re-format the drive as recommended, then skip down 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 uninstalled for now. Failure to do so is likely to produce unpredictable errors on v6. Later, you will be able to install 64 bit versions of them.
    • 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.
    • If using UnMENU, go to its Package Manager and set all packages/plugins to not reinstall. If you do revert to v5, you will need to reverse this of course. It is quite likely that once you move to v6 the new GUI and the enhanced built-in functionality will mean that you will find that you no longer want to run unMenu.
    • Either replace your config/go file with the stock go file, or edit it and remove everything you have ever added, except the bare minimum you are certain you require (you can add stuff back later!)
      • You can temporarily remove some items by placing a pound sign at the very beginning of the line (it acts as a comment symbol), 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 -
#!/bin/bash
# Start the Management Utility
/usr/local/sbin/emhttp &

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 below. 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. v6 files are somewhat larger than 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.


Performing the upgrade

Install the unRAID upgrade

  • Notes:
  1. 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.
  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.
  • 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 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.
  • Making the USB drive 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.
  • Restoring Saved Configuration files

    Now we will restore your saved configuration files.

    Note that if you want to start over, start with a completely fresh system, 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! You still need to copy your .key file to the config folder, but you can skip the other copying here.

    • unRAID V6 requires that the .key file be in the config folder, not in the root. Previous versions allowed it to be in the root of the flash drive, but that is no longer true. If you have multiple key files, it is best to make sure that only the correct one is in the config folder with the .key extension.
    • Very important, you will be copying the files from only 2 folders of your saved v5 backup, and no others!.
    • However, we need to make sure that we do NOT restore the go file from your saved v5 backup unless you have never changed it from the default one. Rename the go in your saved 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 v5 config folder to the flash drive's config folder.Do not copy the folders or you may accidentally copy a 32-bit plugin which is incompatible with v6.
      Note: You may need to grant permission to overwrite existing files.
    • Note: 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 correctly done, you should have a go file in your config folder that has a size of 71 bytes.
  • Final Prep
    • 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..
  • Access to array disks and shares should be the same, from any station.

Meet the new GUI

  • Version 6 has an all new GUI (Graphic User Interface) for managing your server! While it may look similar 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 expanded even further to be able to completely manage your unRAID server.
  • All settings and configuration can be done from the new GUI. All 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. Monitoring your system is easier now through the Dashboard tab, the enhanced Main page, and the Stats tab. And extensive help is widely available, through the Help 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.
  • You will need to take 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!
  • Visit all of the available tabs now, and check the system out...

Configuring the Settings

  • Note: this section is based on the current set of settings (v6.0-rc6a at the moment). Because v6 is still in beta, changes are still being made, but we will try to keep this section updated.
  • As 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.
  • Make sure you turn on the new Help feature, 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 a bit of 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 revert back to v5, then you CANNOT format any drives with the new v6 file systems XFS and BTRFS! 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 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. This is not the same as how often the display is updated, that is controlled by a Display Setting, Page update frequency. It defaults to 30 minutes, and unfortunately is sometimes 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).
  • 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 and file name for the Docker file (holds the Docker system stuff), and an initial size for the file (it can easily be made larger, but it is not so easy to shrink it later). 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.)
    • 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!
    • 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'.)
    • 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
  • Network Services section
    • 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

Note: we suggest you start by watching the LimeTech demo video of unRAID OS 6!

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. If you choose, you can still install applications as plugins, but it is no longer recommended. 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.
  • 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:

  • First, add the system plugins you have been loading in v5. Their v6 counterparts are probably listed in the Dynamix Plugins section and the Other Plugins section below it.
  • Next, 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).
  • Then decide what Docker Containers are right for you, and install and configure them, one at a time.
  • Then if you want to load Windows or anything else that's very graphical, learn about and configure hardware passthrough, and install a selected VM or two.

Plugins

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 (apparently, most plugins will now be installed via this method), 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.
IMPORTANT! 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. If you choose, you can still install applications as plugins, but it is no longer recommended. For example, you can install Plex as a plugin, but what happens if it crashes? As a plugin, it will 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!
  • 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 v5 and want to find the v5 settings you have been using, refer to your go file in the config folder of your 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
    • Community Applications (was Community Repositories)
    • Unassigned Devices
    • NerdPack
      • This plugin includes tools for advanced users, but since it includes screen, many 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.
      • 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.
    • ntfs-3g - installs read/write support for NTFS
    • 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!
    • 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.
    • SNAP - mount and share drives outside of the unRAID array
      • SNAP is slowly being replaced 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.
      • 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 the ntfs-3g plugin above.
    • possibly others?
  • 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 it will not work!
    • These are not needed, because they are now built in
      • APCUPSD
      • Dynamix Disk Health
      • Any plugin or script providing email support
    • There may be others too

Dockers

  • 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.
  • 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 or the Cache drive is a Share folder. To avoid that, here are the rules - 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, and 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!
  • 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, rather than his 4GB.
  • All information on Dockers is located in the Learning about Dockers section.

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 (preclear_disk.sh, v1.15 or later; thoroughly tests and prepares drives for unRAID)
    • Works with v6, but make sure you are using the latest, at least Preclear v1.15
    • 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 (cache_dirs, v1.6.9; forces dir entries to stay cached, allowing drives to spin down)
    • 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

There are now (as of v6.0-beta14b) three file system choices available (more coming), for formatting unRAID drives with. 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.
  • XFS is seen as 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, so that is still a grey area.
  • 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.
  • 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, 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.

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.


Troubleshooting

  • 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! 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). Update: in v6, it looks like you *may* (unconfirmed as yet) be able to change the preferred NIC by selecting eth1 or eth2 instead! More information needed.


Please Contribute

We encourage knowledgeable users of the unRAID community to correct and enhance this guide. We appreciate any insights you may have on upgrading to unRAID v6, and making it smarter, faster, and easier!

Please place all feedback, suggestions, and corrections related to this guide 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)