Difference between revisions of "VirtualBox"

From ReactOS Wiki
Jump to: navigation, search
(Redirect to named pipe (Win32 host))
(Installing Guest Additions)
 
(130 intermediate revisions by 31 users not shown)
Line 1: Line 1:
[http://www.virtualbox.org/ VirtualBox] is a virtual machine for x86 architecture developed by innotek and maintained by Sun Microsystems. There are two versions: the full VirtualBox package with a proprietary license and the VirtualBox Open Source Edition (GPL).
+
[http://www.virtualbox.org/ VirtualBox] is a virtual machine for x86 architecture developed by Innotek and maintained by Oracle. There are two versions: the full VirtualBox package with a proprietary license and the VirtualBox Open Source Edition (GPL).
  
It's easier to configure than [[QEMU]] and slightly slower than [[VMware]].
+
It's easier to configure than [[QEMU]] and slightly slower than [[VMware]]. __TOC__
  
The best results tend to be obtained by configuring the ReactOS VM using the 'Windows/Windows NT4' template or 'Other/Other'.
+
'''Note''': VirtualBox '''5.2.44''' version is highly and strongly recommended. VirtualBox 6.x branch is still very buggy and unstable, causes fake regressions to be found in ReactOS.
  
== Getting debug output ==
+
'''Note''': If you have any trouble 'capturing' your mouse/cursor within the Ros-VM-window with VirtualBox, first go to the "machine" tab and then select "Disable mouse integration", then click again on the VM-session you're running to 'capture', and this time it should work.
  
=== Redirect to virtual serial port (com0com, Win32 host) ===
+
'''Note''': If you get the error <code>Raw-mode is unavailable courtesy of Hyper-V. (VERR_SUPDRV_NO_RAW_MODE_HYPER_V_ROOT).</code> when attempting to start a Virtual Machine ensure ''both'' Hyper-V and Windows Sandbox are unchecked in the "Turn Windows features on or off" section of the Add/Remove Programs control panel applet.  (Quickly access it by pressing <code>Win</code>+<code>R</code> and typing <code>appwiz.cpl</code>)
  
This is the recommended method on Windows host, due to problems with pipes.  
+
== Running the ReactOS Live CD ==
 +
'''Note''': You '''can't''' install ReactOS from the Live CD. You need to use the full installation image, which is called  ReactOS BootCD.
  
1. Download and install [http://sourceforge.net/project/showfiles.php?group_id=129551 com0com] virtual comport redirector. See [[com0com]] tutorial for more info.
+
The following instructions will guide you through the process of creating a ReactOS compatible virtual machine in VirtualBox, and mounting the Live CD. The process is demonstrated using VirtualBox 4.2.14 r86644 on Windows 7 x64, but it should be similar on other operating systems, and versions.
  
2. Setup a serial port in VBox. Choose Port Mode = "Host Device", Port Path: "\\.\CNCA0" if you use the default or maybe something like "\\.\COM5" if you have renamed your ports.
+
* [http://www.reactos.org/download Download] the latest LiveCD release
 +
* Start VirtualBox.
 +
* Click the 'New' button.
 +
* Enter a name and set the type to Microsoft Windows. The version should be set to Windows 2003 (32bit). Click next.
 +
* Choose the amount of RAM you wish to allocate to the Virtual Machine. At least 256&nbsp;MB is recommended.
 +
* '''Add a Virtual Hard Drive, even if you wish to run from CD.''' A hard drive is required for booting the system. You can either make a new one, or choose an existing one (if formatted it must be FAT16/FAT32). Click Create to create your new VM.
 +
* Select your new VM and click Settings.
 +
* Make sure that you '''assigned only 1 core of CPU''' to ReactOS VM
 +
* Go to 'Storage' and select the empty disk IDE controller.
 +
* Under Attributes, select your Live CD image and tick the 'Live CD/DVD' checkbox.
 +
* Go to 'System', and make sure that 'Enable I/O APIC' is unchecked.
 +
* Go to 'Network', click advanced, change the adapter type to ''''PCnet-FAST III''''. '''Note''': This step should be optional now, as Intel PRO/1000 network card is supported out-of-the box since ReactOS 0.4.12.
 +
* Press OK. You are now ready to boot ReactOS.
  
3. Start your favourite serial terminal (I have tested hyperterminal and putty), set it to the other serial port, set speed to 115200 and connect at any time.
+
If you are unable to choose the correct screen resolution in ReactOS, then refer to the instructions [http://superuser.com/questions/495670/how-can-i-get-windows-8-and-virtualbox-to-use-my-full-screen here]. They explain the steps for Windows 8, but it should work for ReactOS as well.
  
4. Start ReactOS in VBox and watch the log.
+
== Installing the ReactOS Boot CD ==
 +
'''Note''': First of all, make sure you have read '''[[Installing ReactOS]]''' article.
  
=== Redirect to named pipe (Win32 host) ===
+
If you type "Reac" as your VM name, VirtualBox will detect that you are creating a ReactOS virtual machine and assign to it a Windows 2003 profile, which is most suitable. Make sure you are using Virtualbox 5.2.18 version or newer to benefit from this feature.
Virtualbox and any other application that needs to access Named Pipes in Vista, must be elevated to Administrator. Sadly the VBox serial to pipe implementation seems to be a little buggy resulting in missing characters in the debuglog. Choose the virtual com ports solution to avoid that problem.
 
  
 +
You can customize the amount of RAM you wish to allocate to the Virtual Machine. At least 64 MB are recommended.
  
1. Using putty only:
+
'''Note''': Intel PRO/1000 network card is supported out-of-the box since ReactOS 0.4.12. For older ReactOS versions, always select ''''PCnet-FAST III''''.
  
On Virtualbox serial menu set up the following: Port mode to '''Host Pipe''', tick the '''create pipe''', finally type the named pipe path, for example:
+
After you are done with the installation of ReactOS itself you may want to have Guest Additions too.
\\.\pipe\ros_pipe
 
  
Run Putty. On Vista it must be elevated to Admin, as anything that is to use named pipes. Select the serial as connection type, set speed to 115200 baud and put the named pipe path as serial line. Instead of ros_pipe, you can use any unique name, only mind to follow the \\.\pipe\[pipe name] scheme.
+
=== Installing Guest Additions ===
  
Start virtual machine first, then open the putty session. When you close down the VM window, putty will change to inactive state and display error message, but when you restart the vm, you can easily reconnect that session by pressing right mouse button on window top bar and selecting '''Restart session'''.
+
Mount the ''CD-image with guest additions'' in the CD-Drive and open the file VBoxWindowsAdditions.exe and follow the setup instructions.
  
 +
To use the shared folders, follow the instructions on [[Using shared folders]].
 +
 +
'''Attention:''' You can only install the VirtualBox guest additions if your virtual machine is configured with max. 32-64MB graphics memory. Otherwise, an attempt to restart after installing the guest additions will result in a BSOD on VBoxDisp.dll. You can adjust the graphics memory in the "Display" section of your VM when it is shut down.
 +
 +
'''Attention:''' If you want to install and try  Vbox experimental '''3d acceleration''' you should install Vbox additions only in safe mode (press F8 key on boot). Vbox versions 4.X or 5.X are recommended, because 6.1.x has removed 3D acceleration support for Windows OS's earlier than Windows 7 (ReactOS pretends to be XP or 2003).
 +
 +
=== Setting up audio ===
 +
 +
ReactOS has had limited support for sound since the 0.3.9 release, but it is recommended to test sound with a [http://www.reactos.org/getbuilds trunk build].
 +
 +
In VirtualBox Machine Settings, enable audio and set the following:
 +
* Host Audio Driver: Windows DirectSound
 +
* Audio Controller: ICH AC97
 +
 +
After installing ReactOS:
 +
# Download the Intel AC 97 driver from ReactOS Application Manager
 +
# Extract the files to <tt>C:\ReactOS\</tt>
 +
# Restart the virtual machine
 +
# Goto Device Manager
 +
# If the Audio Device is not identified properly, find the unknown Audio device
 +
# Right-Click and choose to Update the Device Driver
 +
# Browse to the C:\ReactOS\inf folder as the install location
 +
# Update the Audio Device
 +
# Reboot ReactOS
 +
# Install and start your favorite audio playback or multimedia application (e.g. Winamp, VLC, MPlayer)
 +
# Open an audio file and play
 +
 +
Sometimes this method does not work. In case:
 +
# Download the Intel AC 97 driver from ReactOS Application Manager
 +
# Extract the files to <tt>C:\Downloads\</tt>
 +
#Copy the folders <tt>inf</tt> and <tt>system32</tt> to <tt>C:\ReactOS\</tt>
 +
# Restart the virtual machine
 +
# If it worked, you will be able to hear startup sound (remember to turn up speakers).
 +
=== Known Issues ===
 +
 +
* The AC97 Driver only supports PCM Wave Audio in the range 8000-44.100Khz, 16Bit Samples and 2 Channels
 +
* Sample rate conversion is not yet supported
 +
* The driver has issues when changing the sample rate of the audio stream
 +
 +
== Getting debug output ==
 +
=== Windows ===
 +
 +
[[File:rosdebug1.png|right|300px]]
 +
 +
Steps to be taken:
 +
 +
* '''Set up a serial port in VirtualBox.'''
 +
: There are other VM's possible, but they all work more or less the same, and they can all send a debug output to a COM port.
 +
:* Download [http://www.virtualbox.org/wiki/Downloads VirtualBox], if you haven't done so yet.
 +
:* Obviously, to debug/log ReactOS, you also need a [http://www.reactos.org/getbuilds/ ReactOS Debug build]. ( You MUST use a Debug build. You will also need [http://www.7-zip.org/download.html 7-Zip] to get the ReactOS ISO out of the .7z file.
 +
:* When the VirtualBox-window opens, click on the tab <code>Settings</code>. Click on <code>Serial Ports</code>.
 +
:: Choose <tt>Port Mode</tt>: <code>Host Pipe</code>, tick the <tt>Create Pipe</tt> option, <tt>Port Path</tt>: <code>\\.\pipe\ros_pipe</code>. (You may see <tt>Connect to existing pipe/socket</tt> instead of <tt>Create Pipe</tt>. In this case, untick it.)
 +
 +
:'''IMPORTANT''': Don't change the "COM1" port that appears in the Dropdown listbox. Keep it as COM1.
 +
 +
[[File:rosdebug2.png|right|300px]]
 +
* '''Download and start [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY]''' or your own favourite serial terminal (e.g. HyperTerminal,... )
 +
: This is the program that creates the debug logs. PuTTY can listen to a COM port and write it to file. If you don't know what you're looking for, get the
 +
: "For Windows on Intel x86" putty.exe file. It doesn't need to be installed; you just have to know where you downloaded it to. On Windows Vista and later
 +
: it must be run as Admin, as anything that is to use named pipes.
 +
 +
* Make sure <tt>Session</tt> is selected on the TreeView on the left. In the main part of the window, under <tt>Connection Type</tt>, choose the radiobutton <tt>Serial</tt>. Under <tt>Serial Line</tt> type <code>\\.\pipe\ros_pipe</code>. Under speed, type "115200". Depending on your wish how to log, one can go to the TreeView on the left and click on <tt>Logging</tt> under <tt>Session</tt>. Under <tt>Session Logging</tt>, choose <tt>All session output</tt>.
 +
 +
* Log file name indicates where the debug log will be and what it will be called. Use the Browse button to change the location if you like, but make sure you know where it's being saved!
 +
 +
*Go back to the TreeView on the left and click on Serial (under Connection). Set <tt>Flow Control</tt> to <code>None</code>. PuTTY is now configured. Note that on the main page of PuTTY you can Save/Load configurations which makes it even easier.
 +
 +
* Thus, after you elect the serial as connection type, set speed to 115200 baud and put the named pipe path as serial line (<code>\\.\pipe\ros_pipe</code>), you are ready to go. Of course, instead of <code>ros_pipe</code>, you can use any unique name, only mind to follow the <code>\\.\pipe\''[pipe_name]''</code> scheme.
 +
 +
* Click on "Open" at the bottom of the PuTTY-window. This activates PuTTY's debug-log-creating abilities, which is a black window with a flashing green
 +
:cursor. If you can see your PuTTY window in the background, you'll see lots of text flying past as PuTTY does its thing. When you've finished with
 +
: exploring ReactOS, you'll have your debug log there. When you shut down the virtual machine, PuTTY will change to inactive state and display error
 +
: message, but when you restart the virtual machine, you can easily reconnect that session by pressing right mouse button on window top bar and selecting
 +
: ''Restart session''.
 +
 +
* '''First start ReactOS in DEBUG MODE''' in VirtualBox, then open PuTTY and watch the log.
 +
<gallery widths=300px>
 +
File:rosdebug3.png|Select Debug Mode
 +
File:rosdebug4.png|ReactOS running + PuTTY output
 +
</gallery>
 +
 +
It has been suggested that there might be some slight data loss with pipes under very heavy output. If one notices this as being the case, and one intends to be a heavy tester/logger, there is still another way of getting a debug-log to work:
 +
 +
'''Com0com''' : This is the VirtualBox/PuTTY bridge. It gives you the option to have multiple COM port pairs, but you really only need 1 COM port pair. (Virtual Port Pair 0, for instance). Download and install [http://sourceforge.net/projects/com0com/files/com0com/ com0com] virtual comport redirector. See the [[com0com]] tutorial for more info. At the setup window, you'll see the names of the virtual serial ports (default: "CNCA0" and "CNCB0"). Be sure to check that the driver for com0com is installed correctly (with Device Manager, for instance). Then start your VM. In VirtualBox, go to "Settings", "Serial Ports" and set "Port Mode" to "Host Device" in the drop-down box (NOT "Host pipe"). Then, set Port/File Path to "\\.\CNCA0". Next, start Putty; check "Serial" and at the Serial line now type "CNCB0", and click on "open". As said earlier, a black box should appear, and when you run ReactOS in debug mode, the box will fill with text, aka, your log.
 +
 +
'''IMPORTANT''': Make sure to use the digitally signed version of the com0com driver on 64-bit versions of Windows Vista and later.
 +
<gallery widths=300px>
 +
File:rosdebug1b.png
 +
File:rosdebug1d.png
 +
</gallery>
 +
 +
==== Using VMwareGateway ====
 +
 +
You need to download the [http://l4ka.org/tools/vmwaregateway.php VMwareGateway] application. Start it with <tt>/r</tt> option to make it run as a service (in Windows Vista you have to use an elevated CMD for this). You can download a x86/x64 build [http://files.reactsoft.com/reactos/vmwaredebug/ here] that does not require VirtualBox to run elevated on Vista/Win7.  Next you need to start the service, using SC command:
  
2. Using Vmwaregateway:
 
You need to download the [http://l4ka.org/tools/vmwaregateway.php VmwareGateway] application ([http://opendn.org/reactos/x64/vmwaregateway.exe VmwareGateway x64 Edition]). Start it with /r option to make it run as a service (in Vista you have to use an elevated cmd for this). Next you need to start the service, using SC command:
 
 
  sc start vmwaregateway
 
  sc start vmwaregateway
  
Sort out any firewall popup if applicable. Finally, use your favourite telnet client to connect to '''localhost''' on port '''567'''.
+
Sort out any firewall pop-up if applicable. Finally, use your favorite telnet client to connect to ''localhost'' on port 567.
 +
 
 +
To configure your virtual machine, set it to ''Host Pipe'' with the following pipe address:
  
To configure your VM, set it to '''Host Pipe''' with the following pipe adress:
 
 
  \\.\pipe\vmwaredebug
 
  \\.\pipe\vmwaredebug
  
Make sure you do not mark the '''create pipe''' box. vmwaregateway has already created it.
+
Make sure you do not mark the ''Create Pipe'' box. VMwareGateway has already created it.
Debug output should appear in your telnet client ([http://opendn.org/reactos/x86/puttytel.exe PuttyTel (x86)], [http://opendn.org/reactos/x64/puttytel.exe PuttyTel (x64)]).
+
Debug output should appear in your telnet client [http://the.earth.li/~sgtatham/putty/latest/x86/puttytel.exe PuttyTel].
 +
 
 +
=== Linux ===
 +
 
 +
:* Install VirtualBox package, how to do so will depends on your distribution
 +
On Debian or Ubuntu:
 +
<code>sudo apt-get install virtualbox</code>
 +
:* Obviously, to debug/log ReactOS, you also need a [http://www.reactos.org/getbuilds/ ReactOS Debug build]. ( You MUST use a Debug build. You will also need [http://www.7-zip.org/download.html 7-Zip] to get the ReactOS ISO out of the .7z file.
 +
* '''Set up a serial port in VirtualBox.'''
 +
Setup a serial port in VirtualBox as shown in the picture to the right and below.
 +
:* When the VirtualBox-window opens, click on the tab <code>Settings</code>. Click on <code>Serial Ports</code>.
 +
:: Choose <tt>Port Mode</tt>: <code>Host Pipe</code>, tick the <tt>Create Pipe</tt> option, <tt>Port Path</tt>: <code>/tmp/ReactOS-Debug.pipe</code>. (You may see <tt>Connect to existing pipe/socket</tt> instead of <tt>Create Pipe</tt>. In this case, untick it.)
 +
 
 +
:'''IMPORTANT''': Don't change the "COM1" port that appears in the Dropdown listbox. Keep it as COM1.
 +
 
 +
[[File:VirtualBox-4.0.8.Setup serial port for socat pipe.png|right|300px]]
 +
 
 +
==== Using minicom ====
 +
 
 +
This guide is based on the terminal application minicom. First install it by typing:
 +
sudo apt-get install minicom
 +
 
 +
===== Configuring the serial port in minicom =====
 +
 
 +
* "sudo minicom -s" will allow you to set your port and save the configuration file (dfl = default)
 +
 
 +
* Choose "Configure serial ports". Name the device <tt>unix#pipe_path</tt> where "pipe_path" is a file like <tt>/tmp/ReactOS-Debug.pipe</tt> which will be used as pipe between the virtual machine and minicom.
 +
Make sure that pipe_path is exactly the same on both minicom and VirtualBox.
 +
 
 +
* Save config (dfl) will save your configure
 +
 
 +
* Exit
 +
 
 +
* now after starting the VM, execute "minicom" without sudo, to run it as a normal user
 +
 
 +
===== Redirect to file (Linux host) =====
  
=== Redirect to console (Linux host) ===
+
When running minicom, type <tt>Ctrl-A</tt> then <tt>L</tt>. Type the name of the capture file.
  
 
==== Using socat ====
 
==== Using socat ====
If you just simply want a display of the debug output in a terminal window, '''socat''' works nicely.
 
  
The usage is very simple:
+
===== For viewing only =====
<pre>socat unix-client:pipe_path stdout</pre>
+
socat unix-client:pipe_path stdout
  
 
You could also do this:
 
You could also do this:
<pre>socat unix-client:pipe_path stdio</pre>
 
  
Substitute "pipe_path" with the path of the pipe you created using VirtualBox.
+
socat unix-client:pipe_path stdio
 +
 
 +
Substitute "pipe_path" with the path of the pipe you created using VirtualBox (e.g. "/tmp/ReactOS-Debug.pipe").
 +
 
 +
In case you want to redirect the socat output to a file you can use the following command:
  
If ReactOS crashes, you should still be able to type in the VirtualBox window - eg within a debug session. You'll see the input and output on the console window which socat is running in.
+
socat -u unix-client:pipe_path stdio OPEN:log_file_name,creat,trunc
  
==== Using minicom ====
+
Where log_file_name is the file you want to send VirtualBox serial output to.
This guide is based on the terminal application minicom. First install it by typing:
 
<pre>sudo apt-get install minicom</pre>
 
Then you will have to configure a pipe. Type Ctrl+A, then O. Select Configure serial ports, and name the device <pre>unix#pipe_path</pre> where "pipe_path" is a file like /tmp/vboxlog which will be used as pipe between the VM and minicom.
 
  
Create the new Virtual Machine in VirtualBox, then go to the Serial Ports configuration. Select Host pipe, type the "pipe_path" and select Create Pipe.
+
If ReactOS crashes, you should still be able to type in the VirtualBox window – e.g. within a debug session. You'll see the input and output on the console window which socat is running in.
  
Make sure that pipe_path is exactly the same on both minicom and VirtualBox.
+
===== For an interactive window (e.g. to get a backtrace) =====
 +
In one terminal tab/window do:
 +
<code> $socat UNIX-CONNECT:/tmp/ReactOS-Debug.pipe PTY,link=/tmp/vbox_term </code>
  
=== Redirect to file (Linux host) ===
+
In an other terminal tab/window do:
When running minicom, type Ctrl-A then L. Type the name of the capture file.
+
<code> $screen /tmp/vbox_term </code>
  
 
=== Serial port output using com0com ===
 
=== Serial port output using com0com ===
Install and configure com0com according to the [[com0com|com0com guide]].
+
 
 +
Install and configure com0com according to the [[com0com]] guide.
  
 
Enable the first serial port for your ReactOS machine. Use port number "COM1", mode "host device" and port path "COM4" or whatever virtual port you created first with com0com.
 
Enable the first serial port for your ReactOS machine. Use port number "COM1", mode "host device" and port path "COM4" or whatever virtual port you created first with com0com.
Line 79: Line 222:
 
Connect your terminal application to your second virtual port and start up VirtualBox.
 
Connect your terminal application to your second virtual port and start up VirtualBox.
  
== Installing Guest Additions ==
+
== Built-in VirtualBox (low-level) debugger ==
 +
VirtualBox has a built-in debugger.
 +
For a detailed description, see in the chapter "12.1.3. The built-in VM debugger"
 +
of VirtualBox User Manual help file.
 +
 
 +
=== Activating debugger ===
 +
The VM debugger is available in all regular production versions of VirtualBox, but it is disabled by default because the average user will have little use for it. There are two ways to access the debugger:
 +
* A debugger console window displayed alongside the VM
 +
* Via the telnet protocol at port 5000
 +
 
 +
The debugger can be enabled in three ways:
 +
 
 +
* Start the VM directly using VirtualBox --startvm, with an additional --dbg,--debug, or --debug-command-line argument. See the VirtualBox usage help for details.
 +
 
 +
* Set the VBOX_GUI_DBG_ENABLED or VBOX_GUI_DBG_AUTO_SHOW environment variable to true before launching the VirtualBox process. Setting these variables (only their presence is checked) is effective even when the first VirtualBox process is the VM selector window. VMs subsequently launched from the selector will have the debugger enabled.
 +
 
 +
* Set the GUI/Dbg/Enabled extra data item in config file to true before launching the VM. This can be set globally or on a per VM basis. Per VM basis – change corresponding .vbox file,  is an XML-formatted settings of virtual machine.
 +
The paths are:
 +
* X:\Users\%username%\.VirtualBox\VirtualBox.xml – for global
 +
 
 +
XML-node: VirtualBox/Global/ExtraData
 +
 
 +
* ...\%VM_NAME%.vbox – for local
 +
 
 +
XML-node: VirtualBox/Machine/ExtraData
 +
 
 +
And under the mentioned XML-node add the next element:
 +
<nowiki><ExtraDataItem name="GUI/Dbg/Enabled" value="true"/></nowiki>
 +
 
 +
As result, a new 'Debug' menu entry will be added to the VirtualBox application. This menu allows the user to open the debugger console.
 +
 
 +
'''NB.''': sometimes this debugger activation requires Windows restart.
 +
 
 +
=== Using the debugger ===
 +
The VM debugger command syntax is loosely modeled on Microsoft and IBM debuggers used on DOS, OS/2 and Windows. Users familiar with symdeb, CodeView, or the OS/2 kernel debugger will find the VirtualBox VM debugger familiar.
 +
The most important command is 'help'.
 +
 
 +
See more at: [http://www.virtualbox.org/manual/ch12.html#ts_debugger VirtualBox debugger manual]
 +
 
 +
== See also ==
 +
* [[Transfer files from the host OS to the virtual drive]]
  
This is NOT recommended for now as there are some bugs the mouse and graphics driver which will make the system useless after install.
+
{{Navigation Virtualization Software}}
  
Just mount the CD in the CD-Drive and open the file VBoxWindowsAdditions.exe and follow the setup instructions.
+
[[Category:Tutorial]]
  
The graphics driver can be controlled by Registry-Hacks only.
+
__NOTOC__
The mouse driver apparently doesn't work at all.
 

Latest revision as of 15:14, 16 January 2021

VirtualBox is a virtual machine for x86 architecture developed by Innotek and maintained by Oracle. There are two versions: the full VirtualBox package with a proprietary license and the VirtualBox Open Source Edition (GPL).

It's easier to configure than QEMU and slightly slower than VMware.

Note: VirtualBox 5.2.44 version is highly and strongly recommended. VirtualBox 6.x branch is still very buggy and unstable, causes fake regressions to be found in ReactOS.

Note: If you have any trouble 'capturing' your mouse/cursor within the Ros-VM-window with VirtualBox, first go to the "machine" tab and then select "Disable mouse integration", then click again on the VM-session you're running to 'capture', and this time it should work.

Note: If you get the error Raw-mode is unavailable courtesy of Hyper-V. (VERR_SUPDRV_NO_RAW_MODE_HYPER_V_ROOT). when attempting to start a Virtual Machine ensure both Hyper-V and Windows Sandbox are unchecked in the "Turn Windows features on or off" section of the Add/Remove Programs control panel applet. (Quickly access it by pressing Win+R and typing appwiz.cpl)

Running the ReactOS Live CD

Note: You can't install ReactOS from the Live CD. You need to use the full installation image, which is called ReactOS BootCD.

The following instructions will guide you through the process of creating a ReactOS compatible virtual machine in VirtualBox, and mounting the Live CD. The process is demonstrated using VirtualBox 4.2.14 r86644 on Windows 7 x64, but it should be similar on other operating systems, and versions.

  • Download the latest LiveCD release
  • Start VirtualBox.
  • Click the 'New' button.
  • Enter a name and set the type to Microsoft Windows. The version should be set to Windows 2003 (32bit). Click next.
  • Choose the amount of RAM you wish to allocate to the Virtual Machine. At least 256 MB is recommended.
  • Add a Virtual Hard Drive, even if you wish to run from CD. A hard drive is required for booting the system. You can either make a new one, or choose an existing one (if formatted it must be FAT16/FAT32). Click Create to create your new VM.
  • Select your new VM and click Settings.
  • Make sure that you assigned only 1 core of CPU to ReactOS VM
  • Go to 'Storage' and select the empty disk IDE controller.
  • Under Attributes, select your Live CD image and tick the 'Live CD/DVD' checkbox.
  • Go to 'System', and make sure that 'Enable I/O APIC' is unchecked.
  • Go to 'Network', click advanced, change the adapter type to 'PCnet-FAST III'. Note: This step should be optional now, as Intel PRO/1000 network card is supported out-of-the box since ReactOS 0.4.12.
  • Press OK. You are now ready to boot ReactOS.

If you are unable to choose the correct screen resolution in ReactOS, then refer to the instructions here. They explain the steps for Windows 8, but it should work for ReactOS as well.

Installing the ReactOS Boot CD

Note: First of all, make sure you have read Installing ReactOS article.

If you type "Reac" as your VM name, VirtualBox will detect that you are creating a ReactOS virtual machine and assign to it a Windows 2003 profile, which is most suitable. Make sure you are using Virtualbox 5.2.18 version or newer to benefit from this feature.

You can customize the amount of RAM you wish to allocate to the Virtual Machine. At least 64 MB are recommended.

Note: Intel PRO/1000 network card is supported out-of-the box since ReactOS 0.4.12. For older ReactOS versions, always select 'PCnet-FAST III'.

After you are done with the installation of ReactOS itself you may want to have Guest Additions too.

Installing Guest Additions

Mount the CD-image with guest additions in the CD-Drive and open the file VBoxWindowsAdditions.exe and follow the setup instructions.

To use the shared folders, follow the instructions on Using shared folders.

Attention: You can only install the VirtualBox guest additions if your virtual machine is configured with max. 32-64MB graphics memory. Otherwise, an attempt to restart after installing the guest additions will result in a BSOD on VBoxDisp.dll. You can adjust the graphics memory in the "Display" section of your VM when it is shut down.

Attention: If you want to install and try Vbox experimental 3d acceleration you should install Vbox additions only in safe mode (press F8 key on boot). Vbox versions 4.X or 5.X are recommended, because 6.1.x has removed 3D acceleration support for Windows OS's earlier than Windows 7 (ReactOS pretends to be XP or 2003).

Setting up audio

ReactOS has had limited support for sound since the 0.3.9 release, but it is recommended to test sound with a trunk build.

In VirtualBox Machine Settings, enable audio and set the following:

  • Host Audio Driver: Windows DirectSound
  • Audio Controller: ICH AC97

After installing ReactOS:

  1. Download the Intel AC 97 driver from ReactOS Application Manager
  2. Extract the files to C:\ReactOS\
  3. Restart the virtual machine
  4. Goto Device Manager
  5. If the Audio Device is not identified properly, find the unknown Audio device
  6. Right-Click and choose to Update the Device Driver
  7. Browse to the C:\ReactOS\inf folder as the install location
  8. Update the Audio Device
  9. Reboot ReactOS
  10. Install and start your favorite audio playback or multimedia application (e.g. Winamp, VLC, MPlayer)
  11. Open an audio file and play

Sometimes this method does not work. In case:

  1. Download the Intel AC 97 driver from ReactOS Application Manager
  2. Extract the files to C:\Downloads\
  3. Copy the folders inf and system32 to C:\ReactOS\
  4. Restart the virtual machine
  5. If it worked, you will be able to hear startup sound (remember to turn up speakers).

Known Issues

  • The AC97 Driver only supports PCM Wave Audio in the range 8000-44.100Khz, 16Bit Samples and 2 Channels
  • Sample rate conversion is not yet supported
  • The driver has issues when changing the sample rate of the audio stream

Getting debug output

Windows

Rosdebug1.png

Steps to be taken:

  • Set up a serial port in VirtualBox.
There are other VM's possible, but they all work more or less the same, and they can all send a debug output to a COM port.
  • Download VirtualBox, if you haven't done so yet.
  • Obviously, to debug/log ReactOS, you also need a ReactOS Debug build. ( You MUST use a Debug build. You will also need 7-Zip to get the ReactOS ISO out of the .7z file.
  • When the VirtualBox-window opens, click on the tab Settings. Click on Serial Ports.
Choose Port Mode: Host Pipe, tick the Create Pipe option, Port Path: \\.\pipe\ros_pipe. (You may see Connect to existing pipe/socket instead of Create Pipe. In this case, untick it.)
IMPORTANT: Don't change the "COM1" port that appears in the Dropdown listbox. Keep it as COM1.
Rosdebug2.png
  • Download and start PuTTY or your own favourite serial terminal (e.g. HyperTerminal,... )
This is the program that creates the debug logs. PuTTY can listen to a COM port and write it to file. If you don't know what you're looking for, get the
"For Windows on Intel x86" putty.exe file. It doesn't need to be installed; you just have to know where you downloaded it to. On Windows Vista and later
it must be run as Admin, as anything that is to use named pipes.
  • Make sure Session is selected on the TreeView on the left. In the main part of the window, under Connection Type, choose the radiobutton Serial. Under Serial Line type \\.\pipe\ros_pipe. Under speed, type "115200". Depending on your wish how to log, one can go to the TreeView on the left and click on Logging under Session. Under Session Logging, choose All session output.
  • Log file name indicates where the debug log will be and what it will be called. Use the Browse button to change the location if you like, but make sure you know where it's being saved!
  • Go back to the TreeView on the left and click on Serial (under Connection). Set Flow Control to None. PuTTY is now configured. Note that on the main page of PuTTY you can Save/Load configurations which makes it even easier.
  • Thus, after you elect the serial as connection type, set speed to 115200 baud and put the named pipe path as serial line (\\.\pipe\ros_pipe), you are ready to go. Of course, instead of ros_pipe, you can use any unique name, only mind to follow the \\.\pipe\[pipe_name] scheme.
  • Click on "Open" at the bottom of the PuTTY-window. This activates PuTTY's debug-log-creating abilities, which is a black window with a flashing green
cursor. If you can see your PuTTY window in the background, you'll see lots of text flying past as PuTTY does its thing. When you've finished with
exploring ReactOS, you'll have your debug log there. When you shut down the virtual machine, PuTTY will change to inactive state and display error
message, but when you restart the virtual machine, you can easily reconnect that session by pressing right mouse button on window top bar and selecting
Restart session.
  • First start ReactOS in DEBUG MODE in VirtualBox, then open PuTTY and watch the log.

It has been suggested that there might be some slight data loss with pipes under very heavy output. If one notices this as being the case, and one intends to be a heavy tester/logger, there is still another way of getting a debug-log to work:

Com0com : This is the VirtualBox/PuTTY bridge. It gives you the option to have multiple COM port pairs, but you really only need 1 COM port pair. (Virtual Port Pair 0, for instance). Download and install com0com virtual comport redirector. See the com0com tutorial for more info. At the setup window, you'll see the names of the virtual serial ports (default: "CNCA0" and "CNCB0"). Be sure to check that the driver for com0com is installed correctly (with Device Manager, for instance). Then start your VM. In VirtualBox, go to "Settings", "Serial Ports" and set "Port Mode" to "Host Device" in the drop-down box (NOT "Host pipe"). Then, set Port/File Path to "\\.\CNCA0". Next, start Putty; check "Serial" and at the Serial line now type "CNCB0", and click on "open". As said earlier, a black box should appear, and when you run ReactOS in debug mode, the box will fill with text, aka, your log.

IMPORTANT: Make sure to use the digitally signed version of the com0com driver on 64-bit versions of Windows Vista and later.

Using VMwareGateway

You need to download the VMwareGateway application. Start it with /r option to make it run as a service (in Windows Vista you have to use an elevated CMD for this). You can download a x86/x64 build here that does not require VirtualBox to run elevated on Vista/Win7. Next you need to start the service, using SC command:

sc start vmwaregateway

Sort out any firewall pop-up if applicable. Finally, use your favorite telnet client to connect to localhost on port 567.

To configure your virtual machine, set it to Host Pipe with the following pipe address:

\\.\pipe\vmwaredebug

Make sure you do not mark the Create Pipe box. VMwareGateway has already created it. Debug output should appear in your telnet client PuttyTel.

Linux

  • Install VirtualBox package, how to do so will depends on your distribution

On Debian or Ubuntu: sudo apt-get install virtualbox

  • Obviously, to debug/log ReactOS, you also need a ReactOS Debug build. ( You MUST use a Debug build. You will also need 7-Zip to get the ReactOS ISO out of the .7z file.
  • Set up a serial port in VirtualBox.

Setup a serial port in VirtualBox as shown in the picture to the right and below.

  • When the VirtualBox-window opens, click on the tab Settings. Click on Serial Ports.
Choose Port Mode: Host Pipe, tick the Create Pipe option, Port Path: /tmp/ReactOS-Debug.pipe. (You may see Connect to existing pipe/socket instead of Create Pipe. In this case, untick it.)
IMPORTANT: Don't change the "COM1" port that appears in the Dropdown listbox. Keep it as COM1.
VirtualBox-4.0.8.Setup serial port for socat pipe.png

Using minicom

This guide is based on the terminal application minicom. First install it by typing:

sudo apt-get install minicom
Configuring the serial port in minicom
  • "sudo minicom -s" will allow you to set your port and save the configuration file (dfl = default)
  • Choose "Configure serial ports". Name the device unix#pipe_path where "pipe_path" is a file like /tmp/ReactOS-Debug.pipe which will be used as pipe between the virtual machine and minicom.

Make sure that pipe_path is exactly the same on both minicom and VirtualBox.

  • Save config (dfl) will save your configure
  • Exit
  • now after starting the VM, execute "minicom" without sudo, to run it as a normal user
Redirect to file (Linux host)

When running minicom, type Ctrl-A then L. Type the name of the capture file.

Using socat

For viewing only
socat unix-client:pipe_path stdout

You could also do this:

socat unix-client:pipe_path stdio

Substitute "pipe_path" with the path of the pipe you created using VirtualBox (e.g. "/tmp/ReactOS-Debug.pipe").

In case you want to redirect the socat output to a file you can use the following command:

socat -u unix-client:pipe_path stdio OPEN:log_file_name,creat,trunc

Where log_file_name is the file you want to send VirtualBox serial output to.

If ReactOS crashes, you should still be able to type in the VirtualBox window – e.g. within a debug session. You'll see the input and output on the console window which socat is running in.

For an interactive window (e.g. to get a backtrace)

In one terminal tab/window do: $socat UNIX-CONNECT:/tmp/ReactOS-Debug.pipe PTY,link=/tmp/vbox_term

In an other terminal tab/window do: $screen /tmp/vbox_term

Serial port output using com0com

Install and configure com0com according to the com0com guide.

Enable the first serial port for your ReactOS machine. Use port number "COM1", mode "host device" and port path "COM4" or whatever virtual port you created first with com0com.

Connect your terminal application to your second virtual port and start up VirtualBox.

Built-in VirtualBox (low-level) debugger

VirtualBox has a built-in debugger. For a detailed description, see in the chapter "12.1.3. The built-in VM debugger" of VirtualBox User Manual help file.

Activating debugger

The VM debugger is available in all regular production versions of VirtualBox, but it is disabled by default because the average user will have little use for it. There are two ways to access the debugger:

  • A debugger console window displayed alongside the VM
  • Via the telnet protocol at port 5000

The debugger can be enabled in three ways:

  • Start the VM directly using VirtualBox --startvm, with an additional --dbg,--debug, or --debug-command-line argument. See the VirtualBox usage help for details.
  • Set the VBOX_GUI_DBG_ENABLED or VBOX_GUI_DBG_AUTO_SHOW environment variable to true before launching the VirtualBox process. Setting these variables (only their presence is checked) is effective even when the first VirtualBox process is the VM selector window. VMs subsequently launched from the selector will have the debugger enabled.
  • Set the GUI/Dbg/Enabled extra data item in config file to true before launching the VM. This can be set globally or on a per VM basis. Per VM basis – change corresponding .vbox file, is an XML-formatted settings of virtual machine.

The paths are:

  • X:\Users\%username%\.VirtualBox\VirtualBox.xml – for global

XML-node: VirtualBox/Global/ExtraData

  • ...\%VM_NAME%.vbox – for local

XML-node: VirtualBox/Machine/ExtraData

And under the mentioned XML-node add the next element: <ExtraDataItem name="GUI/Dbg/Enabled" value="true"/>

As result, a new 'Debug' menu entry will be added to the VirtualBox application. This menu allows the user to open the debugger console.

NB.: sometimes this debugger activation requires Windows restart.

Using the debugger

The VM debugger command syntax is loosely modeled on Microsoft and IBM debuggers used on DOS, OS/2 and Windows. Users familiar with symdeb, CodeView, or the OS/2 kernel debugger will find the VirtualBox VM debugger familiar. The most important command is 'help'.

See more at: VirtualBox debugger manual

See also

Virtualization software‎ to run ReactOS on
Windows Bochs | Hyper-V | PCem | QEMU | Virtual PC | VirtualBox | VMware
ReactOS Bochs | PCem | QEMU | Virtual PC
Linux Bochs | PCem | QEMU | VirtualBox