jcs.org
Serenity Operating System
1# Serenity installation guide for VirtualBox
2
3## NOTICE
4There are currently issues with running Serenity in VirtualBox. Please refer to the [open issue](https://github.com/SerenityOS/serenity/issues/2927) for a list of currently known issues. Anything that doesn't currently work will be noted in this document.
5
6## Creating the disk image
7Before creating a disk image that will work in VirtualBox, you will need to create a GRUB image as described in the [Serenity installation guide](BareMetalInstallation.md). Please skip the final step of that section, as that is only relevant for putting the image onto a real drive. You **cannot** use the same disk image created for QEMU. Using that image will halt immediately with the message ``FATAL: No bootable medium found! System halted.``
8
9There are a couple of ways to convert the disk image:
10
11If you have QEMU installed:
12``
13qemu-img convert -O vdi /path/to/grub_disk_image /path/to/output/serenityos.vdi
14``
15
16If you only have VirtualBox installed:
17``
18VBoxManage convertfromraw --format VDI /path/to/grub_disk_image /path/to/output/serenityos.vdi
19``
20
21Set an identifier to the disk image, otherwise updating the disk image makes the identifiers no longer match up.
22``
23VBoxManage internalcommands sethduuid serenityos.vdi 19850209-0000-0000-0000-000000000000
24``
25
26Note that if you are on Windows and you do not have QEMU or VirtualBox in your PATH environment variable, you must be in the installation folder for the tool you're using. You will also need to put ``./`` in front of the command.
27
28## Creating the virtual machine
29**Please note that these instructions were written with VirtualBox v6.1.12 in mind. Therefore, these instructions may not match exactly for past and future versions.**
30
311. Open the **Create Virtual Machine** dialog. Switch to **Expert Mode**.
322. Feel free to give it any name and store it anywhere.
333. Switch the **Type** to **Other** and the **Version** to **Other/Unknown (64-bit)**.
344. Serenity requires at minimum 512 MiB of memory. Set **Memory size** equal to or above 512 MiB. The currently recommended size is 1 GiB.
355. For **Hard disk**, select **Use an existing virtual hard disk file**. Click the folder icon next to the dropdown to open the **Hard Disk Selector**.
366. Click **Add**. Browse to where you stored the converted disk image from the previous stage and add it. Click **Choose**.
377. Finally click **Create**.
38
39Reference image:
40
41
42
43## Configuring the virtual machine to boot Serenity
44Serenity will not be able to boot with the default configuration. There are a couple settings to adjust. Open **Settings** and:
451. Go to **System**, open the **Processor** tab and tick **Enable PAE/NX**.
462. Go to **Audio** and set **Audio Controller** to **SoundBlaster 16**.
47
48There are a couple of settings to check:
49- In **Storage**, click on the **Controller**. Make sure the controller type is PIIX4. PIIX3 and ICH6 are untested. Anything else is guaranteed not to work, as Serenity does not currently support them.
50- In **Network** and in the **Advanced** drop down, make sure the **Adapter Type** is anything but **Intel PRO/1000 MT Desktop (82540EM)**. While it is the only adapter type Serenity currently supports, it does not currently work in VirtualBox.
51
52Please note that at the time of writing, audio and networking do not work in VirtualBox.
53
54That is all you need to boot Serenity in VirtualBox! Read on for additional configuration you may want to use.
55
56## Blinking cursor after GRUB menu
57If you only see a blinking cursor after selecting an option in the GRUB menu, it is very likely you have encountered one of the errors listed in the [troubleshooting document.](Troubleshooting.md)
58
59- Check that you have enabled PAE/NX in the **Settings** > **System** > **Processor** tab.
60- If you are using a 64-bit disk image, check that **Version** is set to **Other/Unknown (64-bit)** instead of **Other/Unknown** in **Settings** > **General**.
61
62## Additional configuration (optional)
63For serial debugging, go to **Serial Ports** and enable port 1. Feel free to set the **Port Mode** to anything if you know what you're doing. The recommended mode is **Raw File**. Set **Path/Address** to where you want to store the file. This must also include the file name.
64
65While the default 16 MB of video memory is more than enough to use the default resolution, it is not enough to use all the supported resolutions. If you want to use 2560x1080, you will need to supply at minimum 22 MB of video memory.