OSM Documentation 0.1.0 Search

3. Shared folders

A shared folder is a folder on a volume that you give people access to: Photos, Documents, Media, Backups. You manage them in Settings > Shared Folders.

The same permissions hold everywhere: in Files, over SMB and NFS, over SFTP, and for the apps that use the folder. OSM writes them as standard Linux access lists (POSIX ACLs), also for the files and folders created later.

Creating a shared folder

In Settings > Shared Folders, Create opens a dialog with three tabs: General, Permissions and Quota. On General:

  • Name and Description (optional). The name is also the folder's name on the network.
  • Location: the volume it lives on. Choose a Btrfs or ZFS volume if you want snapshots and earlier versions.
  • Share it over SMB (Windows, macOS, Linux), and Hide it in the network's list of shares (it stays reachable by its name). SMB is installed in Settings > File Protocols.
  • A Time Machine destination for Macs, with a size its backups may not exceed if you want (Files).
  • Recycle bin: what is deleted goes to its Recycle Bin folder first, and is emptied after a number of days or by hand.
  • Encrypt it (gocryptfs): only when the folder is created (below).

Edit changes these later, the name too. A renamed folder keeps its snapshots, its shared links, Media Streaming and the search. A folder that apps use cannot be renamed, nor one that a backup, cloud or replication task names: OSM lists those tasks, to change or remove first. An encrypted folder keeps its name: to have it under another name, create a new encrypted folder and move the files into it.

Permissions

For each shared folder, give every account and every group one of:

  • Read/Write: read, add, change and delete;
  • Read only: read and download;
  • No access: not even its name in a list;
  • — (not set): its groups decide.

Rules:

  • An account's own setting wins over its groups'. A group setting is the simple way to manage many people: give the group access, and add people to the group.
  • Apps is a line of its own: the container apps that use the folder (Jellyfin reading Media, for example).
  • A new shared folder gives the Administrators group Read/Write, and nobody else any access until you add them. Everyone is the built-in group of every account that may sign in.
  • When you change the permissions of an existing folder, Also set them on everything in the folder applies them to what it already holds, in the background.

When the server is joined to a directory (Accounts), its accounts and groups can be given access too, but only with the API or the command line (osm-cli.py call shares.update, see API and command line): Settings > Shared Folders lists this server's own accounts and groups.

Quotas

Quota sets the largest size of a shared folder (the Quota tab, Limit its size). Computers connected over SMB see that size as the folder's size. Quotas work on ext4 volumes with quotas on (every new ext4 volume), on Btrfs and on ZFS. An older ext4 volume made without them has Turn on quotas... on its card in Storage > Storage.

Each account can also have a quota on each ext4 volume with quotas on: Edit the account in Settings > Users and Groups, then its Quota tab.

The recycle bin

With the recycle bin on, what is deleted in Files or over SMB goes to the shared folder's Recycle Bin folder first, in the same place it was below the folder.

  • Restore in Files puts a file back where it was.
  • Empty recycle bin in Settings > Shared Folders deletes its contents for good. The bin also empties itself of what is older than the number of days you chose (0: only by hand).
  • Recycle bins are left out of backups, cloud tasks, search and virus scans.

Encrypted shared folders

A shared folder can be encrypted when it is created (with gocryptfs, and a password of 8 characters or more). Its files are stored encrypted on the disks, and readable only while it is unlocked with its password.

  • Lock / Unlock in Settings > Shared Folders locks or unlocks it. While locked, it is gone from Files and SMB, and nobody can read it, not even an Administrator.
  • Unlock at start-up... has OSM keep its password so it unlocks when the server starts. With a TPM 2.0 chip, the password is sealed in it: the disks, even all of them, give nothing away on another computer. Without a TPM, the password is kept on the system disks, which protects data disks that are taken away alone.
  • An encrypted folder has no quota and no snapshots, is not shared over NFS, and is never indexed for search.
  • Keep the password somewhere safe. Without it, nobody can read the folder.

Snapshots and earlier versions

On Btrfs and ZFS volumes, snapshots keep the earlier versions of every file in a shared folder: set them up in Storage > Snapshots (Storage). People see them in Files (Earlier versions) and in Windows (Previous Versions).

Moving in from another server

Copy from another server... in Settings > Shared Folders copies the shared folders of your old server (another NAS, a Windows or Linux computer) into shared folders here. OSM only reads the old server: nothing there changes.

  1. The old server: how it shares its folders (Windows file sharing (SMB), which Windows, macOS and most NAS use, or NFS), its name or address, and for SMB an account that may read every folder you want to copy (and, under More, its domain or SMB version). The first time, OSM offers to install what it needs (cifs-utils, smbclient and nfs-common).
  2. What to copy, and where: the folders the old server shares. Tick those to copy, and choose for each a new shared folder (named like the old one; you can change the name) or one you have. An NFS server that lists none: add each export by its path.
  3. Who may use them: for each new shared folder, the permission of every account and group. People need accounts of their own first: passwords cannot be copied from any server, so each person gets a new one. Import accounts from a list... makes many at once from a CSV file (Accounts).
  4. Copy: Start copying. It runs in the background, also while you are away and while OSM updates itself, and Copies from other servers, below the list, shows how far it is.

What a copy does:

  • Files keep their dates. A shared folder's permissions apply to what it receives.
  • Nothing is ever deleted here, and a file that is newer here is never replaced: what people changed on the new server stays.
  • The old server's recycle bins, snapshots and thumbnails are left out (you can untick that). So are links and special files.
  • Pause stops it, Resume goes on where it was. A copy that the server's restart stopped says so and goes on with Resume.
  • Copy what changed copies, later, only what is new or changed on the old server since: run it as often as you like, until the day you switch.
  • Report... lists the files a copy could not copy, and why (the account may not read them, a link, no room left). OSM tells you when a copy is finished.
  • The old server's password is kept only until the first copy is finished, unless you tick Keep the old server's password; it is never shown again. Forget removes a copy from the list (what it copied stays).
  • Over NFS, this server reads what the old server lets its root account read: share the folders with this server without "root squash", or make them readable by everyone.

Deleting a shared folder

Delete stops sharing the folder. Its files stay on the volume unless you tick the box to delete them too. What Settings > Search Index read of it goes. OSM refuses while apps use the folder. Its immutable snapshots stay until their time; on ZFS, its files can be deleted only after that.