Hi everyone, I have a question regarding hard-link behavior in Unraid (v7.1.4) when using /mnt/user paths with media scrapers such as Nastools.

📂 Current setup

/mnt/diskX/影视/电影 is for pt download path,My real media storage path is like:（影视 and Media are the sharing folders， and Split Level = Automatically split only the top 2 diretory levels as required）

/mnt/diskX/影视/电影/movie_name.mkv
or
/mnt/diskX/影视/电影/movie_name/movie_name.mkv

Scraping tools will create a hard link like:

/mnt/diskX/Media/Movie/movie_name/movie_name.mkv

This works, but it means every time I add a new disk, I need to add another individual path mapping in the container. That‘s inconvenient.

✅ What I want to do

Instead of mapping every single /mnt/diskX path, I want to just map:

/mnt/user/影视   :   /NAS/影视
/mnt/user/Media :  /NAS/Media
or more simple, just
/mnt/user : /NAS

So the scraper sees:

/NAS/影视/电影/movie_name.mkv
or
/NAS/影视/电影/movie_name/movie_name.mkv
→ hard-linked to
/NAS/Media/Movie/movie_name/movie_name.mkv

❓ My questions

1. Will the hard link always be placed on the same disk as the source file?

Example:

Real file is on:

/mnt/disk2/影视/电影/movie_name.mkv
in docker ,it is
/NAS/影视/电影/movie_name.mkv

If I create a hard link through /mnt/user, will the link always go to:

/mnt/disk2/Media/Movie/movie_name/movie_name.mkv
in docker , it is 
/NAS/Media/Movie/movie_name/movie_name.mkv

and never accidentally land on a different disk?

In other words — does the FUSE /mnt/user layer guarantee hard links stay on the same physical disk as the source file?

---

2. Moving files that contain both original + hard links

In Unraid 7.1.4, if I use Unbalance or the built-in file manager to move a folder between differen disks that contains both the source file and its hard link:

• Does Unraid keep the hard-link relationship?

• Does the moved data still consume disk space only once?

• If there's a setting to preserve hard links during move, where is it?
  (I remember seeing a related option a long time ago but can't find it now.)

---

🧰 Environment

• Unraid 7.1.4

• XFS array disks

• Nastools (hard-link mode)

---

Thanks in advance! 🙏 Any clarification would be really appreciated.

Edited November 5, 2025Nov 5 by xemaco

Review:

https://trash-guides.info/File-and-Folder-Structure/How-to-set-up/Unraid/

I usualy only hear about the hard links sym lilnk stuff when people try and setup the Arrs system..
example ars compose setup...
https://forums.unraid.net/topic/194760-dockers-fail-to-communicate-on-unraid-72/#findComment-1588190

Short answer up front:

• Yes—if you create a hard-link via /mnt/user, Unraid’s FUSE layer (shfs) will only succeed when the source and destination resolve to the same underlying disk. If the paths would land on different disks, the hard-link syscall fails with a “cross-device link” error (EXDEV) and most apps fall back to copying. It won’t silently hard-link across disks. see https://forums.unraid.net/topic/51381-hard-links-on-user-shares/

• Moving data between disks breaks the hard-link relationship (because a single inode can’t span filesystems). You’ll either end up with two independent files (double space) or need a tool that recreates hard-links after the move (e.g., rsync -H). https://docs.unraid.net/unraid-os/using-unraid-to/manage-storage/shares/

  • Shares realy should be primary only...

1) Mapping /mnt/user in Docker and hard-links

• Mapping just /mnt/user → /NAS is fine. When your scraper asks for a hard-link:

  • If /NAS/影视/... and /NAS/Media/... both point to folders that Unraid has placed on disk2, shfs makes the hard-link on disk2.

  • If allocator rules would put the destination on another disk, the call fails with EXDEV (“Invalid cross-device link”). Apps that support “hard-link or copy” will then copy.

• Make sure Global Share Settings → “Enable hard links” is Yes (sometimes shown as “Tunable (support Hard Links)” in guides). Without it, many link operations will be blocked or slow.

How to maximize “same-disk” probability

• Keep “download” and “library” in the same user share (e.g., a single Media share with downloads/ and library/ subfolders) and use Split level rules that keep each movie/show folder together. That nudges Unraid to place both the original and the link target on the same disk. (Hard-links require same disk regardless of using /mnt/user.)

• Avoid Most-free allocation for link-heavy workflows; it’s the most likely to scatter files across disks. Prefer High-water or Fill-up. There are active reports of mover/allocator interactions selecting different disks and thereby breaking link expectations.

---

2) Moving folders that contain originals + hard-links

• Within the same disk: a “move” is just a rename; hard-links remain intact and space is still counted once. (You can do this safely with Dynamix File Manager if you’re sure the path stays on the same /mnt/diskX.)

• Across disks (user shares or Unbalance default move): a move becomes copy+delete; there is no way to carry the single inode across filesystems, so hard-linked files become independent copies and space usage increases. Many users discover “moved 2.2 TB but space only dropped 1.5 TB” because hard-linked siblings remain on the old disk.

How to preserve hard-links when you must rebalance

• Use rsync with -aH to re-create hard-links at the destination. Unbalance lets you add custom rsync flags; users report success adding -XH (xattrs + hard-links) in Unbalance settings. Note: -H forces rsync to scan the entire transfer set to detect link groups; expect more RAM/CPU.

• Be cautious with the Mover. There are ongoing reports (7.0/7.1 era) where mover operations can break hard-links when the allocator chooses different disks for link siblings. Until that’s fully resolved, the safest approach is to write directly to the final disk for link-heavy shares or keep them cache-only and avoid mover for those paths.

---

3) Practical recipe for your Nastools layout

1. In Settings → Global Share Settings: enable Hard links.

2. Use one share (e.g., Media) with subfolders 影视/电影/ and Library/Movie/.

3. Set Split level so each movie folder stays on one disk (e.g., “automatically split only top 2 levels” fits your tree). This keeps the original and library path likely co-located.

4. Prefer High-water (or Fill-up) over Most-free.

5. If you must rebalance or evacuate a disk, use Unbalance with rsync flags -aH (and -X if you care about xattrs) to preserve link groups.

Answers to your Q/A bullets

• Will a hard-link via /mnt/user always land on the same disk as the source?
  Yes, or it fails. Hard-links never “hop” to a different disk. If the destination resolves to another disk, the call returns EXDEV; tools may then copy instead of link.

• If I move a folder with originals + hard-links between disks, will Unraid keep the relationship and single space usage?
  Not by default. Cross-disk moves break the shared inode. Use rsync -H (e.g., via Unbalance custom flags) to rebuild the hard-links on the destination. Otherwise you’ll consume space twice.

Please review: https://forums.unraid.net/topic/51381-hard-links-on-user-shares/ and https://www.reddit.com/r/unRAID/comments/1kpxzpa/unbalance_and_preserve_hard_links/