Un-Official UnRAID Manual

From unRAID
Jump to: navigation, search

This is the UNofficial unRAID manual. It is starting its existence as an exact copy of the official manual, but will be edited to contain extra information and clarifications edited by users of unRAID. It is expected it will eventually be more accurate and more up to date than the "Official" manual.

Contents

Connecting To the Server Management Utility

unRAID Server management is accomplished through the use of a browser-based Management Utility (e.g. Internet Explorer or Firefox).

Normally, to connect to the Management Utility, simpy type the name of your server into your browser's address bar:

Example: Where you would normally type "http://www.google.com" type "//tower" to enter the Management Utility. On Chrome it might not work, so type "http://tower" instead

Address bar small.jpg

The default server name is tower. This may be changed on the Settings page, or you may plug the Flash into your PC and edit the config/ident.cfg file directly. Alternately, instead of typing the server name, you could enter the server's IP address. Also by default, upon boot unRAID Server will attempt to contact the local network DHCP server to obtain an IP address. If your network does not have a DHCP server, or if you want to assign a static IP address to your server, you must plug the Flash into your PC and edit the config/network.cfg file where these settings are stored.

If you are using a MAC, you will probably need to access the unRAID server via its IP address. Alternatively, you can edit your hosts file (/etc/hosts) and add a line such as shown below:

192.168.1.200 tower

Once this change has been made, you can access your unRAID server by loading "http://tower" in your browser. More information on editing your hosts file can be found here. Note that you will need to configure your unRAID system to use a static IP address for this method to work.

Main

The home page of the Management Utility is called Main. This page displays all the vital information about the hard drives in the unRAID Server array. This page is divided into four horizontal sections:

  1. A header area which displays the name of your Server and a Comment string. This is the name and comment of your server as it appears in My Network Settings. Both strings may be changed on the Settings page.
  2. A menu bar which displays a list of subpages along with the unRAID version number. These will be explained below.
  3. The Disk Status section which displays all the critical information and status of the hard drives in your unRAID array.
  4. The Command area which consists of a set of buttons which let you Start and Stop the server, as well as initiate various utility operations.

Disk status

There is a line in this section for each disk (hard drive) of your unRAID server. In the unRAID organization, one hard drive serves as the parity disk; the other hard drives are called data disks.

The parity disk is what provides the redundancy in a RAID system. The parity disk is updated every time you write any of the data disks. If a data disk fails, there is sufficient information on the parity disk to permit the system to reconstruct the contents of the failed disk onto a new disk.

IMPORTANT: A requirement of the unRAID system is that the capacity of the parity disk needs to be as large or larger than the capacity of the largest data disk.

The data disks are exported and appear as shares named disk1, disk2, etc., in My Network Places under Windows.

Colored status indicator

The significance of the color indicator at the beginning of each line is as follows:

  • Green: the hard drive status is Normal
  • Yellow: the data contents of the actual hard drive are invalid. The parity disk has this status when Parity-Sync is taking place. A data disk has this status during Reconstruction.
  • Red: the disk is disabled.
  • Blue: a new disk not currently part of the array.
  • Grey: indicates no disk present.
  • Blinking: indicates the corresponding disk has been spun-down.

Disk Name

The disk name is actually a link that will open a page to set specific options for that disk.

On that page you can set the spin-down-delay and the spin-up groups specific to that disk. The spin-down delay will override the global spin-down delay setting if set on an individual disk.

Model/Serial No.

This data is read directly from the hard drive.

Temperature

This is the temperature reported by the hard drive via S.M.A.R.T. When the disk is spun down, there will be an asterisk (*) displayed here instead. This is because sending the command to a hard drive to obtain S.M.A.R.T. information would cause it to spin up.

Size

This is the raw capacity of the hard drive expressed as the number of 1024-byte blocks.

Free

This is the amount of free space in the disk's file system, expressed as the number of 1024-byte blocks. The free space of a freshly formatted disk will always be less than the disk's raw size because of file system overhead.

Reads, Writes, Errors

The Read and Write statistics display the number of 4096-byte read and write operations that have been performed by the disk.

The Error statistic displays the number of read and write operations which have failed. In a protected array, any single-disk read error will be corrected on-the-fly (using parity reconstruction). The Error counter will increment for every such occurrence. Any single-disk write error will result in the Error counter being incremented and that disk being disabled.

Upon system boot, the statistics start out cleared; and they may be manually cleared at any time; refer to the Settings page.

Command area

Starting and Stopping the array

Normally following system boot up the array (complete set of disks) is automatically started (brought on-line and exported as a set of shares). But if there's been a change in disk configuration, such as a new disk added, the array is left stopped so that you can confirm the configuration is correct. This means that any time you have made a disk configuration change you must log into the Management Utility and manually start the array.

Disk configuration changes

Here are the normal configuration changes you can make:

  • You add one or more new disks.
  • You replace a single disk with a bigger one.
  • You replace the cache disk.
  • You replace a failed disk.
  • You shuffle two or more data disks between slots.
  • You remove one or more data disks
Add one or more new disks

This is the normal case of expanding the capacity of the system by adding one or more new hard drives:

  1. Stop the array.
  2. Power down the server.
  3. Install your new hard drive(s).
  4. Power up the unit.
  5. Start the array.

When you Start the array, the system will show newly added disks as "Unformatted" If any disk shows as Unformatted a "Format" button will appear on the management interface. You must press this button to format the new disk(s). When this operation finishes, all the data disks, including the new one(s), will be exported and be available for use.

The format operation consists of two phases. First, the the entire contents of the new disk(s) is cleared (written with zeros), and then it's marked active in the array. Next, a file system is created. unRAID Server uses the ReiserFS journalled file system.

The clearing phase is necessary to preserve the fault tolerance characteristic of the array. If at any time while the new disk(s) is being cleared, one of the other disks fails, you will still be able to recover the data of the failed disk. Unfortunately, the clearing phase can take several hours depending on the size of the new disks(s).

The capacity of any new disk(s) added must be the same size or smaller than your parity disk. If you wish to add a new disk which is larger than your parity disk, then you must instead first replace your parity disk. (You could use your new disk to replace parity, and then use your old parity disk as a new data disk.)

Replace a single disk with a bigger one

This is the case where you are replacing a single small disk with a bigger one:

  1. Stop the array.
  2. Power down the unit.
  3. Replace smaller disk with new bigger disk.
  4. Power up the unit.
  5. Start the array.

When you start the array, the system will reconstruct the contents of the original smaller disk onto the new disk. Upon completion, the disk's file system will be expanded to reflect the new size. You can only expand one disk at a time.

If you are replacing your existing Parity disk with a bigger one, then when you Start the array, the system will simply start a parity sync onto the new Parity disk.

Special note: After replacing a parity disk and re-calculating parity it is strongly recommended you then perform a parity "Check" by pressing the button on the web-management page. Until a check is performed you have no way of knowing if the parity calculations you just wrote to the parity drive are readable. (otherwise you are trusting the new drive to be perfect, and they sometimes are not)

In the same way, after replacing a data disk, it is recommended that a non-correcting parity check be run. This is only available on the command line after logging in via telnet or on the system console as root. To perform that test, log in and type:

/root/mdcmd check NOCORRECT

A special case exists when the new bigger disk is also bigger than the existing parity disk. In this case you must use your new disk to first replace parity, and then replace your small disk with your old parity disk:

  1. Stop the array.
  2. Power down the unit.
  3. Replace smaller parity disk with new bigger disk.
  4. Power up the unit.
  5. Start the array.
  6. Wait for Parity-Sync to complete.
  7. Stop the array.
  8. Power down the unit.
  9. Replace smaller data disk with your old parity disk.
  10. Power up the unit.
  11. Start the array.
Replace the cache disk

This is the case where you replace the cache disk with a new cache disk (typically, one of a larger size):

  • If you are using Docker containers (Docker tab, unRAID 6.0):
    • Make a list of the container names, whether they are running or not, and the position (ON/OFF) of their Autostart buttons;
    • Turn all the Autostart buttons off;
    • Stop the individual docker containers.
  • Stop all plugins.
  • Run mover from the command prompt by logging in and typing:
mover
  • Copy the contents of the old cache disk to an array disk (this assumes disk1 is assigned):
mkdir /mnt/disk1/cache_save
cp -R /mnt/cache/* /mnt/disk1/cache_save
  • Stop the array.
  • Power down the unit.
  • Replace the old cache disk with the new one.
  • Power up the unit.
  • Select the new cache disk in the cache device drop down.
  • Start the array.
  • unRAID will identify the new cache disk as unformatted if it was not already formatted; click the check box under ‘Array Operation’ that says Format and then click the Format button to format the new cache disk.
  • Restore the contents of the old cache disk to the new disk:
cp -R /mnt/disk1/cache_save/* /mnt/cache
  • Set permissions for the new cache disk:
chmod -R u-x,go-rwx,go+u,ugo+X /mnt/cache
chown -R nobody:users /mnt/cache
sync
  • Restart plugins.
  • If you are using Docker containers (Docker tab, unRAID 6.0):
    • Set the position of their Autostart buttons back to the initial settings;
    • Manually start the docker containers that were running.
  • Once you are satisfied that all of the required files are on the new cache disk, you can delete the copies created on the array disk above.
Replace a failed disk

This is the case where you have replaced a failed disk with a new disk:

  1. Stop the array.
  2. Power down the unit.
  3. Replace the failed hard disk with a new one.
  4. Power up the unit.
  5. Start the array.

When you Start the array after replacing a failed disk, the system will reconstruct the contents of the failed disk onto the new disk; and, if the new disk is bigger, expand the file system.

You must replace a failed disk with a disk which is as big or bigger than the original and not bigger than the parity disk. If the replacement disk is larger than your parity disk, then the system permits a special configuration change called swap-disable.

For swap-disable, you use your existing parity disk to replace the failed disk, and you install your new big disk as the parity disk:

  1. Stop the array.
  2. Power down the unit.
  3. Replace the parity hard disk with a new bigger one.
  4. Replace the failed hard disk with you old parity disk.
  5. Power up the unit.
  6. Start the array.

When you start the array, the system will first copy the parity information to the new parity disk, and then reconstruct the contents of the failed disk.

NOTE: Swap-disable (copy) button will not appear if your drive is not red.

Scenario: One data drive (2TB) in slot 5 is having issue with read/write but not yet RED, Replacement drive is 3TB while current parity drive is only 2TB in slot 1. The steps are as below

  1. Identify drive serial number from UNRAID GUI
  2. Shutdown and Power off Unraid server
  3. Replace parity drive (2TB) with new 3TB drive in Slot 1
  4. Remove faulty 2TB drive in slot 5 and replace with the old 2TB parity drive just removed from step above
  5. Power on Unraid Server

From the GUI (5.0.5)

  1. UnRaid GUI will show 2 Drives red
  2. Select the original parity drive (2TB) as parity
  3. Select the "faulty" drive in slot 5 and select No-Disk
  4. Start the array - GUI will show red stated No-Disk
  5. Stop the array
  6. Select the newly install 3TB drive from parity drop down in slot 1 to become the new parity drive
  7. Select the old parity drive 2TB to be the new replacement for faulty drive in slot 5
  8. Copy button will appear instead of start Array.
  9. Click Copy to start Swap Disable function where the old parity (2TB) will copy over to the new parity drive (3TB).
Shuffle two or more data disks between slots

This is the case where the system recognizes all the data disks, but notices that they are not in the same slots they used to be in. The Main page will display the disk model/serial numbers both of the actual placement and what the placement used to be.

If you start the array in this state, the system will just record the new positions of the disks. Note however, that if the same parity disk is not in the top slot you can not start the array.

Remove one or more data disks

In this case the missing disk(s) will be identified. If there is only one missing disk when you start the array it will be marked as failed. All data disks will be exported (including the missing one), but the system will be running unprotected; that is, if a disk fails you will lose data.

If there are two or more missing disks, you can not start the array. In this case you must either put the disks back, or click Restore on the Main page to reset the configuration.

Initialize array configuration (pre-unRAID 4.5.4, the Restore button, on subsequent versions, the "initconfig" command)

When the array is Stopped, on versions of unRAID prior to 4.5.4, there is a button in the Command area of the Main page labeled Restore. Many unRAID users feel this button is mislabeled since the button has nothing to do with restoring data. This button should instead be labeled something like 'Set Initial Configuration' or 'Delete Parity Data', or at its most verbose, 'Delete Existing Parity Data and Disk Configuration'. This function will reset the array configuration data so that the system thinks it's brand new with all new hard drives. When you Start the array, the system will start a background process to generate the parity information.

The Restore button will not erase your data if pressed during healthy unRAID operation, though it will temporarily remove parity protection from your system until a full parity sync completes. If a data disk fails during a parity sync, you will likely lose the data on that disk.

What makes the Restore button so dangerous is that if you were to press this button while unRAID is operating in degraded mode (one hard drive disabled/red balled), then unRAID would immediately forget the data on the disabled disk. This is one of the most common ways that data has been lost with the unRAID system.

In the special case where all the hard drives are new, the format operation will not clear the data areas; it simply generates parity. This can be used when you've added new disk(s) and you don't want to wait around for the clear phase to complete. In this case you could first Reset the array configuration by pressing the Restore button, and then simply Start the array, and the system will re-sync parity, incorporating the new disk(s). Caution: if a disk fails during the operation, you will not be able to rebuild it.

On version 4.5.4 of unRAID the Restore button was removed from the web-interface. It was replaced with a command that must be used on the system console or in a telnet session after logging in as root The command is

initconfig

As an alternative you can type a special command into your browser after first stopping the array on the server

//your_server_name/blank.htm?cmdInit=apply

Typing initconfig will initialize the array device assignment to the drives that are working and currently assigned on the "Devices" page. It will immediately set the parity disk as "invalid". When you next start the array a new initial parity calculation will be performed on the new disk configuration and written to the parity drive. The definition of user-shares and other system configuration stored on the flash drive is not affected.

If you are removing a disk from the array, and do not plan on re-constructing its data onto a replacement, then you must first un-assign it and then either press the Restore button or issue the initconfig command.

The array configuration data is stored in the file config/super.dat on the Flash. For this reason, you must always have the Flash installed in your server.

Check parity

When the array is Started and parity is already valid, there is a button in the Command area labeled Check which will initiate a background Parity-Check and Correct function. Parity-Check will march through all data disks in parallel, computing parity and checking it against stored parity on the parity disk. The "Check" button is actually a "Parity Sync" button. If a mismatch occurs, the parity disk will be updated (written) with the computed data and the Sync Errors counter will be incremented. This button should not be pressed if you suspect that one of your data disks is un-readable. It would update parity with the wrong contents based on the failed read from the data disk.

The most common cause of Sync Errors is power-loss which prevents buffered write data from being written to a disk. Anytime the array is Started, if the system detects that a previous unsafe shutdown occurred, then it automatically initiates a Parity-Check.

Users

The Users page is used to set a password for the root user, and configure User level security for your server.

Security

User level security is a feature that lets you restrict access to shares according to user name. When User level security is enabled, you will need to enter the list of users who may access your server. When a user attempts to connect to a share on your unRAID server, a dialog box will appear asking them to enter their user name and password before being granted access to shares. In addition, you can specify which users may access each share, as well as retrict access to read-only.

If User level security is not enabled, then you do not need to enter a list of users. Any user that attempts to connect to a share on your unRAID server is granted access, subject to the Export mode setting on the share.

User level security

This is the control for enabling or disabling User level security.

Users

This section lists each configured user name.

Regardless of whether User level security is enabled, the built-in user name root always appears atop the Users list. If you enter a non-blank password for the root user, then your browser will also prompt you for the password when you attempt to open the Management Utility. In addition, you will be prompted for a password to log into the console or telnet session.

Add user

To create a new user (User level security enabled), scroll to the end of the Users list, enter the new User name and Password (and Retype password), and then click Add User.

Change password

To change the password of an existing user, just type the new Password (and Retype password) for the user and click Apply.

Remove user

To delete a user, change the User name to blank and click Apply. Note that you can not delete the root user.

Technical notes

  • All user access restrictions on shares is defined for each share on the Shares page.
  • Each new user is automatically given a unique uid, and unique gid (group name same as the user name). However, all objects (files/directories) created in shares will be owned by root.
  • Only root can access the System Management Utility, and log in to the system console or telnet session. The configured users do not have actual home accounts on the server.
  • The following files are maintained in the config directory on the Flash when User level security is enabled:

config/passwd - contains user names and encrypted passwords
config/group - contains groups created for users
config/smbpasswd - contains user names and SMB encrypted passwords

User name

The name should only consist of the characters a-z, 0-9, - (dash), _ (underscore), and . (dot). Please do not use any uppercase letters.

Password

Type anything you want here. Blank is also ok.

Retype password

Must be the same as what you typed for Password.

Shares

The Shares page is used to configure shares and share access.

Export settings (for unRaid 4.x)

This section lets you configure how the pre-defined flash and disk shares are exported, and whether User shares are enabled or not.

The basic external access mode for a share is defined by it's Export mode:

  • Export read/write
    • The share will be exported and visible under My Network Places. If User level security is not enabled, then anyone on the network can read/write data in the share. If User level security is enabled, then anyone who can log into the server can read/write data in the share.
  • Export read-only
    • The share will be exported and visible under My Network Places. The share may not be written, but if User level security is not enabled, then anyone on the network can read data in the share. If User level security is enabled, then anyone who can log into the server can read data in the share.
  • Export read/write, hidden
    • The share will be exported, but will not show up in browse lists (i.e., under My Network Places). If User level security is not enabled, then anyone on the network who knows about the share can read/write data in the share. If User level security is enabled, then anyone who can log into the server and knows about the share can read/write data in the share.
  • Export read-only, hidden
    • The share will be exported, but will not show up in browse lists (i.e., under My Network Places). If User level security is not enabled, then anyone on the network who knows about the share can read data in the share. If User level security is enabled, then anyone who can log into the server and knows about the share can read data in the share.
  • Don't export
    • The share is not exported and can not be accessed.

Export settings (for unRaid 5.x)

There are three types of shares:

  • disk shares
  • flash share
  • user shares, or just 'shares'.

The disk shares are automatically generated by the server and map directly to each of the array data disks. The names of these shares are "disk1", "disk2", etc.

The flash share is also automatically generated by the server and maps directly to the USB flash device from which the system is booted. The name of this share is "flash".

User shares are shared created by the user.

Security

Each share has it's own security settings. The security settings for a share include it's Export setting and its Security Mode setting.

The share Export setting determines overall visibility of the share:

  • Export=Yes means the share is visible in browse list and is accessible per it's security mode.
  • Export=No means the share is not visible and not accessible regardless of the security mode, that is, effectively disabled.
  • Export=Yes/hidden means the share is not visible in Windows CIFS networking, but is accessible per it's security mode.

The Security Mode setting establishes access rights to the share. There are three security modes for a share:

  • Public
  • Secure
  • Private

Public means that no user account is needed on the server for someone to access the share. This means you won't see the login box pop up when accessing the share. It also means that anyone can read/write/create/delete any file or directory on the share. This is the default setting when a new share is created. This is also the default setting if a share is created by creating it on a disk share. When a file is created it will be be owned on the linux-side by the 'nobody' user of the users group (uid/gid = 99/100).

Secure means that no user account is necessary on the server in order to access the share, and no login box will pop up. But in this mode you can select users than can have read/write access to the share, all other users will have read-only access. Since no login box will appear, in order to get this to work, this must be true:

  • Whatever username you used to log in to your windows PC must also be a user name on the server. The 'case' of the user name does not matter (actually you must enter all lower-case on server side).
  • The password you set on the server must match exactly the password used for your windows logon. The password IS case-sensitive.

Private means that you specify the exact set of users that can either have readonly or read/write access to the share. If you try to connect to the server you may or may not get a login box. If the username/password of your windows login matches one of the usernames defined on the server side, and that username has either readonly or read/write access (ie, not 'no access), then no login box will appear and you will be be logged into the share with the access rights specified. But if either your windows username is unknown on the server, or your windows password does not match, then windows will present a login box prompting for a username/password. Using this box you can then login to the share using one of the other username/passwords on the server.

Note that once you login to the server using some other username than your windows username, windows will use that username to access all shares on the server.

Flash share

This is the export mode of the flash share.

Disk shares

This is the export mode for the entire set of disk shares.

User shares

This is the control for enabling and disabling User shares.

User shares


This section lists all of the configured User shares.

Note: if User shares are not enabled, then this section is not present.

User shares is a unique feature of unRAID OS which provides a unified name space across multiple data disks. User shares simplify storage management by presenting a view of all unRAID storage as if it were one large file system.

When User Shares are enabled, unRAID OS will automatically create a set of shares named after the top-level directories found on each data disk. If the same top-level directory exists on more than one disk, then the exported share will contain all directories/files under that top-level directory on all the disks.

For example, suppose each disk has the following structure:

  • disk1
    • Movies
      • Alien
        • folder.jpg
        • VIDEO_TS
          • VIDEO_TS.IFO
          • VTS_01_1.VOB
          • VTS_01_2.VOB
      • Basic Instinct
        • folder.jpg
        • VIDEO_TS
          • VIDEO_TS.IFO
          • VTS_01_1.VOB
          • VTS_01_2.VOB
  • disk2
    • Movies
      • Cars
        • folder.jpg
        • VIDEO_TS
          • VIDEO_TS.IFO
          • VTS_01_1.VOB
          • VTS_01_2.VOB
  • disk3
    • Movies
      • Days of Thunder
        • folder.jpg
        • VIDEO_TS
          • VIDEO_TS.IFO
          • VTS_01_1.VOB
          • VTS_01_2.VOB


With User Shares enabled, for the above tree we would see this share under My Network Places:

//tower/Movies

And it would have the following structure:

  • Movies
    • Alien
      • folder.jpg
      • VIDEO_TS
        • VIDEO_TS.IFO
        • VTS_01_1.VOB
        • VTS_01_2.VOB
    • Basic Instinct
      • folder.jpg
      • VIDEO_TS
        • VIDEO_TS.IFO
        • VTS_01_1.VOB
        • VTS_01_2.VOB
    • Cars
      • folder.jpg
      • VIDEO_TS
        • VIDEO_TS.IFO
        • VTS_01_1.VOB
        • VTS_01_2.VOB
    • Days of Thunder
      • folder.jpg
      • VIDEO_TS
        • VIDEO_TS.IFO
        • VTS_01_1.VOB
        • VTS_01_2.VOB

In the case where the same object (directory or file) exists at the same hierarchy on multiple disks, the User Share will reference the object on the lowest numbered disk. For example, if Movies/Cars existed on both disk1 and disk2, then Cars under the Movies User Share would refer to the version on disk1.

Each time the array is Started, if User Shares are enabled, unRAID OS will regenerate and re-export each top-level directory as a network share.


Creating User Shares

To create a new User share, scroll to the end of the User shares list, enter the new Share name and other configuration, and then click Add Share. unRAID OS will select the disk to create the initial top-level share directory according to the configured Allocation method.

Deleting User Shares

To delete a User Share, just clear the Share name field and click Apply. Only entirely empty User Shares may be deleted.

Renaming User Shares

To rename a User share, just click in the Share name field of the share, type it's new name, and then click Apply.

Technical notes:

  • A user share configuration file called config/shares/<share name>.cfg is stored on the Flash for each User Share (where is the Share name). If this file does not exist, then a set of default values are used for the User Share. Whenever a User Share parameter is changed, it's configuration file is also updated, or created if it does not exist.
  • Adding a new User Share or changing the configuration parameters of an existing User Share will not break any current connections on other shares. Renaming or deleting a User Share will break all outstanding connections, however. This is because Samba must be stopped in order to rename or delete the top-level directory which is associated with the share.
  • User Shares are implemented using proprietary code which builds a composite directory hierarchy of all the data disks. This is created on a tmpfs file system mounted on /mnt/tmp. User Shares are exported using a proprietary FUSE pseudo-file system called 'shfs' which is mounted on /mnt/users.
  • When an object needs to be created on a selected disk, first the directory hierarchy is created on the disk (if it isn't already in place). When the last file of a particular directory on a disk is removed, the unused part of the directory hierarchy on that disk remains in place.
  • With User Shares enabled, files may still be accessed via the individual disk shares. However, depending on the disk directory hierarchy and user share settings, some operations on a disk share may not be reflected in the user share which includes this disk.




Share name


This is the name of the share. Use only the characters: a-z, A-Z, 0-9, - (dash), and . (dot).


Comments


Optional descriptive text that will appear in the Comments column under My Network Places.


Allocation method


When a new User share is created, or when any object (file or directory) is created within a User share, the system must determine which data disk the User share or object will be created on. In general, a new User share, or object within a User share, will be created on the data disk with the most free space. However there are a set of share configuration parameters available to fine tune disk allocation.

The basic allocation strategy for a share is defined by the Allocation method configuration parameter. You may select one of three allocation methods for the system to use.


High Water

The high water allocation method attempts to step fill each disk so at the end of each step there is an equal free space left on each disk. The idea is to progressively fill each disk but not constantly go back and forth between disks each time new data is written to the array. Most times, only a single disk will be needed when writing a series of files to the array so the array will only spin-up the needed disk. The high water level is initially set equal to one-half of the size of the largest disk. A new high water level is again set to one-half of the previous high level once all the disks have less free space than the current high water level.

High-Water Allocation Method.JPG

The above example shows what will occur when there is a mix of 4 disks varying is size from 500gig to 2T in size.

First Pass - The high water level is set to one-half of the size of the 2T drive or 1T. Each disk will be filled until it has <1T of free space remaining. This means no data is stored on disk1 or disk2 since both already have <1T of free space. 500gig of data will be stored on disk3 followed by 1T of data being stored on disk4.

Second Pass - The high water level is reset to one-half of the previous level or 500gig. Each disk will be filled until it has <500gig of free space remaining. This means no data is stored on disk1 since it already has <500gig of free space. 500gig of data will be stored on disk2 and then 500gig of data will be stored on disk3 and finally 500gig of data will be stored on disk4.

Third Pass - The high water level is again reset to one-half of the previous level or 250gig. Each disk will be filled until it has <250gig of free space remaining. 250gig of data will be stored on disk1 and then 250gig of data will be stored on disk2 and then 250gig of data will be stored on disk3 and finally 250gig of data will be stored on disk4. An interesting note is that the 500gig disk does not get used at all until the third pass. Don't be concerned if the smaller sized disks don't immediately get used with this method.

This pattern will continue with progressively smaller high water levels until the disks are full.

Most Free

The most free allocation method simply picks the disk with the most free space and writes the data to that disk. Each time a file is written unRAID will check the free space on the disks and pick the one with the most free space.

Fill-Up

The fill-up allocation method simply attempts to fill each disk in order from the lowest numbered disk to the highest numbered disk. The fill-up allocation method must be used in conjunction with the minimum free space setting. Otherwise, unRAID will begin to give disk full errors and not allow any more transfers once the first disk gets close to being full.


Min. Free Space


The minimum free space setting is used with the allocation method and split level. The minimum free space setting tells unRAID to stop putting new content onto the disk if it can be split to a new disk. This must be used with the fill-up allocation method or disk full errors will occur.

First a brief explanation of how unRAID will typically receive a file. unRAID typically receives data in this manner. First, unRAID receives the request to store a file, named for example "file.eg". At this time, unRAID has no idea how big "file.eg" is so unRAID will pick a spot to place "file.eg" and begin to store the file data as the data is transfered over the network. Now, this is important because unRAID may pick a storage disk that does not have enough space to store the complete "file.eg". unRAID doesn't know there is not enough space when it first places the file so unRAID will only find out the disk doesn't have enough space when the disk is full. At this point, the transfer will fail with a disk full error.

So, unRAID will write to a different disk if the minimum free space is set to a value larger than the biggest file size you will ever transfer. The recommended setting is 2 times the largest file size you will ever transfer. For example, if the largest file you have is 8gig in size then set the minimum free space to 16gig. This allows you to transfer files that may vary in size somewhat and not accidentally transfer one too large. The minimum free space is set in kilo-bytes.

Here are some examples of the minimum free space setting;

Free Space Value
500 meg 500000
20 gig 20000000
40 gig 40000000

Note that unRAID will still place files on the disk if the split level does not allow the files to be placed on another disk with more free space.

Also note that unRAID will typically not move a file onto a new disk if you're over-writing or updating it. For example, a backup file that grows in size over time could end up filling a disk and causing a disk full error.


Split level


The split level setting tells unRAID how many folder levels are allowed to be created on multiple disks. The split level can be used to ensure that the contents of a folder are kept on the same disk. The split level numbering starts with the user share being the top level and given the number 1.


Here is an example showing a possible directory structure for a user share called "Media".

Note: I (the original author of this section) consider combining media types into a single large share a poor way to store media. I use a share for each media type. Movies is a share and TV shows is a share. I combined the movies and TV shows to show the pitfalls in the split levels when doing this as explained after the figure.

Split level 1.JPG

Here is an explanation of the different split levels, referenced to the folder structure above;

  1. Level 1
    • The top level Media share can be created on every disk.
    • Every other folder under the Media share must remain on a single disk.
    • This setting does not allow the SD Movies, HD Movies, Kids Movies or TV Shows folders to spread to multiple disks.
    • This setting is too low for all the media.
  2. Level 2
    • The top level Media share can be created on every disk.
    • The SD Movies, HD Movies, Kids Movies and TV Shows folders can be created on every disk.
    • Each Movie Folder and TV Show Folder must remain on a single disk.
    • This setting may work well. It will keep each movie and each TV series together on a single disk.
    • This setting may give issues because it keeps each TV series on a single disk. So, a disk may fill as new TV seasons are added to a TV show which is on a disk which is close to full.
  3. Level 3
    • The top level Media share can be created on every disk.
    • The SD Movies, HD Movies, Kids Movies and TV Shows folders can be created on every disk.
    • Each Movie Folder and TV Show Folder can be created on every disk.
    • Each Season Folder must remain on a single disk.
    • This setting will allow the contents stored in each Movie Folder to be spread out onto multiple disks.
    • This setting is too high for the different movie types.
  4. Level 4
    • The top level Media share can be created on every disk.
    • The SD Movies, HD Movies, Kids Movies and TV Shows folders can be created on every disk.
    • Each Movie Folder and TV Show Folder can be created on every disk.
    • Each Season Folder can be created on every disk.
    • This setting is too high because it will allow the contents of every folder to be spread out onto multiple disks. The split level is not being used to keep similar content together.

The only valid split level for the above example is 2. This causes a split level limitation which forces each complete TV series to a single disk. This can force a new TV season to be placed on a disk which is almost full and result in out of space errors once new episodes completely fill the disk. The split level can't be increased to 3 because each individual movie would not be contained to a single disk.


The first way to fix this split level mismatch issue is to create separate shares for the movies and the TV shows. This way, the movies can be set to use a split level of 2 and the TV shows can use a split level of 3.

Split level 2.JPG

For Movies use a split level = 2. This allows the "SD Movies", "HD Movies" and "Kids Movies" folders to be placed on every disk and it keeps each individual movie folder on a single disk. This way, any single movie folder and the contents of the movie folder will remain on a single disk.

For TV_Shows use a split level of either 1 or 2. A split level of 1 will keep each TV series on a single disk and split level of 2 will keep each season on a single disk. The split level of 2 means that the complete TV series can be stored on multiple disks, however each individual season of that TV series will be on a single disk.


The second way to fix the issue is to add another folder level to the movies, starting first with a Movies folder in the Media share and then placing the different movie types below this.

Split level 3.JPG

This user share structure must use split level = 3. SD Movies, HD Movies, Kids Movies and each TV series can exist on multiple disks. This structure means each TV season can be on a different disk. This has the opposite issue compared to the first example. You can not use split level 2 to force each complete TV series to remain on a single disk without messing up the ability of the movies to split to every disk.


Some things to keep in mind.

  • The above examples are to demonstrate the use of the split level. It is not necessary to store your media sorted in the same format as the above example illustrates. You may want to use a Movies share and then just place a "Movie Name" folder for each movie directly into the share without sorting the movies by type.
  • It is completely valid to force each complete TV series to stay on a single disk. Just understand that a continuing TV series will keep filling the disk where it is first placed. This may require manual intervention to shift some TV series from an almost full disk to an empty disk. Using the Most Free allocation method can help eliminate the issue since a completely new TV series would be placed on the disk with the most free space.
  • The above TV example applies to any similar share. It could apply to a Pictures share where you store the pictures in folders based on the year (2010, 2011, 2012 etc) or it could apply to a Music share where you store the music in a folder for each artist. In these cases, a split level of 1 would keep a whole year of pictures on a single disk or it would keep all the music by an artist on a single disk.





Disable Split Level

It is also possible to disable the split level by setting a high split level. A file copy or move will fail if a folder is locked to a full disk and an attempt is made to add more files into that folder. Setting a high split level will ensure each file will get written to the server as long as a disk has space for it.


Split Level = 1 Example

The following example demonstrates how the share behaves when the split level is set to 1. The Share name is New_Movies. Each movie stored in this share has its own folder. Inside the movie folder is the movie file as well as some metadata files used by MediaBrowser.


Movie Share.jpg

The above Windows Explorer screen shot shows the file structure of the New_Movies share on the left and the contents of the A History of Violence movie folder on the right. The levels for this share are labeled on the example. This is what split level = 1 means:

  • A New_Movies folder can be created on each disk allowed by the include and exclude disk settings. A new New_Movies folder will be created on the next disk in line when the allocation method calls for unRAID to begin filling the next disk. Note that the New_Movies folder will only be created on the next disk in line when it is necessary and not when the share is created.
  • The A History of Violence folder can only exist on one disk. Once it is created on the disk, all of the contents will remain on the same disk. Any changes or additions to this folder will remain on the same disk. For example, a new file called movie.nfo for the XBMC metadata might be created in this folder in the future. The movie.nfo file will be created in the existing A History of Violence folder. A duplicate A History of Violence folder will not be created on another disk to store this new file.


You will notice that the movie folders 500 Days of Summer (2009) and 2 Fast 2 Furious (2003) both appear in the New_Movies share. The next screen shot will show how each of these files is stored on a separate disk.


Movies Share Disk View.JPG

The above screen shot shows side by side Window Explorer views of the file structure stored on disk1 and disk2. On the left is disk1 and on the right is disk2. The left Explorer window shows the contents of disk1. The New_Movies share is a folder stored at the top level or the root of disk1 with the individual movie directories stored in this directory. The right Explorer window shows the contents of disk2. The New_Movies share is a folder stored at the top level or the root of disk2 with the individual movie folders stored in this directory. As files were being moved into the New_Movies share, unRAID created the New_Movies folder on both disk1 and disk2 to store these files.

The windows side by side can be used to examine the contents of the New_Movies share on a disk by disk basis. You will notice that the movie folder 500 Days of Summer (2009) is stored on disk1 and the movie folder 2 Fast 2 Furious (2003) is stored on disk2. As previously noted, unRAID combines the movies stored on disk1 and disk2 into one network share called New_Movies and both movies appear in the New_Movies network share.

Take note that a share called Movies is also visible on disk2.

Split Level 0

Split level 0 is a special case. Split level 0 requires you to create the desired top level or parent folder structure. unRAID will unconditionally create an object on the disk that contains the parent folders. unRAID will choose which disk to use according to the allocation method if the parent folders exist on multiple disks.

Exception for unRAID versions 4.4.x and below: If you set the Split level to 0, then all directories/files created under that share will be on the same disk where the share was originally created. In other words, use level 0 to not allow the share to split.


Example

The server has 4 disks. A user share called Media is desired. Different types of media will be stored in this share. The desired structure is;

  • disk1 - will hold the DVD movies.
  • disk2 - will hold the BluRay movies.
  • disk3 - will hold the BluRay movies.
  • disk4 - will hold the TV series.

The desired structure is illustrated below.

Level 0.JPG

On the left side is how the user share will appear and on the right side is the folder structure on each disk. The user will go to each disk and create the folders shown in red to create the storage as listed above. Then, the Media folder as well as the DVD Movies, BluRay Movies and TV Shows folders become the parent folders for everything stored in the Media share. The media will be sorted by disk as follows;

  • Movies placed in the DVD Movies folder will go to disk1.
  • Movies placed in the BluRay Movies folder will go to disk2 or disk3. The disk is selected by the allocation method.
  • TV shows placed in the TV Shows folder will go to disk4.

Say one day that disk1 is full and disk5 is added to the server to hold new DVD Movies. The same folders on disk1 must be created on the new disk5. In other words, the folder Media and sub-folder DVD Movies must be created on disk5. Then, unRAID can use either disk1 or disk5 to store DVD Movies.

Split By Character

Specify a character in the split level box to use this method. Then, unRAID will not allow any folder name containing the character to split. For example, set the split level to an opening square bracket ( [ ) instead of a number. Then, create each movie folder with the year encased in square brackets after the title in this manner - Iron Man 2 [2010]. unRAID will see the opening square bracket ( [ ) and it will not split this folder or any content stored inside this folder.

This type of split level can allow different levels of sub-folders to be specified as not splitting simply by inserting the character into the folder name which should not split. This can overcome the limitation of having a fixed split level for a share.


Included and Excluded disk(s)


The included disk(s) and excluded disk(s) parameters control which disks are allowed to be used by each user share. These parameters can be used separately or together to define the group of disks allowed for each user share. The disks are entered by disk number with a comma separating each disk, for example "disk2,disk5".

unRAID will first check the included disks(s) set and then the Excluded disk(s) set when deciding which disk to place a file on. Then, unRAID will use the split level and allocation method to pick a disk which is allowed to hold the file.

Included disk(s)

The included disks(s) parameter defines the set of disks which are candidates for allocation to that share. All disks may be used by the user share when the Included disk(s) parameter is left blank. Specify the disks to include here. For example, set the included disk(s) to "disk1,disk2,disk3" to allow the share to only use disk1, disk2 and disk3.

Excluded disk(s)

The excluded disk(s) parameter defines the set of disks which are excluded from use by the user share. No disks are excluded from use by the user share when the excluded disk(s) parameter is left blank. Specify the disks to exclude here. For example, set the excluded disk(s) to "disk1,disk2" to restrict a share from using disk1 and disk2.


Export mode


Specifies the basic export mode of the share. See Export Mode above.

Exceptions

A list of users who are exceptions to the basic export mode of the share: If the export mode of the share is read/write, then this lists users who will have read-only access. If the export mode of the share is read-only, then this lists users who will have read/write access. Separate multiple user names with commas.

Note: this parameter is present only when User level security is enabled.


Valid users

A list of users who can exclusively access the share. Blank means all users.

Note: this parameter is present only when User level security is enabled.

Invalid users

A list of users who may not access the share at all. Blank means no users.

Note: this parameter is present only when User level security is enabled.

Examples

Suppose we have a share called Movies for which we want everyone on the network to be able to read, but only larry can read/write:

Export mode: Export read-only
Exceptions: larry

Suppose we have a share called Finances which only mom and dad can access:

Export mode: Export read/write, hidden
Valid users: mom,dad

Further, suppose only mom should be able to change the files:

Export mode: Export read/write, hidden
Exceptions: dad
Valid users: mom,dad

Another way to achieve the same thing:

Export mode: Export read-only, hidden
Exceptions: mom
Valid users: mom,dad

Settings

There are multiple versions of the Settings page:

  1. UnRAID 5
  2. UnRAID 4

UnRAID v5

The Settings Page has two sections with a sub-section under each.

  1. Network Services
    1. AFP
    2. FTP
    3. NFS
    4. SMB
  2. Other Settings
    1. Date and Time
    2. Disk Settings
    3. Identification
    4. Network Settings
    5. Share Settings

Network Services

This contains the supported share access services. Each type is listed in it's own sections below.

AFP
FTP
NFS
SMB

Other Settings

Date and time
Current date & time

The current date and time, that is, when the page was refreshed. To change the date and/or time, edit this field appropriately and then click Apply.

Time zone

Enter your time zone here.

It is possible to use a custom time zone so that DST adjustments are handled properly. To use this feature, you first need to download your timezone file from our website. Once you have identified your timezone file, right-click the link and select "Save Link As". In the dialog box, type timezone for the File name.

Next, copy the file timezone to the config directory of your Flash. Navigate to the 'Settings' page of the System Management Utility and select "(custom)" in the Time zone dropdown list. Check that the Date and Time are correct and click Apply.

Disk settings
Disk spin down delay

Sets the amount of inactive time before a hard drive is spun down.

Identification
Server name

This is the name of the server on your network.

Comments

This is a comment field which shows up net to the server name under My Network Places.

Workgroup

This is the workgroup that your server belongs to.

Local master

If set to Yes, then the server will attempt to become the local browse master.

SMB ports

Specifies which ports the server should listen on for SMB traffic.

Network settings
MAC address

This is the MAC address of your network interface.

Obtain IP address automatically

If set to Yes, then the server will attempt to contact the local DHCP server to obtain an IP address lease. If set to No, then you must statically set the IP address.

IP address

The IP address of the server.

Netmask

The subnet mask of the server.

Gateway

The gateway IP address.

Share Settings
Enable User Shares

This drop down let's you choose whether to enable user shares on your UnRAID server. User shares is a unique feature of unRAID OS which provides a unified name space across multiple data disks.

Choose 'Yes' to enable User Shares.

Included Disks

List each of the included disks that will have User Shares enabled on them. Separate the list by commas.

Excluded Disks

If you specifically want to exclude disks from User Shares, list them here. Separate the list by commas.


UnRAID v4

The Settings page is used to configure general system parameters. This page is divided into 4 sections:

  1. Identification
  2. Network settings
  3. Disk setttings
  4. Date and time

Identification

Server name

This is the name of the server on your network.

Comments

This is a comment field which shows up net to the server name under My Network Places.

Workgroup

This is the workgroup that your server belongs to.

Local master

If set to Yes, then the server will attempt to become the local browse master.

SMB ports

Specifies which ports the server should listen on for SMB traffic.

Network settings

MAC address

This is the MAC address of your network interface.

Obtain IP address automatically

If set to Yes, then the server will attempt to contact the local DHCP server to obtain an IP address lease. If set to No, then you must statically set the IP address.

IP address

The IP address of the server.

Netmask

The subnet mask of the server.

Gateway

The gateway IP address.

Disk settings

Disk spin down delay

Sets the amount of inactive time before a hard drive is spun down.

Date and time

Current date & time

The current date and time, that is, when the page was refreshed. To change the date and/or time, edit this field appropriately and then click Apply.

Time zone

Enter your time zone here.

It is possible to use a custom time zone so that DST adjustments are handled properly. To use this feature, you first need to download your timezone file from our website. Once you have identified your timezone file, right-click the link and select "Save Link As". In the dialog box, type timezone for the File name.

Next, copy the file timezone to the config directory of your Flash. Navigate to the 'Settings' page of the System Management Utility and select "(custom)" in the Time zone dropdown list. Check that the Date and Time are correct and click Apply.

Devices

The Devices page is used to display information about the physical devices installed in the server.

Boot device

This section displays information regarding the USB Flash device from which the system booted.

Disk devices

An unRAID server disk array consists of a single parity disk and a number of data disks. The data disks are exclusively used to store user data, and the parity disk provides the redundancy necessary to recover from any singe disk failure.

Terminology

Note that we're careful to use the term disk when referring to an array storage device. We use the term hard drive when referring to an actual hard drive. This is because in a RAID system it's possible to read/write an array disk whose corresponding hard drive is disabled or even missing! In addition, it's useful to be able to ask, "which hard drive is assigned to be the parity disk?" or "which hard drive corresponds to data disk2?".

Assigning devices

We need a way therefore, to assign hard drives to array disks. This is accomplished on the Devices page, in the Disk devices section. Here you will find a drop-down box for each array disk. The drop-down box lists all the unassigned hard drives. To assign a hard drive simply select it from the list. Each time a hard drive assignment is made, the system updates the config/disk.cfg file to record the assignment.

Note: The system doesn't actually record information about the hard drive itself, but rather, the port through which the hard drive is accessed. We need to record the port so that we can detect, for example, when a disabled disk is replaced. (Port here is really the linux device pathname.)

Note2: The array must be stopped on the Main page before disk assignment changes can be made on the Devices page.

Requirements

Unlike traditional RAID systems which stripe data across all the hard drives, an unRAID system stores files on individual data disks. Consequently, all file write operations will involve both the data disk the file is being written to, and the parity disk. For these reasons,

  • the parity disk size must be as large or larger than any of the data disks,

and

  • given a choice, the parity disk should be the fastest disk in your system.

Guidelines

Here are the steps you should follow when designing your disk array:

  1. Decide which hard drive you will use for parity, and which hard drives you will use for data disk1, disk2, etc., and label them in some fashion. Also, find the serial number of each hard drive and jot it down somewhere; you will need this information later.
  2. Connect cables to the hard drives in a logical manner. For example, if your motherboard has 4 SATA ports, they are labeled "sata-0", "sata-1", "sata-2", and "sata-3" (or something similar). Hook these cables to a contiguous set of hard drives, e.g., parity, disk1, disk2, and disk3. Follow a similar pattern for PCI disk controllers. (Note: There is an exception to this for optimization of certain system configurations, see [1])
  3. Build your system, boot unRAID Server and start the Web Management Utility. If this is a fresh system build, then the Main page of the Web Management Utility will show no disks installed. This doesn't mean the system can't detect your hard drives; it just means that none have been assigned yet.
  4. Go to the Devices page and look at the Disk devices section. Here is where you will assign hard drives to the various array disks. You will notice there is a drop down box for each array disk device. Clicking on the drop down box reveals all the unassigned hard drives in the system. Remember the serial numbers you recorded back in step 1? For each disk, choose the proper hard drive based on its serial number.

After you have assigned all of your hard drives, go back to the Main menu and you will see the array and be able to start it.