Upgrading to Unraid 6
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, based on the many lessons learned by the Unraid community. The guide is intended to be comprehensive, covering most scenarios and pitfalls, but the basic process is simple if you work through the sections one by one. There are a number of steps to follow below, designed to help make the migration experience more predictable and less stressful. It includes 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.
There is also an official LimeTech plugin that performs the update from v5 to v6. This method is worth a try, if the thumb drive is not easily accessible, as the whole procedure takes place while Unraid is running. Worth a try, because the plugin is not totally perfect. When updating from older releases of v5, there might be a reboot issue as the location of some files changed in late v5 and v6 releases. In this particular case see here.
The following guide covers all other update methods and provides valuable additional information about changes introduced with Unraid 6.
Whether you use the plugin or not, it is recommended to read the guide!
- 1 Before the upgrade
- 2 Performing the upgrade
- 3 Research and decision making
- 4 Adding software to your server
- 5 Other Topics
- 6 Troubleshooting
- 6.1 Need help? Read me first!
- 6.2 Networking not working after upgrade
- 6.3 Array will not start
- 6.4 Unraid not booting after upgrade
- 6.5 Make_bootable may fail on a Mac
- 6.6 Docker containers losing their configurations
- 6.7 Disks shares lost
- 6.8 No User Shares
- 6.9 Disk controller compatibility issues
- 6.10 Audio and Video Dropouts
- 7 Please Contribute
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 ...
- Login or Telnet into your Unraid console
- Type "grep --color lm /proc/cpuinfo" (type it without the quotes; color is preceded by 2 hyphens)
- Look for lm in the CPU flags listed
- 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.
- There are reports that a very low-speed single-core CPU struggles in Unraid v6, particularly with parity checks. While this is certainly not a blocker, you may wish to investigate whether your CPU socket will support a multi-core CPU upgrade. If so, they are quite cheap.
- There are also reports of dropouts when streaming audio and video with an onboard NIC (especially Realtek) and a low power CPU. You may need to disable the onboard NIC and add an Intel NIC. ,
Upgrade or Clean Install?
- The difference is not about whether you can skip formatting or not, but whether you can keep your current configuration and settings or not.
- If you are upgrading from ANY release before v5.0, then you will need to do a 'clean' install, essentially a fresh start, with all of your drives and data intact, but with little or no configuration.
- Note: This is a change from the past, where it was recommended to first upgrade to v4.7, correct any HPA's and drive identifiers, then upgrade to v5.0, make sure everything worked correctly, and re-enter your users and passwords and run New Permissions, then upgrade to the current v6. Now, we recommend skipping all previous version upgrades, with the one downside that you will have to re-enter almost all of your configuration, including drive assignments. PLEASE follow the instructions below carefully, especially about full backups and notes about your current settings and assignments.
- Here's a table of previous versions you may be running, and the recommended course of action -
ANY version prior to v5.0-beta6 -> 'clean install', then configure settings and drive assignments, then run New Permissions v5.0-beta6 through v5.0-rc8a .. -> 'upgrade install', then run New Permissions v5.0-rc9 through v5.0.6 ....... -> 'upgrade install' v6.0-beta1 through v6.0-rc6a .. -> 'v6 beta upgrade'
- How to do 'clean install'
- This is the required method for anyone running any version prior to v5.0-beta6, including all v4 releases. It is an optional method for anyone running a version from v5.0-beta6 or later, or anyone that wants to start over, start with a fresh configuration. All of your data will be safe, and you will probably not have to redo your parity drive either. But you WILL have to reassign your drives and re-enter all or most of your system settings, users and passwords.
- Except for a few files mentioned in the next note, you will NOT restore anything from your previous configuration except your license key file.
- There are a few configuration files that are safe to keep and restore, ident.cfg, network.cfg, share.cfg, and any .cfg files in the config/shares folder. These files hold your network settings and identification, and your share settings, and are safe to bring forward. They will help you get back on the network quicker! One caution, if you restore them and use them in v6, they cannot be reverted to v5 or earlier. If you wanted to go back to your previous version of Unraid, you would need to restore them from your old backup instead. That's another good reason to make a complete backup before you start!
- Proceed through the guide below, using the 'clean' instructions when present. Make sure you run the New Permissions tool, once drives are assigned and operational.
- How to do 'upgrade install'
- Proceed through the guide below, using the 'upgrade' instructions when present. If needed, make sure you run the New Permissions tool, once you are operational.
- How to do 'v6 beta upgrade'
- You do not need to follow this guide or redo your flash drive. However, there is a LOT of other information here that will be helpful, no matter what version you are currently running.
- Depending on which v6.0-beta or v6.0-rc you are running, there are certain steps that may be necessary. Unfortunately, some information below is vague, but this author does not have the first-hand experience to be more specific.
- If you haven't done so before, your license key file(s) MUST be moved to the config folder. It no longer works in the root of the flash.
- A license is required now, even for trial use. See the license key discussion a few paragraphs below.
- Early v6 plugins are not compatible and should be removed. This includes the dockerman files (Docker Manager), the VM Manager plugin, the Xen Manager, and any other plugin from the early days of the v6 betas.
- For those coming from v6 betas, we strongly recommend removing your plugins, config/plugins, and extra folders from your flash, then after upgrading install the current plugins you need.
- If you created a docker.img file with an earlier v6 beta, you probably will have to delete and recreate it. This FAQ entry may be helpful.
- Those who upgraded to early betas of v6 did not have complete instructions, and *may* have remnants of v5 on their flash drive. It's important that they be removed, because they often cause very strange issues. Please refer to the Files on flash drive section below, to help 'weed' your flash drive.
- If you are running a v6.0-rc or later, then you can upgrade through the Plugins page. All others must upgrade the old manual way, by downloading the release from the LimeTech downloads page and installing it the same way you always have. If for any reason the Plugins page link does not work, then you too must use the old manual way.
- 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 reformat 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 the 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).
- Note: If your flash drive is greater than 32GB, then you may have trouble formatting it properly, as FAT or FAT32. Try the guiformat.exe tool found here.
- 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.
- However, it is safe to copy network.cfg, ident.cfg, share.cfg, and shares/*.cfg (but no others!). These files will 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.
- 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 into 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! Take it back to your desktop station, and run make_bootable on it!
- 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 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.
- The first time you start the array after the upgrade, you may see SMART errors for one or more array drives. The upgrade DID NOT cause these errors! Previous Unraid versions did not have built-in SMART monitoring, so the errors were there but there was nothing to inform you of them unless you manually checked a SMART report. Unraid v6 monitors the SMART health of your drives and will notify you of problems.
- If your User Shares appear to be missing, it is probably an ad blocker or antivirus interfering, please see No User Shares.
- 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 that now, and once the array is running correctly, run the New Permissions tool. 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 4 and 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. Most of the UnMenu functionality has been incorporated into the GUI or into plugins you can add.
- 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.
- Note: If you are using an Adblocker as an add-in to your browser, you need to whitelist your Unraid server or it may not display some pages correctly.
- 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 anymore, 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 '300' (for 5 minutes) or '120' (for 2 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).
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/user/system/docker/docker.img or /mnt/disk1/docker.img.
- 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. 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.
- 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.
- 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.
- In v6.2, the network settings were revamped and more settings added, plus better support for multiple NICs.
- Global Share Settings
- This used to be called Share Settings, but has been renamed to reflect the global scope of this section. 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.
- Important change! As of v6.1, there is a new setting here, Enable disk shares, that may impact you. It defaults to Auto (options are Yes, No, or Auto). When set to Auto, it may cause your disk shares to be off. Please read the v6.1-rc1 announcement post, where this is fully explained, and what the options mean, and why this change was made.
- 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. Update: there is now a v6 plugin with NUT support!
- 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. By default, no users are configured, which disables the FTP server.
- 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. The first part of these settings only affects the look-and-feel of the GUI, while the second part defines thresholds for disk operational temperatures and utilization. Exceeding these thresholds results in sending of notifications (see Notification Settings).
- 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 may impact 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.
- The notifications function needs to be enabled for proper system monitoring, though the user may deselect any notifications to be sent.
- Click the Basic view switch in the upper right, and change it to Advanced view. This will open up even more options, including the SMART settings.
- It is recommended to uncheck Command timeout, and Reported uncorrectable errors too if you get errors with ridiculously large (and false) numbers.
- Add 199 to the Custom attribute number. If constantly increasing, this attribute (UDMA_CRC_Error_Count) is a good indicator of a bad SATA cable!
- 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.
- 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 'Custom' (instead of 'Monthly'), then customize as desired. I prefer every other month, so I selected 'Custom' then checked alternating months.
- The Mover settings only show up if you have a cache drive present and 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.
- 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, there are several things you can do.
- You can install the Tips and Tweaks plugin and change the CPU Scaling Governor.
- You can 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
- To these:
- append intel_pstate=disable initrd=/bzroot
- append intel_pstate=disable initrd=/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
Plugins, Dockers, and VMs
Previously, you enhanced your Unraid system with plugins, 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, Mac OS's, 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 lightweight tools, and VM's are the heavyweights 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!
- Unraid V6 Manual - has a good conceptual introduction to Dockers and VM's
- LimeTech's Official Docker Guide
- Docker Home Site - the place to learn about the Docker technology in general - not just the Unraid use of Docker.
- Docker Containers board - the Unraid forum for discussing all things Docker
- Using Docker - Unraid Manual for v6, guide to creating Dockers
- Noobie docker setup guide - one user's illustrated guide, plus a video guide
- Popular Unraid Docker Template Repositories and Containers - current list of Docker template repositories
- Dockerization of some popular applications - 63 page thread, and initially focused on needo's work, but has interesting discussions of Docker use, creation, and development
- Docker FAQ - some common questions and answers
Learning about Virtual Machines
There is a lot that could be discussed and explained here, but we are going to point to what has already been written!
- Virtual Machines - An introduction, from the V6 Manual
- A brief synopsis of virtualization terms and acronyms - Understanding terms like Hypervisor, KVM, HVM, VFIO, and QEMU
- Using Localized Virtual Machines - Unraid Manual for v6, guide to creating and working with VM's
- LimeTech Videos - a page of videos created by LimeTech, includes a number of very helpful videos on VM topics, installation and usage
- Virtual Machines - KVM forum - KVM on Unraid 6
- Unraid as Guest forum - ESXi, Hyper-V, etc
- VM Appliances forum - Preconfigured VM images
- 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
- 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).
- Install the Fix Common Problems plugin to audit your system, warn you of many issues, and notify you of updates to the system and your plugins and Dockers.
- 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 the 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. But you can also install plugins and Docker containers using the Community Applications plugin.
- 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 than 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. NOTE: If the Community Applications plugin is installed, then it will also handle displaying of all compatible plugins and installation of them.
- 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 changelog for a plugin, click on the little blue circle with the i, next to the version.
- 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!
- 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 the creation of these relations. Any new IP address seen will be automatically added to the list.
- Optionally, streams can be stopped from the GUI.
- 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 anymore, 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 anymore.
- 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.
- Local Master - supports detection of the local master browser in an SMB network.
- It will display an icon in the header at the top-right when Unraid is elected as local master browser.
- Under SMB Workgroup settings, it provides more information about the current elected local master browser.
- S3 Sleep - puts the system in a low energy state if no activity (if your system supports it); defines the conditions under which the system will go to S3 sleep mode; adds an unconditional 'sleep' button on the Array Operation page
- 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.
- Schedules - a front-end utility for the built-in hourly, daily, weekly and monthly schedules.
- It allows the user to alter the schedule execution times using the GUI.
- System Autofan - more sensor-based controls for system fans
- Allows automatic fan control based on the system temperature. High and low thresholds are used to speed up or slow down the fan. This is a new plugin and still under development.
- System Buttons - adds a one-click button to the header which allows for instant sleep, reboot, and shutdown of the system, or array start/stop.
- System Info - gives detailed information about your system hardware
- Shows various details of your system hardware and BIOS. This includes processor, memory, and sub-system components.
- Much of this information comes from the DMI (SMBIOS), and may be unreliable, as it's entered by the manufacturer.
- System Stats - graphs your hard disk utilization and system resources
- Shows in real-time the disk utilizations and critical system resources, such as CPU usage, memory usage, interface bandwidth, and disk I/O bandwidth.
- System Temp - displays CPU and motherboard temps (if your system supports it)
- Shows in real-time the temperature of the system CPU and motherboard. Temperatures can be displayed in Celsius or Fahrenheit.
- Your hardware must support the necessary probes, and additional software drivers may be required too.
- This plugin requires PERL, and this package needs to be installed separately.
- 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.
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.
- Community Applications
- All users should install this. If you have any interest or even curiosity about Dockers, then install this plugin!
- It is the App store for Unraid. It is designed to load the entire list of containers of the Popular Unraid Docker Template Repositories and Containers thread, plus info on all available plugins. The lists have been enhanced with categories, to make it easier to find the ones you are most interested in.
- Docker does not have to be enabled. After installation, a new tab will display called "Apps" which will display all of the available docker applications and plugins.
- Installation URL is https://raw.githubusercontent.com/Squidly271/community.applications/master/plugins/community.applications.plg.
- Support thread is here.
- Community Applications also handles the indexing and installation of all of the plugins compatible with v6.1 or later
- Fix Common Problems
- All users should install this. It is designed to find and offer up suggestions to a multitude of configuration errors, outright problems, etc, for numerous aspects of your Unraid server. Problems are reported in the syslog for easy analysis, and if notifications are on, you will be notified of issues as they are found. Scans are manual or automatic, scheduled as often as you like.
- Installation URL is https://raw.githubusercontent.com/Squidly271/fix.common.problems/master/plugins/fix.common.problems.plg. Easy way to install it is to use Community Apps.
- Support thread is here
- Unassigned Devices
- This is the successor to SNAP, which is no longer compatible.
- This plugin uses UDEV to mount and share disks that are not part of your Unraid array. Scripts can be edited and applied. It creates an Unassigned Devices section on the Main screen.
- Installation URL is https://github.com/dlandon/unassigned.devices/raw/master/unassigned.devices.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- Currently, it automatically installs support for exFAT, HFS, and ntfs-3g.
- Server Layout
- Wish you could quickly figure out where that problem drive is physically located? Then you want this plugin. Create a layout that resembles your server and its drives, and you'll never wish again that you had labeled all those drives first before you installed them into their dusty hidden slots!
- Installation URL is https://raw.githubusercontent.com/theone11/serverlayout_plugin/master/serverlayout.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- Preclear GUI
- This plugin allows Preclears to be run from the GUI, thus removing the main reason users had to go to the command line.
- Installation URL is https://raw.githubusercontent.com/gfjardim/Unraid-plugins/master/plugins/preclear.disk.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- 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.
- Some of the tools included are: iftop, iotop, screen & utempter, lshw, kbd, inotify-tools, cpio, unrar, bwm-ng, strace, git, lftp, subversion, and numerous others. More keep being added!
- Installation URL is https://raw.githubusercontent.com/eschultz/Unraid6-nerdpack/master/NerdPack.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- A helpful guide to using screen is Screen Tips.
- Useful Links
- Here's a very small but useful plugin, just a bunch of useful links, when you can't remember where they are yourself.
- Installation URL is https://raw.githubusercontent.com/Squidly271/UsefulLinks/master/useful_links.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- NUT - Network UPS Tools
- This plugin will install NUT (Network UPS Tools), which provides UPS control services for most UPS models. In particular, it supports almost all of the UPS brands and models NOT supported by the built-in APCUPSD support.
- Unfortunately, development has stopped on this plugin. The author is unavailable, and we're hoping someone else will pick it up.
- Installation URL is https://raw.githubusercontent.com/macexx/plugins/master/nut/nut.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- Recycle Bin
- Provides control and easy recovery of deleted files, subject to certain conditions. Provides control of trash emptying.
- Important Notes!
- Because this depends on the vfs recycle features of Samba, this is only for shares over Samba! The only files that are covered are those being accessed across SMB (which is generally all or most of them). Files deleted locally from the console or Telnet session, or through NFS or AFP, are not covered by this!
- The files are recoverable, but not their timestamps, their 'last date modified'.
- Requires Unraid v6.1 or later
- For viewing the deleted files, shares are organized by Disk, Cache, User, Unassigned, and Flash.
- Installation URL is https://github.com/dlandon/recycle.bin/raw/master/recycle.bin.plg. The easy way to install it is to use Community Apps.
- Support thread 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 (maybe more now).
- Make sure you install the v3 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 178 pages long, make sure you read every word! Just kidding! But it IS worth searching, your issue may already be solved.
- ProFTPd - installs ProFTP daemon to provide highly configurable FTP access to your Unraid system
- Installation URL is https://raw.githubusercontent.com/SlrG/Unraid/master/Plugins/ProFTPd.plg. The easy way to install it is to use Community Apps.
- Support thread is here.
- There are many more plugins not yet listed above. You can see them in the Plugins Support forum. Or install Community Apps and check the Apps tab!
- These 3 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
- As of v6.2, these are no longer compatible or may no longer be needed
- The built-in shut down support has improved and you probably do not need this plugin anymore.
- overbyrn plugins
- Development has stopped for the overbyrn plugins. They were never updated for v6.1, so are incompatible with v6.2 or later.
- This is no longer compatible, has been superseded by the Unassigned Devices plugin above.
- 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-Prefer shares. If you forget, the Mover may move them off the Cache drive! Some examples -
- Important! Make sure you set the appdata share to be Cache: Prefer!
EDIT: It is now recommended to store the docker.img file within the auto-generated system share, and do not set the appdata share to be use Cache:Only, but rather use Cache:Prefer
- 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.
- All information on VM's is located in the Unraid forums, Virtualization section, as listed in the Learning about Virtual Machines section.
Go file items
- Optimizations from the past
- 'blockdev --setra 2048' loop
- Unknown if this is advantageous in v6.
- 'blockdev --setra 2048' loop
- Because UnMENU is written in AWK, a scripting language, it is still 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.
- Most of the nice features of UnMENU are now built into v6, such as email notifications and UPS support. Therefore, UnMENU is not nearly as useful anymore. MyMAIN is still useful, still has features no other 'Main' screen has. But overall, we recommend not installing it (or just disable it in the go file) until after you have run v6 without it for a while. If you find you are still missing something from UnMenu, then enable it again.
- 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
- 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.
- Common packages like screen and git and ntfs-3g used to be added separately, but now are either already included with Unraid, or are included in the NerdPack (see Other Plugins above).
- While it still works to put packages into /boot/extra, and they will be automatically installed at boot time, it's not recommended unless absolutely necessary. It's better to use the NerdPack plugin to install any needed packages.
- For v6, ALL packages MUST be 64-bit packages!
- Note: packages in general can be found at http://mirrors.slackware.com/slackware/slackware64-14.2/slackware64/.
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.
Update (October 2015): a recent discussion of the comparative differences made these additional points -
- ReiserFS - clearly has the best tools for file system recovery
- XFS - seems more stable than the others; seems faster too, especially when drive nearly full
- BTRFS - promising, but does not seem very stable yet (from comments elsewhere)
- The "Should I convert to XFS" question? Unless ReiserFS is giving you stability or performance issues, stick with it. Otherwise, convert to XFS. For new disks, choose XFS.
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 maybe 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.
- The first 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.
- An updated procedure is found here, with additional detail, warnings, and discussion.
- The gist of it is:
- Prepare a new empty drive, formatted with XFS, that is as large or larger than the largest data drive
- Copy the entire contents of the largest Reiser-formatted drive to it, and check for a perfect copy
- 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 mistype 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 SSH/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.
- Note: If you are trying to copy data with hard links, use the following rsync variation: (-H 'preserve hard links' is required if you have hard links from an rsnapshot backup)
- rsync -avHPX /mnt/disk15/ /mnt/disk5/
- 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.
Files on flash drive
Here are the files and folders on the flash drive prior to v6, 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 current bzimage - replace with v6 current license.txt - replace with v6 current make_bootable.bat - replace with v6 current make_bootable_mac - replace with v6 current memtest - replace with v6 current readme.txt - replace with v6 current 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 /plugins - delete, including all files and folders /syslinux - keep syslinux.cfg - replace all older ones with v6 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 current v6 (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 Note: super.dat contains the drive models and serials, and their disk assignments 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
FOR EXPERT USERS ONLY!
- 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 Performing the upgrade section. But if you are a veteran Unraid user who refuses to re-format, 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 previously instructed, 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 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 -
#!/bin/bash # 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:
- 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.
- 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.
- 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.
- 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, SMART reports, 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 help you.
- If you see a user posting about a problem but not providing enough info, please inform them of the Need help? Read me first! guide 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 it as an HDD.
- There have been cases (particularly on Macs) 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, the 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 your Docker containers are periodically getting lost, then it is likely that you have them stored on the cache drive (typically in 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 include periodically running the Mover to put their contents on the main array disks. To rectify this, do the following:
- Go into the Shares tab and check the settings for the share folder storing the 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.
- If you have upgraded to any v6.1 release, then there is a new share setting that may cause your disk shares to no longer be exported. Please see the Global Share Settings section above, and read the v6.1-rc1 announcement post. You will have to adjust the settings to regain the same share behavior you had.
- A common problem with browsers and Unraid v6 is that ad blockers can interfere with certain displays, such as the display of your User Shares. If you aren't seeing your User Shares, then try turning off any ad blockers for Unraid pages, or white-listing your Unraid server(s). Also, there have been reports that certain anti-virus tools can interfere with Unraid pages.
Disk controller compatibility issues
- There are 3 known compatibility issues with disk controllers running in v6. In each case, the controllers and attached drives were fine in v5. There may or may not be a workaround.
- Certain Marvell chipset based controllers with virtualization turned on
Unfortunately, some Marvell chipsets have a bad bug that makes them incompatible with certain virtualization BIOS settings turned on. If IOMMU is enabled (may be under other names), then NONE of the attached drives are seen by Unraid! Turning off the BIOS virtualization settings enables the drives to work. For more information, please see Marvell disk controller chipsets and virtualization.
- Certain controllers flashed to LSI 9211-8i
Affected controllers cannot initialize without a special parameter added to your syslinux.cfg file. Please see this thread.
- Slow parity checks
The SAS2LP controller (typically AOC-SAS2LP-MV8) may work fine with Unraid v6, EXCEPT that parity checks are MUCH slower than normal for many users, reason unknown. (Unsure but there might be other similar controllers with the same issue.) Please see this thread and this thread). There have been other problems with the SAS2LP cards too, summarized in this thread.
Audio and Video Dropouts
- There are reports of dropouts when streaming audio and video with a low power CPU and an onboard NIC (especially Realtek). You may need to disable the onboard NIC, and add an Intel NIC. 
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, Tr0910, trurl, Ulvan, WeeboTech, xxredxpandaxx, possibly others (please inform us of others to whom credit is due)