Skip to main content

shares

User shares as first-class SQLite state: each share has its own mergerfs mount and Samba is generated from the same rows. Per-user and per-group share access is stored here too, editable from either the share or the user/group.

📄️Create a share

Persists the share, creates its directory tree on the branches its cache mode uses, writes the per-share mergerfs mount through the existing pool renderer, and regenerates `smb.conf`. Refused with 409 `maintenance_mode` while the array is stopped: create would mkdir under bare disk mountpoints on the root filesystem, and the next array start would hide those writes. Refused with 409 `migration_in_progress` while an Unraid import is pending its point of no return: a new share would need a directory on every adopted disk, and those are not written until then. The import creates its own shares (`startMigrationImport`).

📄️Update a share

Updates cache mode, create policy and SMB options, then regenerates the per-share mount and `smb.conf`. Does not relocate existing files. Refused with 409 `maintenance_mode` while the array is stopped: update would mkdir and remount under bare disk mountpoints on the root filesystem. While an Unraid import is pending its point of no return it creates no directory on any adopted disk, and a cache mode that needs a cache is refused because none exists yet; choosing a cache mode here replaces the one the import recorded as the share's target.

📄️Relocate a share between cache and array

Queues a `share_relocation` job moving name's files between its cache path and the array — `hoserva share relocate <share> --to cache|array`. Cache to array behaves as a mover run limited to this share, ignoring the grace period; array to cache follows the two-phase copy-verify-sync- delete-sync order, through the same threshold guard every other sync goes through. There is no second relocation-invocation path. A relocation in either direction needs the array's cache disk, so it is refused with 409 `no_cache_disk` before any job is queued while the array has no cache disk, and with 409 `no_array` while there is no array; a failure to read the array topology fails the request rather than assuming a cache.

📄️List what a share relocation would collide with

What a caller shows before it starts `startShareRelocation`: the containers whose mounts use the share and every file of the share some process currently holds open, across the cache and every array branch. A container uses the share when a mount's host path is the share's pool path, a path inside it, or a path that holds it (`/mnt/user`, a disk or the cache itself), on the pool, on the cache or on a data disk; the match is made on the path as written, never through a symlink, so it reads no data disk. `active` is true for a container that is running, paused or restarting — one that can hold files open and that a relocation must not run beside. Listing the open files enumerates the share on the cache and on every array branch, so this is an explicit call that may wake disks — it is never polled. `dockerAvailable` is false, with no error and no containers, whenever Docker itself is not reachable. The answer covers both sides of the share, so it is the same whichever way the share will move. No answer is given in the cases `startShareRelocation` refuses before it queues a job: 409 `no_cache_disk` while the array has no cache disk, 409 `no_array` while there is no array, 409 `maintenance_mode` while the array is stopped, 409 `migration_in_progress` while an Unraid migration is unfinished and 409 `database_restore_in_progress` during a database restore. These are the scheduler's own admission checks, queried without submitting a job. Stopping a listed container goes through `stopApp`.