Differences

This shows you the differences between two versions of the page.

--- user:rion [2021/09/28 07:36] – cya (now in the CRT guide) atari
+++ user:rion [2026/06/10 14:45] (current) – rion
@@ Line 1: / Line 1: @@
+====== Storage Manager ======
+{{toc>}}
+> Introduced in **Batocera v43**.
+Batocera's **Storage Manager** allows you to expand your ROM storage across multiple drives while keeping a single unified game library.
+USB drives, external hard drives, SSDs, SD cards, and additional internal drives can all be used.
+<WRAP tip>
+The Storage Manager introduced in Batocera v43 allows multiple drives to be combined into a single ROM library without requiring symbolic links, manual mounts, or custom scripts.
+</WRAP>
+{{wiki:use_external_storage_system_settings.png?nolink&576|Storage Manager location in System Settings}}
+===== Overview =====
+The Storage Manager can:
+  * Detect compatible storage devices automatically
+  * Merge existing ROM drives
+  * Format and prepare new drives
+  * Use multiple drives simultaneously
+  * Present all ROMs as a single library under ''/userdata/roms''
+  * Safely eject drives
+  * Automatically refresh game lists
+From the user's point of view, there is still only one ROM folder:
+<code>
+/userdata/roms
+</code>
+Batocera handles the storage pool in the background.
+{{wiki:use_external_storage_storage_overview_diagram.png?nolink&576|Storage Manager overview}}
+A simplified overview:
+<code>
+Internal ROMs
+     │
+Drive 1 /roms
+     │
+Drive 2 /roms
+     │
+  MergerFS
+     │
+/userdata/roms
+</code>
+===== Requirements =====
+A drive must contain a root-level folder named:
+<code>
+roms
+</code>
+Supported:
+<code>
+Drive
+└── roms
+    ├── nes
+    ├── snes
+    └── psx
+</code>
+Not supported:
+<code>
+Drive
+└── Batocera
+    └── roms
+</code>
+Not supported:
+<code>
+Drive
+├── nes
+├── snes
+└── psx
+</code>
+The Storage Manager currently expects the ''roms'' folder to exist directly in the root of the mounted drive.
+===== Using Existing Drives =====
+When Batocera detects a mounted drive containing a compatible root-level ''roms'' folder, it offers to merge the drive into the Storage Manager.
+{{wiki:use_external_storage_merge_existing_drive_prompt.png?nolink&576|Merge existing drive prompt}}
+After accepting the prompt, Batocera adds the drive to the storage pool.
+{{wiki:use_external_storage_merge_existing_drive_complete.png?nolink&576|Merge complete}}
+After the merge completes, the ROMs stored on the drive become available alongside your existing collection.
+===== Formatting a New Drive =====
+If a blank drive is detected, Batocera can automatically prepare it for game storage.
+{{wiki:use_external_storage_format_new_drive_prompt.png?nolink&576|Format and merge prompt}}
+<WRAP important>
+Formatting a drive will permanently erase all existing data stored on that drive. Make sure any important files have been backed up before proceeding.
+</WRAP>
+Selecting **Format & Merge** will format the drive and add it to the Storage Manager.
+{{wiki:use_external_storage_format_confirmation.png?nolink&576|Format confirmation}}
+Batocera will:
+  * Format the drive
+  * Create a root-level ''roms'' folder
+  * Generate the standard ROM directory structure
+  * Merge the drive into the Storage Manager
+  * Refresh the game lists
+{{wiki:use_external_storage_formatting_drive.png?nolink&576|Formatting drive}}
+===== Using Multiple Drives =====
+Multiple drives can be used simultaneously.
+Example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+Batocera combines them into a single virtual library:
+<code>
+/userdata/roms
+</code>
+Games can be distributed across multiple drives while still appearing as one collection inside EmulationStation.
+===== Internal Drives =====
+The Storage Manager is not limited to removable USB devices.
+Additional internal drives can also be used.
+For example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+As long as the drive is mounted by Batocera and contains a root-level ''roms'' folder, it can be merged into the Storage Manager.
+This includes:
+  * SATA hard drives
+  * SATA SSDs
+  * NVMe SSDs
+  * USB storage devices
+  * SD cards
+<WRAP info>
+The drive name does not matter. What matters is that the mounted drive contains a root-level ''roms'' folder.
+</WRAP>
+===== Safe Drive Removal =====
+Drives can be safely removed from:
+  * **Main Menu**
+  * **System Settings**
+  * **Eject an Extra Disk**
+{{wiki:use_external_storage_safe_eject_menu.png?nolink&576|Safe eject menu}}
+After selecting the drive, Batocera asks for confirmation before removing it from the storage pool.
+{{wiki:use_external_storage_safe_eject_confirmation.png?nolink&576|Eject confirmation}}
+Batocera automatically updates the storage pool and refreshes the game lists.
+{{wiki:use_external_storage_drive_ejected.png?nolink&576|Drive ejected}}
+Games stored only on the removed drive will disappear from the library until that drive is connected and merged again.
+===== What Gets Merged? =====
+Only the ROM library is merged:
+<code>
+/userdata/roms
+</code>
+Folders such as:
+<code>
+/userdata/bios
+/userdata/saves
+/userdata/screenshots
+/userdata/themes
+/userdata/music
+</code>
+remain on internal storage.
+The Storage Manager does not merge BIOS files, save files, screenshots, themes, or music.
+===== Internal ROM Preservation =====
+When the first additional ROM drive is merged, Batocera preserves the existing internal ROM collection.
+Internally, existing ROMs stored in:
+<code>
+/userdata/roms
+</code>
+are moved into:
+<code>
+/userdata/.roms_base
+</code>
+This allows internal ROMs to remain visible alongside ROMs stored on merged drives.
+If all merged drives are later removed, Batocera restores the internal ROM library back to the normal ''/userdata/roms'' location.
+===== Limitations =====
+The Storage Manager currently requires this layout:
+<code>
+<drive>/roms
+</code>
+Nested ROM folders are not detected automatically.
+Example:
+<code>
+<drive>/Batocera/roms
+</code>
+is not automatically merged.
+Only the ROM library is merged. Other userdata folders remain independent.
+===== Advanced Technical Details =====
+Batocera uses **MergerFS** to combine ROM folders from multiple drives into a single virtual directory.
+The merged library is presented at:
+<code>
+/userdata/roms
+</code>
+Internally, Batocera maintains a storage pool containing:
+<code>
+/userdata/.roms_base
+</code>
+plus any merged ROM folders.
+Example:
+<code>
+/userdata/.roms_base
+/media/roms1/roms
+/media/roms2/roms
+</code>
+These locations are combined into:
+<code>
+/userdata/roms
+</code>
+==== MergerFS File Placement Policy ====
+Batocera currently uses the following MergerFS create policy:
+<code>
+category.create=eplfs
+moveonenospc=true
+minfreespace=4G
+</code>
+**eplfs** means:
+<code>
+Existing Path, Least Free Space
+</code>
+When writing a new file:
+  * MergerFS looks for branches where the target folder already exists
+  * Among those branches, the branch with the least free space is preferred
+  * Branches with less than 4 GB free are ignored
+  * If a drive becomes full during a write operation, the file can automatically move to another branch
+Example:
+<code>
+/media/roms1/roms/nes   900 GB free
+/media/roms2/roms/nes   200 GB free
+</code>
+A new ROM copied into:
+<code>
+/userdata/roms/nes
+</code>
+would be stored on:
+<code>
+/media/roms2/roms/nes
+</code>
+because it has the least free space while still meeting the minimum free space requirement.
+<WRAP important>
+The MergerFS implementation and file placement policy may change between Batocera releases. This section reflects the behavior introduced with Batocera v43.
+</WRAP>
+===== Frequently Asked Questions =====
+==== Can I use internal drives? ====
+Yes. Any drive mounted by Batocera containing a root-level ''roms'' folder can be merged into the Storage Manager.
+Example:
+<code>
+/media/roms1/roms
+/media/roms2/roms
+</code>
+==== What happens if I unplug a merged drive? ====
+Batocera updates the storage pool and refreshes the game lists.
+Games stored only on the disconnected drive will temporarily disappear until the drive is connected again.
+==== Are BIOS files merged? ====
+No.
+Only:
+<code>
+/userdata/roms
+</code>
+is merged.
+BIOS files remain stored in:
+<code>
+/userdata/bios
+</code>
+==== Are saves merged? ====
+No.
+Save files remain stored in the normal userdata location, for example:
+<code>
+/userdata/saves
+</code>
+==== Can I store ROMs in a different folder? ====
+No.
+The Storage Manager currently expects a root-level folder named:
+<code>
+roms
+</code>
+==== Does the drive name matter? ====
+No.
+For example, both of these are valid if they contain a root-level ''roms'' folder:
+<code>
+/media/roms1/roms
+/media/MyGamesDrive/roms
+</code>
+===== References =====
+  * Batocera TV — ''Batocera 43 - Episode II''
+    * Storage Manager demonstration:
+      * https://youtu.be/XpH27Yswe38?t=143
+  * Batocera Storage Manager source code:
+    * https://github.com/batocera-linux/batocera.linux/blob/master/package/batocera/core/batocera-scripts/scripts/batocera-storage-manager