Store games on a NAS
Instead of using the internal storage or an external USB key/hard drive to store your userdata (games, saves, configuration, etc.), you can use a NAS (Network Attached Storage) instead.
Recommended watching: Batocera Nation's advanced features volume 4.
Batocera repeatedly checks for a network connection on boot, and if none is present then it will automatically fall back to using internal storage. It is not possible to switch the location of your userdata without rebooting. If using NAS on a device which has a switch to turn on or off Wi-Fi, keep this fact in mind, as turning off the Wi-Fi will effectively wipe the userdata folder from Batocera's perspective.
In general, if using Batocera on a portable device it's not recommended to use a local NAS for its storage anyway due to the instability of its Wi-Fi. Syncthing offers a much more secure method of syncing data between portable devices.
Syntax
You will need to replace the sharedevice=INTERNAL
line with sharedevice=NETWORK
inside batocera-boot.conf
. This file is on the boot partition of the Batocera system. If on a removable drive, you can edit it from any computer as it is in a readable FAT32 file system (don't use Windows Notepad).
You can tell if you have successfully done this as the Storage Device in Main Menu > System Settings will be blank! But that could also mean you've entered an invalid entry to sharedevice
…
Batocera uses a simpler syntax than standard Linux network mounting. For each network share you'd like to attach, add an additional line below sharedevice
beginning with sharenetwork_smb#=
(for most Windows Samba shares) or sharenetwork_nfs#
(for most Linux Network File System shares) where # is the number of the share from 0-9 (yes, this does mean you're limited to only ten shares per type of share, this limit may be changed in the future). Following this, put in the keyword for the appropriate directory you want to replace in Batocera (as listed below).
There are the pre-defined keywords you can use:
Keyword | Description |
---|---|
SHARE | For the whole user data directory. |
ROMS | For the roms directory. |
BIOS | For the bios directory. |
SAVES | For the saves directory. |
MUSIC | For custom menu background music. |
DECORATIONS | For custom bezels. |
SCREENSHOTS | For screenshots taken in game or with batocera-screenshot . |
THEMES | For themes. |
CHEATS | For cheat databases. |
SOUNDS | For sounds (v32 and above). |
LIBRARY | For magazine and videos. |
SPLASH | For the boot splash. |
You can add any combination of the above (except SHARE
as that includes everything) by adding additional lines.
If you map only certain directories to your NAS, Batocera will search the internal storage for the remaining directories.
For Samba
@[IP-address/hostname]:[share-name]/[path/to/directory]:[option1-name]=[option1-value],[option2-name]=[option2-value],[etc.]
Then add the @ symbol, the IP address/hostname of the device with the share, the : character, the name of the share followed by a /, then the path to the directory (using Unix syntax / instead of \), another : character and then any additional options required for the share separated by a comma (,) (guest shares need only :guest
as an option, password protected shares need :username=[your-username],password=[your-password]
). Syntax:
sharenetwork_[smb-or-nfs][0-9]=[keyword]@[IP-address/hostname]:[share-name]/[path/to/directory]:[option1-name]=[option1-value],[option2-name]=[option2-value],[etc.]
For NFS
@[IP-address]:[/absolute/path/to/directory]:[option1-name]=[option1-value],[option2-name]=[option2-value],[etc.]
Examples are below. If you don't know the exact address to your share already, check the discover network share names section below.
If Batocera fails to connect to the network at boot, it will wait approximately one minute retrying to connect before falling back to internal storage.
Samba/Windows share examples
Windows shares can use identification or a guest account to connect.
In the following examples, the Windows CIFS share called Documents has a folder named batocera
which contains the folder structure of Batocera's userdata directory. The IP address of the Windows shared server is 192.168.0.1 in this example. If applicable, you can use the hostname of your NAS instead, however this may have issues with particular routers.
The whole user data directory on the NAS
sharedevice=NETWORK sharenetwork_smb1=SHARE@192.168.0.1:Documents/batocera:guest
Only the ROMs directory on the NAS
sharedevice=NETWORK sharenetwork_smb1=ROMS@192.168.0.1:Documents/batocera/roms:guest
Only the ROMs directory on the NAS with CIFS authentication
Unless you really know what you're doing, it is ill-advised to set up the NAS with a username and password for your ROMs, saves and system folders. This can interfere with Batocera's access to executable bits, leading to the same problems that the NTFS filesystem has.
It is recommended however to use authentication for your NAS in general, it's possible to create an additional share that only shares the ROMs folder with guest access for example.
If your NAS was already using NTFS then this limitation is already in affect, thus it would be no different to using authentication anyway.
sharedevice=NETWORK sharenetwork_smb1=ROMS@192.168.0.1:Documents/batocera/roms:username=john,password=wayne
The ROMs, saves and BIOS directories on the NAS
sharedevice=NETWORK sharenetwork_smb1=ROMS@192.168.0.1:Documents/batocera/roms:guest sharenetwork_smb2=SAVES@192.168.0.1:Documents/batocera/saves:guest sharenetwork_smb3=BIOS@192.168.0.1:Documents/batocera/bios:guest
Specific SMB version options
In several cases, you need to add SMB options, for instance if you NAS requires a specific CIFS version:
sharenetwork_smb1=ROMS@192.168.0.1:Documents/Batocera/roms:guest,vers=1.0
CIFS version is needed for several NAS vendors:
- when using and Orange Livebox as a NAS, or on Synology (tested on a DS418play), you need
vers=1.0
- if you use OpenMediaVault 5, you need
vers=3.0
In this kind of setup, make sure that:
- you provide the exact name your SMB share on the NAS (
Documents/Batocera/roms
in the example above is the path from your NAS export) - you have the right user authentication (
username=john,password=wayne
in the example above) and, if you use anonymousguest
access, that you have write access enabled, so that Batocera can write the updated in thegamelist.xml
files, and download scraped metadata like thumbnails or video snapshots.
NFS share examples
The whole user data directory on the NAS
sharedevice=NETWORK sharenetwork_nfs1=SHARE@192.168.0.1:/mnt/Documents/batocera
Only the ROMs directory on the NAS, with a specific NFS version
sharedevice=NETWORK sharenetwork_nfs1=ROMS@192.168.0.1:/mnt/Documents/batocera/roms:vers=4
The ROMs, saves and BIOS directories on the NAS
sharedevice=NETWORK sharenetwork_nfs1=ROMS@192.168.0.1:/mnt/Documents/batocera/roms sharenetwork_nfs2=SAVES@192.168.0.1:/mnt/Documents/batocera/saves sharenetwork_nfs3=BIOS@192.168.0.1:/mnt/Documents/batocera/bios
Mounting network shares behind a VPN or Tailscale network
Background
Mounting a shared folder on a server that requires a VPN or Tailscale connection to be established first is troublesome due to the Batocera boot initialization process. While Batocera does provide various options for you to execute a custom script throughout the boot process, none of them are suitable due to several factors. The setup procedure in the VPN/Tailscale documentation is great for setting up things like multiplayer, but too late for mounting Batocera core folders.
Basic boot process flow:
1. /boot/boot-custom.sh - At this stage, the system's network has not been initialized yet, therefore a VPN or Tailscale connection cannot be established.
2. /etc/init.d/S07network - This is where the network is initialized.
3. /etc/init.d/S11share - This is where the /userdata is initialized.
4. /boot/postshare.sh - Executed right after /userdata initialization completed. By this point it is too late, and any attempts to mount a VPN/Tailscale network share will fail because those services haven't been initialized yet.
5. /userdata/system/custom.sh - This script is the suggested place for VPN/Tailscale initialization according to the docs, but it's also past the /userdata mounting stage.
From the above, we can see that the VPN/Tailscale client will need to be initialized somewhere between steps 2 and 3.
Workaround
There is a sharenetwork_cmd# feature that allows you to craft a custom mounting command, however, since it accepts any arbitrary shell command we can repurpose it to initialize our VPN/Tailscale client.
First, setup and test the VPN/Tailscale client according to the docs. Once you have successfully confirmed that everything is working, disable custom.sh
or comment out the lines relevant to VPN/Tailscale. Those clients are going to be initialized elsewhere.
The final result of my configuration looks something like the below. Note that in my example, I am using Tailscale and mounting NFS folders, although this should be adaptable for any combination of VPN/Tailscale and SMB/NFS. Also, in my example, I am incorporating an ARM-build fix where the /dev/net folder needs to be created in addition to a “sleep 2s” command because I have observed that the Tailscale daemon sometimes does not finish initializing before the Tailscale client asks it to bring up the network. Adjust these items according to your setup.
sharedevice=NETWORK sharenetwork_cmd1=eval if [ ! -d /dev/net ]; then mkdir -p /dev/net; mknod /dev/net/tun c 10 200; chmod 600 /dev/net/tun; fi && /userdata/tailscale/tailscaled -state /userdata/tailscale/state > /userdata/tailscale/tailscaled.log 2>&1 & sleep 2s; /userdata/tailscale/tailscale up --accept-routes sharenetwork_nfs1=ROMS@100.0.0.1:/mnt/Documents/batocera/roms sharenetwork_nfs2=SAVES@100.0.0.1:/mnt/Documents/batocera/saves sharenetwork_nfs3=BIOS@100.0.0.1:/mnt/Documents/batocera/bios
Advanced
Troubleshooting
Make sure you escape special characters in your CIFS passwords if you have some. To escape a character, put a \ in front of it. To escape a \ itself, use \\.
For troubleshooting purposes, you have /tmp/mountNetwork.log
and /tmp/mountNetwork.err
that will give you some insights on the mount failures if needed.
Discover network share names
If you haven't yet used the network share with other devices and aren't confident of the name of the share itself (very common for NASes to report a false path to go to to access their data) then you can “see” the available network shares from Batocera's file manager. On the system list, press [F1]
to open it. Then, in the menu at the top of the screen, navigate to Go → Network. The names of the available network shares (along with Batocera's own network share) will be shown:
This can be used to confirm that your Batocera machine can at least see the NAS. You may want to note down these names. You will not be able to access any shares from this menu, however.
Discover network share paths
Kodi can be used to see and access network shares. You may need your network share's name in order to do this. Open Kodi, then navigate to Files (a.k.a. Enter files section) → Files → Add media… (by default, Add videos…) → Browse → Add network location….
From here, enter the network share name (and your username and password if you don't have guest/anonymous access enabled on your NAS):
In the case that you don't know the name of the networked device (or one isn't available because your router has hostnames disabled/a very strict firewall) it is still possible to discover the IP address of the networked device from here.
Instead of going to Add network location…, instead go to Zeroconf browser. You will be shown a list of all devices. Select the one you wish to use, and if a username/password is required you will be prompted for one. After that, continue following the steps as usual, replacing the share name with the IP address you will be shown.
Your share will be added to the list of browseable devices, navigate to it (in this example, smb://RASPBERRYPI
) and then navigate to the folder you intend to use for Batocera.
Note down the file path stated at the bottom of the window, this is the path that should be used when configuring your NAS. eg. Kodi's path smb://RASPBERRYPI/samsung1tb/Emulation/roms
contains the share using the Samba (smb) protocol with the hostname RASPBERRYPI
with the share name samsung1tb
and the path being samsung1tb/Emulation/roms
. The correct configuration lines for batocera-boot.conf
would be:
sharedevice=NETWORK sharenetwork_smb1=ROMS@RASPBERRYPI:samsung1tb/Emulation/roms
Samba/Windows manually mounted shares
It is possible to map individual folders with sharenetwork_cmd#
if you are familiar with standard Linux network storage mounting. Examples of mapping other directories via sharenetwork_cmd:
sharenetwork_cmd1=mount.cifs -o guest //192.168.0.1/Documents/batocera/music /userdata/music sharenetwork_cmd2=mount.cifs -o guest //192.168.0.1/Documents/batocera/cheats /userdata/cheats sharenetwork_cmd3=mount.cifs -o guest //192.168.0.1/Documents/batocera/screenshots /userdata/screenshots sharenetwork_cmd4=mount.cifs -o guest //192.168.0.1/Documents/batocera/themes /userdata/themes
This will only work if sharedevice=NETWORK
. You can also use this to just mount anything with acceptable bash commands, including folders from local drives, etc.
These will appear as if though they are local to the drive, so keep that in mind when troubleshooting in the future!
NFS and root permissions
Batocera has a unique root
user, so all files accessed on the share are from the root
user, which can conflict with how other NFS clients access files. You should check how the file permissions are declared on your NFS server. A common way to make sure your file permissions are managed correctly is to map the file rights to the UID of the user that will access these files locally. Typically, if your NFS shares are defined in /etc/exports
and you want to give access to a user with UID/GID of 1000, you can make it with:
/media/games/batocera 192.168.0.1(rw,sync,all_squash,anonuid=1000,anongid=1000,no_subtree_check)
Troubleshooting
Logs for share mounting specifically can be found at /tmp/mountDevicesOrNetwork.err
after booting. If a network share is failing to be booted, Batocera will retry the connection a few times before falling back on internal storage.
- store_games_on_a_nas.txt
- Last modified: 10 months ago
- by cs