Skip to main content

User shares

tip

Enable or disable user shares in Settings > Global Share Settings. User shares are enabled by default.

Overview​

User shares provide an aggregated view of all top level folders of the same name across the cache and the array drives. The name of this top level folder is used as the share name. From a user perspective this gives a view that can span multiple drives when viewed at the network level. Note that no individual file spans multiple drives - it is just the directory level that is given a unified view.

You manage User Shares from the Shares tab. There, you can see an overview off all shares on your Unraid server, you can create new shares, and edit or delete existing ones. If you manually create a top level folder on any drive, the system will automatically consider this to be a User Share and assign it default attributes.

When viewed at the Linux level, user shares appear under the path /mnt/user. This includes the files on the main array and also any for the share on any pool. A user share is a logical view imposed on top of the underlying physical file system so you can see the same files if you look at the physical level, as described for Disk Shares.

Note that current releases of Unraid also include the mount point /mnt/user0 that shows the files in User Shares omitting any files for a share that are on any pool. This is a different view of the files on your server. However, this mount point is now deprecated and may stop being available in a future Unraid release.

The physical drive in the main array, used to store a physical file, is controlled by a number of settings for the share, including the allocation method, included or excluded disks, and the split level.

If you change the settings for an existing share, the changes only affect where new files are put after the new settings are applied. Any files already present in the share are left where they are. To move existing files takes manual action.

caution

There is a quirk of the interaction between Linux and the Unraid user share system that users can encounter if they are working at the disk share level. The Linux command for 'move' is implemented by first trying a rename on the file (which is faster) and only if that fails does it do a copy-and-delete operation.

This can mean when you try to move files from one user share to another from the command line, Linux will often simply rename the files so they have a different path on the same disk, in violation of any user share settings such as included disks. The workaround for this is to instead explicitly copy from source to destination so that new files get created following the user share settings, then deleting from the source.

Share settings​

tip

When you configure the settings for the share, select the Help icon in the top-right of the Unraid WebGUI for detailed information on the individual settings.

Minimum free space​

The Minimum free space setting is used with the allocation method and split level. This setting controls how much space must be free for a drive to be chosen for a new file. If the condition is met, Unraid stops putting new data onto the disk (as long as the Split Level setting indicates it can be split to a new disk).

note

This parameter must be used when the fill-up allocation method is configured, or disk full errors will occur when there isn't enough space to fit a file you are trying to write.

When Unraid receives a request to store a file, say for example file.eg, it has no idea how big the file is. Unraid will pick a spot to place it and begin to store the file data as the data is transferred over the network. Now, this may result in Unraid picking a storage disk with insufficient storage space for the complete file. Unraid is unaware there isn't enough space when it first places the file so it will only find out 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.

We recommend setting the value to twice the size of the largest file you will ever transfer. For example, if the largest file you have is 8GB in size then set the minimum free space to 16GB. 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 kilobytes (KB), megabytes (MB), gigabytes (GB), or terabytes (TB). Enter the value and units without any spaces. For example, if you want to set the value at 50 Gigabytes, enter 50GB. Note that new user shares will have a default 10% minimum free space assignment.

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. Note that Unraid will typically not move a file onto a new disk if you're overwriting 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.

caution

There is also a Minimum Free Space setting for cache pools. This is used to determine if a new file for a user share, with the Use Cache setting of Yes or Prefer, should be written to the cache or, instead, bypass the cache and go directly to the array.

This needs to be set if you want to avoid filling a cache pool which can cause problems. As for this value when used with a User Share it should be larger than the largest file you intend to write, and some people like to make it significantly larger. You get to this setting by clicking on a pool on the Main tab.

Primary and Secondary storage (Unraid 6.12)​

The Primary storage parameter defines the location - Cache, Array, or any named pool - to which new files will be written for the selected share. The Secondary storage parameter sets the location where files will be moved to if there is not enough room in primary storage.

When primary storage is below the Minimum Free Space value, new files and folders are created in secondary storage.

note

If you select an array or any named pool for your primary or secondary storage, you must also configure its allocation method, split level, and any included or excluded disks.

Unraid 6.12 introduces new terminology to make it clearer to users where files are initially placed, and where they will end up. The same functionality is present in earlier releases, but has often been misunderstood by new users.

For the Primary storage drop-down:

  • This setting is mandatory. You must select a primary storage device or pool. Primary storage has a default value of Cache
    • any named pool can be selected.
    • Array can be selected.

For the Secondary storage drop-down:

  • None: This means that there is no secondary storage set for this share. Note that secondary storage is optional.
    • if Primary storage is a pool name, then the only options are None and Array.
    • if Primary storage is Array, then only None appears as an option.

Use Cache and mover behavior with user shares (Unraid 6.11 and earlier)​

The following settings are only found in Unraid 6.11 and earlier. They achieve the same functionality as the settings available in 6.12 but are presented differently.

INFO

Starting with Unraid 6.9, multiple pools can exist and they can have any name you choose. Any of these pools can act as a cache in the way Unraid uses the term. The word cache therefore is referring to this functionality and not necessarily to the pool name.

Unraid includes an application called Mover that is used in conjunction with user shares. It's behavior is controlled by the Use Cache for new files setting under each user share. The way these settings operate is as follows:

  • Yes: Write new files to the cache as long as the free space on the cache is above the Minimum free space value. If the free space is below that then bypass the cache and write the files directly to the main array.

    When Mover runs it will attempt to move files to the main array as long as they are not currently open. Which array drive will get the file is controlled by the combination of the Allocation Method, Split Level, and Minimum Free Space setting for the share.

  • No: Write new files directly to the array. Which array drive will get the file is controlled by the combination of the Allocation method, Split level, and Minimum Free Space setting for the share.

    When Mover runs it will take no action on files for this share even if there are files on the cache that logically belong to this share.

  • Only: Write new files directly to the cache. If the free space on the cache is below the Minimum free space setting for the cache then the write will fail with an out-of-space error.

    When Mover runs it will take no action on files for this share even if there are files on the main array that logically belong to this share.

  • Prefer: Write new files to the cache if the free space on the cache is above the Minimum free space setting for the share, and if the free space falls below that value then write the files to the main array instead.

    When Mover runs it will attempt to move any files for this share that are on the main array back to the cache as long as the free space on the cache is above the Minimum free space setting for the cache

    It is the default setting for the appdata and system shares that support the Docker and VM subsystems. Generally, you want the files/folders belonging to these shares to reside on the cache as it provides better performance for Docker containers and VMs if their files are not on the main array. This is due to the performance overhead of maintaining parity on the main array which slows down write operations.

    This setting works for a share even if you do not (yet) have a physical cache drive(s) as files will be written directly to the array. If at a later date you add a cache drive, Mover will automatically try and move the files in any share set to Prefer to the pool defined as the cache for the share. This is why Prefer is the default for shares that are located on the cache rather than Only as it caters to those who do not (yet) have a cache drive.

Moving Files from a Pool (cache) to the Array​

This is the more traditional usage of a pool for caching where you want the files for a particular share initially written to a pool that acts as a cache to maximize write speed, but later you want it to be moved to the main array for long term storage.

Sometimes, however, you may find that the files seem to be 'stuck' in a pool. In this situation, the way to get the files belonging to a share from a pool onto the main array is:

  1. Make sure that Primary Storage is set to Cache and Secondary Storage is set to Array, for any shares you want to move files from.
  2. Set the Mover action field to Cache -> Array.
  3. Disable Docker and VM services, if they are enabled, as files open in these services cannot be moved.
  4. Go to Main > Array Operation, and select Move to manually move files from the pool (cache) to the array.
  5. When mover finishes, you can re-enable the Docker and/or VMs services you use if you disabled them earlier.

Moving Files from the Array to a Pool (cache)​

You typically want files associated with running Docker containers or VMs on a pool to maximize performance. It is not unusual, for one reason or another, to find that you have files on the main array which you really want to have in a pool. In particular, this is likely to happen for the appdata or default system shares.

The way to proceed to get the files belonging to a share from the main array onto a pool is:

  1. Make sure that Primary Storage is set to Cache and Secondary Storage is set to Array, for any shares you want to move files from.
  2. Set the Mover action field to Array -> Cache.
  3. Disable any Docker and VM services, if they are enabled, as files open in these services cannot be moved.
  4. Go to Main > Array Operation, and select Move to manually move files from the array to the pool (cache).
  5. When mover finishes, you can re-enable the Docker and/or VMs services you use if you disabled them earlier.

Allocation method​

When you create a new user share, 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 stored on. In general, a new user share, or object within a user share, is created on the data disk with the most free space. However, there are a set of configuration parameters available to fine-tune disk allocation.

The basic allocation strategy for a share is defined by its allocation method configuration parameter. You may select one of three allocation methods for the system to use: High-water, Most-free, or Fill-up.

High-water method​

The High-water setting works with switch points based on continually halving the size of the largest drive in the array. It does multiple passes to fill each disk so at the end of each step there is equal free space left on each disk. This progressively fills each disk but without constantly going back and forth between disks each time new data is written. 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.

Example

If you have an array that consists of drives of 8 TB, 3 TB and 2 TB, the largest drive is the one that sets the switch points at 4 TB, 2 TB, 1 TB, and so on, halving the amount in each pass.

  • While the 4 TB switch point is active the 8 TB drive one is filled to 4 TB free space left.
  • When the 2 TB switch point becomes active, the 8 TB and 3 TB drives each get used in disk order until they have 2 TB free space
  • Finally, the 1 TB switch point becomes active, so each drive now gets used in disk order until there is only 1 TB free space.

This pattern continues with progressively smaller high-water levels until the disks are full.

Fill-up method​

The fill-up allocation method 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.

Most-free method​

The most free allocation method 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 included disks and pick the one with the most free space.

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.

Automatically split any directory as required​

When a new file or subdirectory is created in a share, Unraid OS first chooses which disk it is created on, according to the configured Allocation method. If the parent directory containing the new file or subdirectory does not exist on this disk, then Unraid OS will first create all necessary parent directories, and then create the new file or subdirectory.

Automatically split only the top level directory as required​

When a new file or subdirectory is being created in the first level subdirectory of a share, if that first level subdirectory does not exist on the disk being written, then the subdirectory will be created first. If a new file or subdirectory is being created in the second or lower level subdirectory of a share, the new file or subdirectory is created on the same disk as the new file or subdirectory's parent directory.

Automatically split only the top "N" level directories as required​

Similar to the previous option. When a new file or subdirectory is being created, if the parent directory is at level "N", and does not exist on the chosen disk, Unraid OS will first create all necessary parent directories. If the parent directory of the new file or subdirectory is beyond level "N", then the new file or subdirectory is created on the same disk where the parent directory exists.

Manual - do not automatically split directories​

When a new file or subdirectory needs to be created in a share, Unraid OS will only consider disks where the parent directory already exists.

info

In the event of there being conflicts between the Minimum free space, Split Level and the Allocation method settings in deciding which would be an appropriate drive to use, the Split level setting always wins. This means that you can get an out-of-space error even though there is plenty of space on other array drives that the share can logically use.

Included or excluded disks​

These settings allow you to control which array drives can hold files for the share. Never set both values, set only the one that is most convenient for you. If no drives are specified under these settings then all drives allowed under Settings > Global Share settings are allowed.

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, it will use the split level and allocation method to pick a disk which is allowed to hold the file.

important

The include/exclude settings at the individual share level only control which disks new files can be written to. Files on other disks that are in a folder corresponding to the share name will still show up under that share for read purposes.

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.

Default Shares​

If Docker or VMs are enabled then, Unraid automatically sets up a number of default shares to support their use. You are not required to use these shares, and the system will let you remove them if you do not want to use them for their standard purpose. However, we recommend their use, as it makes it easier to support users who encounter problems.

The shares that fall into this category are:

  • appdata - This is the default location for storing working files associated with docker containers. Typically there will be a sub-folder for each docker container.
  • system - This is the default location for storing the docker application binaries, and VM XML templates
  • domains - This is the default location for storing virtual disk images (vdisks) that are used by VMs.
  • isos - This is the default location for storing CD ISO images for use with VMs.
important

We do not recommend changing the permissions on most default shares, as these may impact the functioning of docker containers and VMs. The exception is the isos share that can be shared over the network so you can place new ISOs to use in virtual machines.