Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
modify_the_system_while_it_s_running [2021/09/30 02:44] – [Overlays] amended WRONG AND INCORRECT information (which I wrote in earlier whoops) atarimodify_the_system_while_it_s_running [2023/04/09 16:10] (current) – [Creating a Batocera filesystem overlay] maximumentropy
Line 1: Line 1:
-====== Overlays ======+====== Overlays (modify the live system) ======
  
-Batocera is like a firmware. It's a huge virtual filesystem image at ''/boot/boot/batocera'' (it has no extension in its filename) which expands into RAM at boot. You cannot modify it directly, and for most use cases, you shouldn't need to modify it. Most files in the ''/'' directory stem from this image. +Batocera is like a firmware. It's a huge filesystem image at ''/boot/boot/batocera'' (it has no extension in its filename) which is virtually mounted as the root of the drive in RAM at boot. You cannot modify the ''batocera'' file directly, and for most use cases, you shouldn'//need// to modify it. All folders except for ''userdata'' and ''boot'' in the ''/'' directory stem from this image.
- +
-The boot partition is mounted with read-only permissions at ''/boot/'', but can be [[:edit_boot_partition|remounted with write permissions post-boot]]. All the user data is stored in a separate userdata partition, which is mounted with write permissions at the path ''/userdata/''.+
  
 {{batocera_drive_layout.png?1000|An illustration showing how the batocera system is laid out on a USB stick: the BATOCERA partition first, containing all the programs, and then the SHARE, containing all the userdata}} {{batocera_drive_layout.png?1000|An illustration showing how the batocera system is laid out on a USB stick: the BATOCERA partition first, containing all the programs, and then the SHARE, containing all the userdata}}
  
-That said, you can utilize overlays to "patch" certain files over the ''batocera'' virtual filesystem image at boot.+Under normal circumstances, this file cannot be written to, and any changes made to the filesystem mounted in RAM will be lost upon shutdown. That said, you can utilize overlays to "patch" certain files over the ''batocera'' filesystem image at boot.
  
-<WRAP center round info 60%+===== Creating a Batocera filesystem overlay ===== 
-The boot partition remounting information has been moved to [[edit_boot_partition|its own page]].+ 
 +For modifications to the regular Batocera filesystem, you can directly edit the files in their directory using [[:built_file_manager|the built-in file manager]] while booted (for example if you want to play with the configgen scripts in ''/usr/lib/pythonX.X/site-packages/configgen/generators/'' or change the default platform parameters in ''/usr/share/batocera/configgen/configgen-defaults-arch.yml'') or sign in [[:access_the_batocera_via_ssh|via SSH]] or [[:winscp|SCP/FTP]] to make those alterations. Once the modifications are done, you can save them with [[:access_the_batocera_via_ssh|the command]] ''batocera-save-overlay''. This command script creates a patch file at ''/boot/boot/overlay'' which stores the differences between the current mounted filesystem and the one stored in ''/boot/batocera''
 + 
 +<WRAP center round tip
 +Refer to [[:notable_files|the notable files/folders page]] for some more interesting files!
 </WRAP> </WRAP>
  
-===== Editing system files ===== +By default, Batocera overlay files are limited to 100 MB. If your modifications are over 100 MB, you can specify the size of the overlay with the command. Keep always a bit of margin, the overlay will embed a few more files than those you were expecting (some system files created on-the-fly at boot time). For exampleif you need to save 120 MB of data on the system, you can type ''batocera-save-overlay 125''.
-If you need to edit files to assist in making Batocera boot or to set up external storagerefer to [[edit_boot_partition|editing the boot partition]].+
  
-For modifications to the regular Batocera virtual file system, you can directly edit the files in their directory while booted (for example if you want to play with the configgen scripts in ''/usr/lib/python3.9/site-packages/configgen/generators/'', change the default platform parameters in ''/usr/share/batocera/configgen/configgen-defaults-arch.yml'' or edit the available advanced options in ES in ''/usr/share/emulationstation/es_features.cfg''). Once the modifications are doneyou can save them with the command:+<WRAP center round important> 
 +This overlay file is automatically removed at the next upgrade. 
 +</WRAP> 
 + 
 +<WRAP center round tip> 
 +To view the contents of the overlay independently from the underlying filesystemit can be mounted in a separate location:
  
 <code> <code>
-batocera-save-overlay+mount /boot/boot/overlay /mnt 
 +find /mnt 
 +umount /mnt
 </code> </code>
  
-This script creates a patch file at ''/boot/boot/overlay'' which stores the differences between the current virtual file system and the one stored in ''/boot/batocera''.+</WRAP>
  
-<WRAP center round important 50%>**WARNING**: This overlay file is automatically removed at the next upgrade.</WRAP>+===== Removing the overlay =====
  
-If you don't use the ''batocera-save-overlay'' scriptyou can still edit the files in ''/usr/'' but any modification will be lost on reboot.+Even if you don't use the ''batocera-save-overlay'' script you can still edit the files in any of the root folders, but any modification made outside of ''/userdata'' or ''/boot'' will be lost on reboot. If you want to remove all your overlay modifications made after running ''batocera-save-overlay'' previously, simply [[:edit_boot_partition#editing_the_boot_partition_while_batocera_is_running|remove]] the ''/boot/boot/overlay'' file.
  
-If you want to remove all your customizations, just remove the ''/boot/boot/overlay'' file.+===== Cases when you don't need to modify the system =====
  
-By default, Batocera overlay files are limited to 50MB. If your modifications are over 50MByou can specify the size of the overlay with the command. Keep always a bit of margin, the overlay will embed few more files than those you were expecting (some system files created on-the-fly at boot time). For exampleif you need to save 120MB of data on the system, you can type ''batocera-save-overlay 120''.+Some best practices here: 
 +  * You don't need to edit ''/etc/fstab'' to mount external drivesuse [[:store_games_on_a_second_usb_sata_drive|configure your external storage]] or [[:store_games_on_a_nas|configure your NAS]] instead. 
 +  * You should not modify ''/usr/share/emulationstation/es_systems.cfg'' for altering the systems listed in EmulationStation. This is the base file updated with every release of Batocera. Insteadfollow the instructions at [[emulationstation:customize_systems|the customize systems page]] to create "patch" that's loaded on top of the base fileallowing for updates to the base file.
  
-<WRAP center round alert 60%> +===== I want to modify something in the boot folder though ===== 
-This cannot be done for the current (v31Odroid XU4 version. + 
-</WRAP>+The boot partition is mounted with read-only permissions at ''/boot/'', but can be [[:edit_boot_partition#editing_the_boot_partition_while_batocera_is_running|remounted with write permissions post-boot]]. You do not need to save an overlay for file edits made in the boot partition, as this is a physical partition where your edits are permanent (and because of that, any edits you make here are more dangerous and can result in a non-booting machine, always make backups before attempting this). All the user data is stored in a separate userdata partition, which is mounted with write permissions at the path ''/userdata/'' (like the boot partition, this is just your regular userdata storage partition, no need to save overlays for this either).
  
-===== Cases when you don't need to modify the system ===== 
-Some best practices here: 
-  * You generally don't need to edit ''/etc/fstab'', use [[store_games_on_a_second_usb_sata_drive|configure your external storage]] or [[store_games_on_a_nas|configure your NAS]] instead. 
-  * You should not modify ''/usr/share/emulationstation/es_systems.cfg''. Instead, follow the instructions at [[emulationstation:customize_systems|the customize systems page]]. 
  • modify_the_system_while_it_s_running.1632962690.txt.gz
  • Last modified: 3 years ago
  • by atari