Plugin/webGui/User Shares

From unRAID
< Plugin‎ | webGui
Jump to: navigation, search

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
        • 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
      • Dejavu
        • 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
      • 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
    • Dejavu
      • 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.

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 two Allocation methods for the system to use:

Most-Free

In this method, the system will simply pick the disk which currently has the most free space.

High-Water

In this method, the system will pick the disk which currently has the least free space that is still above a certain minimum (called the "high water" mark). Suppose in our example above, we have this situation:

disk size free
disk1 80GB 75GB
disk2 120GB 110GB
disk3 80GB 70GB


The initial high water mark is set to the 1/2 the size of the largest disk; in this case, it will be set to 60GB. In this state, disk1 has 15GB of free space above the "high water" mark; disk2 has 50GB, and disk3 has 10GB.

As new objects are created, the system will choose disk3 until the amount of free space on disk3 falls under 60GB. Subsequently, the system will start allocating from disk1 until it's free space falls under 60GB. Then it will allocate from disk2 until it's free space also falls under 60GB. Once the amount of free space on all disks is below 60GB, a new high water mark is established by dividing the old high water mark by 2.

The advantage of High-water method is that when writing a series of files, most of the time only one data disk will need to be spun up.

Split Level

Often media data will consolidated under a single directory, or directory tree. Then during playback the files will be accessed one after another. This is the case with the set of VOB files which make up a DVD movie. In this situation we want all the associated media files to be stored on the same physical disk if at all possible. This is because we don't want media playback to pause while the disk containing the next file spins up. unRAID OS solves this problem by introducing a configurable allocation parameter called "Split level".

Split level defines the highest level in the share directory hierarchy which can be split among multiple disks. In the Movie share example above, setting Split level to 1 only permits any object created directly under the Movie directory to be allocated to any disk according to the Allocation method. Thus, when we create the Alien subdirectory, it may reside on any of the data disks; however, when we create a file or another directory within the Movies/Alien directory, this object is at level 2, and will be created on whatever disk the Movies/Alien directory actually resides on.

If the share were organized differently, for example according to genre:

  • Movies
    • SciFi
      • Alien
    • Action
      • Basic
      • Dejavu
    • Kids
      • Cars

Then you would set Split level to 2. This will let the genres expand among all disks, but still ensure that the contents of the actual movie directories stay within the same disk.

If you set the Split level to 0 for a share, then all directories/files created under that share will be on the same disk where the share was originally created.

If you set the Split level high, e.g., 999 for a share, then every directory/file created under that share will get placed on a disk according to Allocation method.

Included and Excluded disk(s)

The last way to control which disks are used by a share is through the Included disks(s) and Excluded disk(s) configuration parameters.

The Included disks(s) parameter defines the set of disks which are candiates for allocation to that share. If Included disk(s) is blank, then all present data disks are candiates. For example, to restrict a share to using only disk1, disk2, and disk3, you would set Included disk(s) to disk1,disk2,disk3.

The Excluded disk(s) parameter defines the set of disks which are exluded from consideration for allocation. If Excluded disk(s) is blank, then no disks are excluded.

When considering which disk to allocate space for a new object, unRAID OS first checks if it's in the Included disks(s) set, and the checks if it's in the Excluded disk(s) set.

Creating User Shares

To create a new User share:

  1. Click the Add Share button at the bottom of the User shares list.
  2. Enter the new Share name and other configuration and click the Add Share button.

On version 4.7 of unRAID 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:

  1. Move or delete the contents of the user share.
  2. Check the Delete box next to the "Apply" button under Share Settings.
  3. Click the Delete button.

Note: Some operating systems add hidden files to the user share which will prevent you from deleting it. You can identify these files by executing the command below from a console (replace <sharename> with your user share name):

ls -a /mnt/user/<sharename>

On version 4.7 of unRAID 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:

  1. Click in the Share name field of the share.
  2. Type it's new name, and then click Apply.

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: Yes
Security: Secure

User Access
larry Read/Write

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

Export: Yes (hidden)
Security: Secure

User Access
mom Read/Write
dad Read/Write

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

Export: Yes (hidden)
Security: Secure

User Access
mom Read/Write
dad Read-only

Technical notes:

  • A user share configuration file called config/shares/.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.

Parameters

  • 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
    The method by which the system will select the disk to use for creating a User share, directory, or disk. See Allocation below.
  • Split level
    The maximum depth in the directory tree which may be split across multiple disks. See Split level below.
  • Included disk(s)
    The set of disks which will be considered for allocation. Blank means all disks. Disks are specified using the identifier disk1,disk2, etc. Separate each identifier with a comma.
  • Excluded disks(s)
    The set of disk which will be excluded from consideration for allocation. Blank means no disks.
  • 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.