MassOS on Virtual Machines

This article discusses, and aims to clarify, everything related to running MassOS on virtual machines (VMs), using examples of well-known virtualization software.

Virtualization Software Support

This table shows the current level of support MassOS has for particular VM software. It can be used as an indicator of how well MassOS runs as a guest operating system, as well as how easy it is to install and set up MassOS.

NOTE: The support levels described here apply to the latest available version/build of MassOS at the time of writing. This same level of support may not be present in older releases or builds, so you should always try to use the newest available version of MassOS.

Software	Support Level	Installation Difficulty	Post-Installation Setup	Remarks
VMware	✅ Fully Supported	⚠️ Medium	✅ Not Required	The installation process, described in detail in the Installing MassOS on VMware section below, is slightly more involved than we would like, as it requires using the advanced setup mode to workaround the issue of VMware incorrectly detecting the OS type from the MassOS ISO image. However, all the necessary software to allow advanced interactions with the guest system, including open-vm-tools and xf86-video-vmware, is pre-installed on MassOS, which means no further setup is required after MassOS is installed. 3D acceleration fully works.
VirtualBox	✅ Fully Supported	✅ Easy	⚠️ Required	The installation process itself is fairly straightforward. However, the VirtualBox Guest Additions (GAs) are not pre-installed on MassOS, and therefore must be installed manually to enable advanced functionality and interaction between the host and the guest system. The process for installing the GAs is described, along with the main installation guide, in the Installing MassOS on VirtualBox section below. 3D acceleration fully works.
Parallels	✅ Supported (Intel only)	✅ Easy	⚠️ Required	Please note that MassOS cannot be installed under Parallels on Apple Silicon Macs. Only Intel Macs are supported. The installation process is straightforward. The Parallels Tools, similar to the VirtualBox Guest Additions, are not pre-installed out of the box on MassOS, and therefore must be installed manually to enable advanced host-guest interactivity. A step-by-step guide for installing MassOS on Parallels, as well as setting up Parallels Tools, can be found in the Installing MassOS on Parallels section below. 3D acceleration fully works.
QEMU	⚠️ Partially Supported	⚠️ Medium	⚠️ Possibly Required	A basic installation guide is provided, but it is not complete, and, at the time of writing, it may not describe the most optimal setup process or how to get all advanced host-guest interaction features working. Some software aiming to support host-guest interaction features is pre-installed on MassOS, such as qemu-guest-agent and spice-vdagent, but it has received little (if any) official testing from the MassOS developers. 3D acceleration works with Virtio, as described in the guide, however it may not be fully stable and seamless to use. Contributions are welcome to help improve support, either within the MassOS system itself, or by improving the documentation on QEMU in this article.

Installing MassOS on VMware

These instructions assume you already have VMware installed and set up on your system. If you don't, it can be downloaded from your Broadcom account portal for all platforms. For Linux hosts, including MassOS, you can simply download this package, extract the tarball, and then run the bundle file as an executable.

These instructions also assume you are using VMware Workstation (which is now free to use without a paid license as of Broadcom's acquisition of VMware); the procedure may differ slightly for VMware Player.

From the VMware dashboard, select File from the top bar, and then select New Virtual Machine. Use the Custom (advanced) option for creating the virtual machine, since the default option may incorrectly detect the OS from the ISO, and therefore misconfigure the VM's settings.

When asked about hardware compatibility, leave this option as the default.

Do NOT select the ISO image here. If you do so, VMware will incorrectly detect the OS as Fedora, and may misconfigure the VM's settings. Instead, select I will install the operating system later, and we will specify the MassOS ISO image later.

Set the OS to Linux, and the version to Other Linux 6.x kernel 64-bit.

Name the virtual machine something memorable of your choice.

On the next few pages, you will be asked to set the amount of resources the VM has. For the processor configuration, ensure you set the Number of processors to 1. As for the Number of cores per processor, we recommend allocating at least 2, however the maximum amount you can allocate will depend on the number of threads your CPU has. For the memory selection, although MassOS is lightweight, we'd recommend allocating 4GB if possible, or 2GB at a bare minimum, depending on how much RAM your system has.

For the next two pages, leave the settings as their defaults.

When asked to select the disk type, ensure you change the selection to SATA. Despite SCSI being VMware's recommendation, it is not recommended for MassOS. Instead, SATA is known to have better compatibility.

You will then be given a few screens prompting you to create a virtual hard disk for the machine. We'd recommend allocating no less than 16GB, but again, the maximum you can allocate will depend on how much free disk space you have on your host machine. You can safely ignore all other options on these pages.

Finally, before confirming creation of the VM, there are a couple of options that need to be changed. Choose Customize Hardware here.

The first option you want to change is in the New CD/DVD (SATA) tab. Ensure you change the selection to Use ISO image, and you can now select the MassOS ISO image which we deferred doing earlier. The second option to change is in the Display tab. While not strictly mandatory, it is strongly recommended to check the Accelerate 3D graphics option, and change the Graphics Memory size to either 512MB or 1GB, depending on how much RAM you allocated to the VM previously. If you allocated more RAM, then you can increase this, but VMware's default of 8GB is too much in almost all cases. If you don't have a supported GPU for this feature, then you may instead ignore the option.

Now close this settings page and finish the VM creation. Before starting up the VM, there is one more setting to change. Ensure the newly created VM is selected, and then choose Edit virtual machine settings.

Switch to the Options tab at the top, then go all the way down to Advanced at the bottom, and change the Firmware type to UEFI. This will ensure the best compatibility with MassOS.

Save and exit the settings page, and then start up the VM. Select the default/top option to boot into the MassOS Live CD.

Now proceed with the installation of MassOS as you normally would, as described in Installing MassOS. Once you've finished the installation and restarted the VM into the new installation, you will be good to go. No further setup will be needed, as MassOS has all the necessary software to support host-guest interaction features pre-installed. This means that adaptive resolution, shared clipboard, shared folders, and more, should be ready to go right out of the box. You can enter full screen mode in the VM by pressing the Enter full screen mode button at the top of the screen. The resolution of the VM should automatically adjust to fill your screen, for a fully immersive experience.

Installing MassOS on VirtualBox

These instructions assume you already have VirtualBox installed and set up on your system. If you don't, please download the appropriate version for your OS from the VirtualBox downloads page. VirtualBox can be installed on a MassOS host system by choosing "Linux Distributions" followed by "All Distributions". This will download a universal .run installer, which can be executed from a terminal to install VirtualBox.

From the VirtualBox main menu, select New to create a new VM. Name it something memorable of your choice, and select the MassOS ISO image you downloaded. Note that VirtualBox will be unable to detect MassOS as a known distro, so you will therefore be required to manually select the OS type. Ensure you choose Linux, then Linux 2.6, then Linux 2.6 / 3.x / 4.x / 5.x (64-bit).

On the next page, you can customise the amount of resources the VM has. While MassOS is lightweight, we recommend allocating 4GB if possible, or 2GB at a bare minimum. We also recommend allocating at least 2 processors - the maximum amount you can allocate will depend on how many threads your CPU has. Most importantly, you should check the box which says Enable EFI (special OSes only), since it will generally provide better compatibility with MassOS, and use a higher internal resolution by default.

Following this, you will be prompted to create a virtual hard disk for the machine. We'd recommend allocating no less than 16GB, but again, the maximum you can allocate will depend on how much free disk space you have on your host machine. You can safely ignore all other options on this page.

Before starting up the virtual machine for the first time, there is one more setting we need to change, which wasn't given as an option during the VM creation process. Press the Settings button near the top of the VirtualBox window, and switch from Basic to Expert mode from the top of the page. Now select the Display category from the sidebar. Now you should check the box labelled Enable 3D acceleration, and then increase the Video Memory size to the maximum supported amount (normally 256MB, but may be 128MB on some systems). Then press the OK button at the bottom of the screen to return to the VirtualBox dashboard.

Start up the virtual machine and select the top/default boot option to boot the MassOS Live CD.

Now proceed with the installation of MassOS as you normally would, as described in Installing MassOS. Once you've finished the installation and restarted the VM into the new installation, some additional manual setup is needed to install the VirtualBox Guest Additions (GAs), which provide support for all host-guest interaction features, including shared folders, shared clipboard, adaptive resolution, and more.

First, you need to eject the MassOS Live CD from the VM's virtual disc drive, if it is still inserted from when you installed the OS in the VM. Do this by accessing Devices from the top bar, followed by Optical Drives, and then select Remove Disk From Virtual Drive. If it gives you any warning about being unable to eject the disc, you can safely select Force Unmount.

Now insert the Guest Additions ISO, by accessing Devices again from the top bar, and then selecting Insert Guest Additions CD image.

The Guest Additions virtual disc should now appear on your desktop. Double click it to mount the disc and open it in the file manager.

Right-click inside the folder, and then select Open Terminal Here.

Run the following command in the terminal:

sudo ./VBoxLinuxAdditions.run

Enter the password for your user account if prompted.

Once the installation of the Guest Additions is complete, the command execution will finish and the message will inform you of this.

You must now reboot the virtual machine (you can do this simply by typing systemctl reboot in the terminal, or alternatively use the graphical user interface to restart the system as normal). After doing so, all host-guest interaction features should be functional. You can make the VM full screen by pressing RightControl+F, and the resolution of the VM should automatically adjust to fill your screen, for a fully immersive experience.

Installing MassOS on Parallels

NOTE: MassOS can only be installed under Parallels on Intel Macs. It is not possible to install MassOS under Parallels on Apple Silicon Macs.

These instructions assume you already have Parallels installed. They also assume you have Parallels activated or are within the 14-day trial period, due to Parallels being paid software. The process of activating Parallels is outside the scope of this guide.

First, open the Create New menu, and then select Install Windows, Linux, or macOS from an image file.

Select Image File and then browse to your downloaded MassOS ISO image. After selecting it, you will see this message informing you that the operating system was unable to be detected. This is expected behaviour and is not an error. Continue.

When asked to select the operating system, you need to navigate to More Linux and then select Other Linux.

Specify the name you wish to use for the machine, and the location to save it in. In this example, it has just been called MassOS. In any case, you will want to change it from the default placeholder of Other Linux.

You need to select Options and then head to the Hardware tab. You then need to select CPU & Memory, and adjust the selections as appropriate for your system's capability. We recommend specifying no less than 2GB of RAM for the system, and no less than 2 CPU threads (processors).

Now, while still in the Hardware tab, move down to Graphics. You will likely want to increase the memory that is allocated to the virtual GPU, and we recommend specifying no less than 256MB. You may specify wish to specify more than this if you plan to run graphically-intensive programs on the virtual machine. Note that the allocated video memory will come out of the total allocated system memory - so if you wish to allocate a large amount, we recommend also increasing the overall system RAM specified in the previous menu.

While still in the Graphics menu, select Advanced and then ensure the Enable 3D acceleration option is checked. This is strongly recommended for best performance in the virtual machine.

Lastly, head all the way down to Boot Order, and then select Advanced.

Change the BIOS mode trro EFI 64-bit. The default setting of Legacy BIOS is supported by MassOS, but using EFI will give you a more seamless experience, so is strongly recommended to use instead.

Now you've configured the virtual machine's options, you can start up the virtual machine. This will load into the MassOS live environment, whereby you can proceed to install MassOS normally as described in Installing MassOS.

After you've finished the installation and restarted the virtual machine into the full installation, you can proceed to install Parallels Tools, which is required to enable advanced host-guest interactivity features such as shared clipboard and shared folders.

First, you should eject the MassOS ISO image from the virtual CD drive if it was still inserted from the installation process you completed previously. Then, you can head to the bar at the top of the screen, choose Actions, and then select Install Parallels Tools.

This will insert the Parallels Tools CD image into the virtual drive, and it will display on your desktop and in the file manager. You can double-click the desktop icon, or find it in the sidebar in the file manager, to access the contents of this virtual disc.

Double-click on the install-gui program. This will start the installation of Parallels Tools. You may be prompted to enter the password for your user account inside the virtual machine.

After the installation is complete, reboot the virtual machine. You should then be ready to go. You can make the window full screen or otherwise adjust its size, and the guest resolution should auto-adjust accordingly. Shared clipboard and shared folders should also be working.

Installing MassOS on QEMU

NOTE: This guide is incomplete. In particular, it may not yet fully describe the most optimal method(s) of installing and setting up MassOS as a guest system under QEMU. It may also not yet provide details about how to get all advanced host-guest interaction features working, despite some or all of the necessary software being preinstalled on MassOS. Contributions to improve this guide are welcome.

These instructions assume you already have QEMU installed. If you are on a MassOS host system, or the version of QEMU provided by your distribution is unacceptably outdated (or, simply, you don't have administrator privileges on the system to install it), you can use DanielMYT's unofficial QEMU AppImage, which aims to provide a complete and up-to-date version of QEMU that is fully portable and should run on almost any reasonably modern GNU/Linux distribution.

First, you need to create a virtual HDD image for the QEMU virtual machine. This can be done using the qemu-img utility:

qemu-img create -f qcow2 MassOS.qcow2 40G

You are free to replace MassOS with whichever name you want, and 40G with whichever size you want the image to be. Note, however, that QCOW2 images do not allocate their full size by default - rather, their size on disk dynamically grows as data is written to the virtual HDD image. This means you can, for example, allocate 100G or more, and that space will only be taken up on disk once you actually write 100GiB of data to the virtual HDD from the VM.

NOTE: If you are using the QEMU AppImage, as described above, the qemu-img utility is included as an executable in the AppImage. To run it, you must set the APPIMAGE_EXE environment variable, like follows:

APPIMAGE_EXE=qemu-img ./qemu-X.Y.Z-x86_64.AppImage create -f qcow2 MassOS.qcow2 40G

You also need to obviously replace X.Y.Z with the actual AppImage version.

Basic Installation on QEMU

This section describes how to set up a basic installation on QEMU. For UEFI boot and 3D acceleration support, please see the relevant sections below.

You can launch the QEMU program to start the VM (again, you must replace /path/to/massos.iso with the exact full path to the MassOS ISO image, and its correct filename):

# Normal installation
qemu-system-x86_64 -enable-kvm -M q35 -m 4G -smp 2 -vga qxl -hda MassOS.qcow2 -cdrom /path/to/massos.iso
# AppImage (qemu-system-x86_64 is the default executable in the AppImage)
./qemu-X.Y.Z-x86_64.AppImage -enable-kvm -M q35 -m 4G -smp 2 -vga qxl -hda MassOS.qcow2 -cdrom /path/to/massos.iso

In the above commands -m 4G is used to set the VM's RAM size to 4GiB. You can set this higher if your machine has enough available RAM. Similarly, -smp 2 is used to set the number of CPU threads that the VM can use. You can set more if your system's CPU has more available threads, but we generally wouldn't recommend setting the value less than 2.

One the MassOS Live CD environment is booted, you should proceed with the installation of MassOS as you normally would, as described in Installing MassOS. Once the system is installed, you may optionally remove the -cdrom /path/to/massos.iso parameter from the launch command above for subsequent boots. The preinstalled software, including qemu-guest-agent and spice-vdagent, should be running automatically to enable host-guest interaction features.

UEFI-Based Installation on QEMU

This section describes how to use OVMF with QEMU, to allow the QEMU system to boot in UEFI instead of Legacy BIOS mode. This can provide a more stable and seamless experience, particularly when it comes to getting 3D acceleration working (see below).

First, you need to obtain a build of OVMF - both the firmware itself, and the UEFI variables cache. The easiest way to obtain OVMF is to download nightly builds from here. You want to download both the files named ovmf-code-x86_64.fd and ovmf-vars-x86_64.fd, as shown in the image below.

These files should be placed in an easily accessible location - but the easiest place to put them is in the same folder as your VM folder, i.e., the one containing your QCOW2 HDD image.

Now re-run the QEMU launch command, with modified arguments to make it boot in UEFI mode using our newly provided OVMF binaries:

# Normal installation (UEFI).
qemu-system-x86_64 -enable-kvm -M q35 -drive if=pflash,format=raw,readonly=on,file=ovmf-code-x86_64.fd -drive if=pflash,format=raw,file=ovmf-vars-x86_64.fd -m 4G -smp 2 -vga qxl -hda MassOS.qcow2 -cdrom /path/to/massos.iso
# AppImage (UEFI).
./qemu-X.Y.Z-x86_64.AppImage -enable-kvm -M q35 -drive if=pflash,format=raw,readonly=on,file=ovmf-code-x86_64.fd -drive if=pflash,format=raw,file=ovmf-vars-x86_64.fd -m 4G -smp 2 -vga qxl -hda MassOS.qcow2 -cdrom /path/to/massos.iso

Please see the details in the previous section regarding the other command-line arguments, and proceeding with the installation.

3D Graphics Acceleration on QEMU

The -vga qxl option in the above commands is used to ensure QEMU uses QXL for its emulated graphics adapter. From the testing done by the MassOS developers, this has been found to provide the best compatibility and most stability. However, it only supports 2D acceleration. Full 3D acceleration support requires the use of Virtio, which can be set by removing the -vga qxl option, and instead passing -device virtio-vga-gl -display sdl,gl=on, as shown below (you may also need to increase the resolution from the display settings inside the MassOS guest system):

# Normal installation for 3D acceleration.
qemu-system-x86_64 -enable-kvm -M q35 -m 4G -smp 2 -device virtio-vga-gl -display sdl,gl=on -hda MassOS.qcow2 -cdrom /path/to/massos.iso
# AppImage for 3D acceleration.
./qemu-X.Y.Z-x86_64.AppImage -enable-kvm -M q35 -m 4G -smp 2 -device virtio-vga-gl -display sdl,gl=on -hda MassOS.qcow2 -cdrom /path/to/massos.iso
# Normal installation for 3D acceleration (UEFI boot - see section above).
qemu-system-x86_64 -enable-kvm -M q35 -drive if=pflash,format=raw,readonly=on,file=ovmf-code-x86_64.fd -drive if=pflash,format=raw,file=ovmf-vars-x86_64.fd -m 4G -smp 2 -device virtio-vga-gl -display sdl,gl=on -hda MassOS.qcow2 -cdrom /path/to/massos.iso
# AppImage for 3D acceleration (UEFI boot - see section above).
./qemu-X.Y.Z-x86_64.AppImage -enable-kvm -M q35 -drive if=pflash,format=raw,readonly=on,file=ovmf-code-x86_64.fd -drive if=pflash,format=raw,file=ovmf-vars-x86_64.fd -m 4G -smp 2 -device virtio-vga-gl -display sdl,gl=on -hda MassOS.qcow2 -cdrom /path/to/massos.iso

In the above commands, -display sdl,gl=on makes QEMU use SDL for its GUI window instead of GTK. This has been chosen because it appears to provide a better experience when using Virtio; in particular, the window size will automatically adjust as you change the resolution from inside the guest OS on SDL, whereas it does not on GTK. If you really want to use GTK with the Virtio backend, replace -display sdl,gl=on in the above command with -display gtk,gl=on.

You can test that 3D acceleration is properly working by running the following command from a terminal inside the guest:

glxinfo | grep "OpenGL renderer"

And it should display OpenGL renderer string: virgl, as shown in this image:

If it instead shows OpenGL renderer string: llvmpipe, then it has instead fallen back to software rendering and will not properly be able to accelerate 3D graphics.

If you are having trouble getting 3D acceleration to work, please firstly ensure the necessary Mesa GPU drivers for your own GPU are installed on your host system (note that MassOS already includes all GPU drivers out of the box, so this advice applies to other distributions which may not ship every GPU driver by default). You can check this by running glxinfo | grep "OpenGL renderer" on the host system. The output should display something that represents your GPU, such as the following:

Again, if it displays OpenGL renderer string: llvmpipe, then 3D acceleration is not working on the host (therefore it won't physically be possible for it to work on the guest). The most common way to correct this problem is by installing the necessary Mesa GPU drivers if they are missing. Consult your distro's documentation or support channels if you are unsure about this.

You also need to ensure that the virglrenderer package is installed on your host system (specifically, the libvirglrenderer.so library), to allow the QEMU installation on your system to be able to use it. Note that this does not apply to the QEMU AppImage, since the AppImage bundles libvirglrenderer.so, and the QEMU binary inside the AppImage automatically links to the bundled library. Therefore, you should only need to install the virglrenderer package on your host system if you are using a normal (i.e., distro-provided) version of QEMU.