run_batocera_in_vm [Batocera.linux

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Run Batocera in a Virtual Machine ======

Running Batocera in a virtual machine is not officially supported, nor will it be an accurate representation of how it will behave, but it can be useful for quickly testing custom images or UI changes.

<WRAP center round important>
Expect massive performance deficits compared to bare-metal installation. Virtual Machines don't take kindly to newer/modern graphics APIs and standards.
</WRAP>

===== Oracle VirtualBox =====

  - [[https://batocera.org/download|Download the latest Batocera x86_64 image.]]
  - Install [[https://www.virtualbox.org/wiki/Downloads|Oracle's VirtualBox]].
  - Install the VirtualBox #.#.# Oracle VM VirtualBox Extension Pack too. <WRAP center round tip>
If you need further help with installing VirtualBox, refer to their helpful [[https://www.virtualbox.org/manual/ch01.html#hostossupport|user manual]]
</WRAP>
  - If you downloaded the Batocera image file from the website, it is in ''.img.gz'' format. Uncompress the ''.gz'' part with your favorite uncompressing tool (7-Zip, WinRar...) to make it a ''.img'' file. Some browsers uncompress the file you downloaded by default.
  - Convert the Batocera IMG file to a VDI using the command line (''[Win]'' + ''[R]'', then type ''cmd''). For example, for the default VirtualBox installation using Batocera v33 beta: <code>
"C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" convertdd C:\batocera-x86_64-33-20211108.img C:\batocera-x86_64-33-20211108.vdi
</code>
  - Resize it to be larger, can also be done via command line. For example, to create an image that's 20GB in physical size: <code>
"C:\Program Files\Oracle\VirtualBox\VBoxManage.exe" modifyhd "C:\batocera-x86_64-33-20211108.vdi” --resize 20000
</code>
  - Run VirtualBox proper and create a new VM and select "Expert Mode".
    - Set the type "Microsoft Windows" and version to "Windows 7 (64bits)"; (It's just a label for predefined setup, maybe linux or oracle will be better for you, but try this one first)
    - Set available RAM to at least 2GB (2048MB);
    - Use the Batocera VDI file created earlier:\\ {{:vm-setup-1.png?direct| VirtualBox's new VM dialogue box at expert mode.}}
  - Once the VM has been created, adjust its settings like so:
    - Processor: **Processors:** "2". A higher setting might provide better performance, but try to stay within the green range for your computer. For host computers that only have two cores, use "1" here. **Execution Cap:** //100%//.\\ {{:vm-setup-3.png?direct|}}
    - Display: **Acceleration:** Tick "Enable 3D Acceleration". **Video Memory:** As high as you can go, "256MB" works fine.\\ {{:vm-setup-4.png?direct|}}
    - Network: **Adapter 02:** Tick "Enable Network". **Attached to:** "Bridge Adapter". **Promiscuous mode:** "Allow VMs"\\ {{:vm-setup-5.png?direct|}}
    - USB: Add desired devices (such as controllers, Bluetooth dongles, etc.) to the list:\\ {{:vm-setup-usb.png?direct|}}<WRAP center round info>
Peripherals that the VM automatically forwards through such as mouse, keyboard and network cards are not necessary to add here.
</WRAP>
  - If AUTO Audio and AUTO Video didn't work, change the following settings within Batocera:
    - **SYSTEM SETTINGS** -> **VIDEO OUTPUT** to "VIRTUAL-1",
    - **AUDIO OUTPUT** to "ALSA_OUTPUT_PCI.STEREO" and
    - **AUDIO PROFILE** to "PRO_AUDIO".\\ {{:vm-setup-9.png?direct&600|}}<WRAP center round tip>
If those settings don't produce audio, keep trying all permutations of **AUDIO PROFILE** and **AUDIO OUTPUT** until you find one that does. Remember to exit the menu each time to test the change!
</WRAP>

And we're done.

{{ :vm-setup-8.png?direct&600 |Oh the wonders of running Batocera in a virtual environment!}}

==== Post-installation setup ====

You can increase the output resolution releasing your cursor (right ''[Ctrl]'') and clicking **VIEW** -> **VIRTUAL SCREEN-1** in the menu toolbar of VirtualBox.

{{:vm-setup-7.png?direct|}}

You can still add files to Batocera using [[:add_games_bios|the usual methods]], even the network share.

As you already have the image .vdi, you can setup different environments for the same machine and test which one will be better for your PC, just make sure you are using a 64-bit one (or 32-bit if appropriate).

{{:vm-setup-10.png?direct|}}

===== Qemu =====

==== Method 1 ====

  - Download the image for Batocera from [[https://batocera.org/download|the main site]].
  - Download the following script and mark it as executable: https://raw.githubusercontent.com/batocera-linux/batocera.linux/master/scripts/linux/runQemu.sh
  - Create an empty "share" image containing the partition Batocera will use for its userdata and name it ''share.img'' (replacing ''5G'' with the size you desire, make it at least 5GB to support future upgrades): <code bash>
dd if=/dev/zero of=share.img count=5 bs=5G
</code> <WRAP center round tip>
To confirm that the blank share image has been created, run <code bash>
ls -lh share.img
</code> to check its reported space. For instance, a 5GB blank image should report back something like: <code bash>
-rw-rw-r-- 1 XXX XXX 5.0G XXX share.img
</code>
</WRAP>
    - Optionally, if you don't want to use Batocera itself to format the partition, create the filesystem manually with something such as: <code bash>
mkfs.ext4 share.img
</code> Otherwise it's fine to, after booting Batocera, go to **SYSTEM SETTINGS** -> **DEVELOPER** -> **FORMAT A DISK** and format it there.
    - Optionally, forward a gamepad connected to the host computer by running the following: <code bash>
udevadm info -q all -n /dev/bus/usb/001/002
echo 'SUBSYSTEM=="usb", ENV{ID_MODEL}=="Usb_Gamepad", MODE="0666"' >> /etc/udev/rules.d/99-joysticks-rw.rules
</code>
  - Then run the following to start up the Qemu virtual machine: <code bash>
./runQemu.sh ~/batocera-x86_64-XX-XXXXXXXX.img share.img
</code>

{{:bato_in_qemu.png?400|}}

The ''runQemu.sh'' script itself contains further instructions (that may get updated faster than this wiki). For an example of what an ordinary installation procedure might look like:

{{:bato_in_qemu_setup.png|}}

[[https://www.youtube.com/watch?v=6V9iZAe9xz8|A video demonstration of Batocera being run inside a Qemu VM.]]

=== Post-installation setup ===

You can still add files to Batocera using [[:add_games_bios|the usual methods]], even the network share.

In case you'd like to mount the share image to add files directly, run the following: <code bash>
X=$(sudo losetup -f)
mkdir -p BATOCERA
sudo losetup -P $X share.img
sudo mount ${X}p1 BATOCERA
sudo chmod -R 777 BATOCERA/
</code>

Then it should be automatically detected and mounted by your desktop environment.

==== Method 2 ====

  - Download the compressed Batocera image for x86_64 from [[https://batocera.org/download|the main site]] and extract the ''batocera*.img'' file from the compressed ''batocera*.img.tz'' tarball.
  - Expand the image to the size you'd like to assign to Batocera using ''fallocate''. At least 16 GB is recommended for full functionality, but if space is a concern then you can get away with just 7 GB: <code bash>
sudo fallocate -l 7G batocera.img
</code>
  - Install the ''virt-manager'' and ''qemu'' packages for your distro:
    * **On Debian/Ubuntu:** <code bash>
apt-get update
apt-get upgrade
apt-get install virt-manager qemu
</code>
    * **On Fedora/RPM-based:** Update your package lists, then: <code bash>
sudo dnf install virt-manager qemu
</code>
    * **On Arch/pacman-based:** Update your package lists, then: <code bash>
pacman -S virt-manager qemu
</code>
    * **On Yum-based:** Update your package lists, then: <code bash>
yum install virt-manager qemu
</code>
  - Make sure your user owns the ''libvirt'' socket. Change out the username:username with your actual username:<code bash>
sudo chown username:username /var/run/libvirt/libvirt-sock</code>
  - Create a VM with the Batocera image as a drive in Qemu.
    - Go to **File** -> **New virtual machine...**\\ {{:qemu-vm-french-1.png?520|}}
    - Ensure "Import an existing disk image" is selected.\\ {{:qemu-vm-french-2.png?360|}}
    - "Browse" for an existing image.\\ {{:qemu_bato_browse_for_image.png?360|}}
    - Click "Browse for local..." and select the Batocera image file.\\ {{:qemu-vm-french-4-b.png?440|}} {{:qemu-vm-french-5.png?620|}}
    - Select the OS: ''Microsoft Windows 10'' (FIXME no screenshot? What does this mean, as we've already selected our image?)
    - The dialogue box should now look like this, proceed:\\ {{:qemu_bato_i_dunno.png?360|}}
    - Grant access permission to the emulator to search into the selected path
    - Change the default **Memory** and **CPU** numbers if you choose. The defaults are good enough.\\ {{:qemu-vm-french-3.png?360|}}
    - Give your virtual machine a name and click **Finish**.\\ {{:qemu-vm-french-6.png?360|}}
  - (Optional) If you'd prefer to passthrough your GPU to the virtual machine for extra performance (warning: <wrap em>your host machine will lose access to the GPU you passthrough</wrap>) follow the instructions here: https://www.server-world.info/en/note?os=Debian_11&p=kvm&f=12
  - (Optional) For gamepad support:
    - Connect the gamepad into a USB port on the host computer.
    - On the virtual machine, go to **View** -> **Redirect USB Devices** and then select the connected gamepad.\\ {{:qemu-redirectusbdevice.png?direct&400|}}
  - (Optional) For external storage device support:
    - Connect the USB external disk into a USB port on the host computer.
    - On the virtual machine, go to **View** -> **Redirect USB Devices** and then select the connected USB disk device.\\ {{:qemu-externalstoragedevice.png?direct&400|}}
    - Now goes to Settings -> Storage Devices -> And select the USB Disk, system will reboot to apply the changes.

  - Enjoy!
===== Proxmox =====

<WRAP center round todo>
Untested. Reportedly, following this tutorial to set it up in addition to passing through all devices enables it to work: https://www.nicksherlock.com/2020/12/running-tails-as-a-vm-with-persistence-on-proxmox/
</WRAP>

===== Troubleshooting =====

==== I have a black screen but can still hear the audio playing ====

The virtual machine is not configured correctly. Preferably, you would figure out how it's not configured correctly and remedy that, but in case you'd rather just instantly work around it, you can [[:display_issues#when_emulationstation_feels_sluggish_on_a_4k_tv|force Batocera to use a particular resolution]].

==== I have no space in my virtual userdata partition! ====

Perhaps you didn't expand the image before using it as the base?

It's also possible to simply replace the userdata partition with another, larger one by changing the "drives" in the virtual machine's settings. This will differ from virtual machine to virtual machine, look up its instructions. Batocera uses the **ext4** [[:batocera.linux_architecture|filesystem]] for its userdata by default.

==== My controller isn't working! ====

First, make sure you have passed it through as a USB device to the VM itself (refer to the instructions above).

If it's still not working, check that the controller itself is working fine on your host machine outside of VirtualBox.

=== I've done that and it's still not working! I'm on a Linux-based host. ===

If it's still not being recognized, add the user to the correct group:
  - Close VirtualBox
  - Open a terminal and run ''%%sudo usermod -a -G vboxusers $USER && sg vboxusers virtualbox%%''

Windows shouldn't have this issue as long as the program is run in administrator mode.

==== I have no network connection even though my host has one ====

If you face an error about the "default" network device like this:\\ {{:qemu_network_error.png?360|}}

then you are not currently passing through your network connection to the virtual machine. Run the following on the host machine to enable that:

<code bash>
sudo virsh net-start default
</code>