By default, VirtualBox keeps all sources of time visible to the guest synchronized to a single time source, the monotonic host time. This reflects the assumptions of many guest operating systems, which expect all time sources to reflect “wall clock” time. In special circumstances it may be useful however to make the TSC (time stamp counter) in the guest reflect the time actually spent executing the guest.
This special TSC handling mode can be enabled on a per-VM basis, and for best results must be used only in combination with hardware virtualization. To enable this mode use the following command:
VBoxManage setextradata "My VM" "VBoxInternal/TM/TSCTiedToExecution" 1 To revert to the default TSC handling mode use:
VBoxManage setextradata "My VM" "VBoxInternal/TM/TSCTiedToExecution"
Note that if you use the special TSC handling mode with a guest operating system which is very strict about the consistency of time sources you may get a warning or error message about the timing inconsistency. It may also cause clocks to become unreliable with some guest operating systems depending on they use the TSC.
9.19 Configuring the hard disk vendor product data
(VPD)
VirtualBox reports vendor product data for its virtual hard disks which consist of hard disk serial number, firmware revision and model number. These can be changed using the following commands:
VBoxManage setextradata "My VM"
"VBoxInternal/Devices/ahci/0/Config/Port0/SerialNumber" "serial"
VBoxManage setextradata "My VM"
"VBoxInternal/Devices/ahci/0/Config/Port0/FirmwareRevision" "firmware"
VBoxManage setextradata "My VM"
"VBoxInternal/Devices/ahci/0/Config/Port0/ModelNumber" "model"
The serial number is a 20 byte alphanumeric string, the firmware revision an 8 byte alphanumeric string and the model number a 40 byte alphanumeric string. Instead of “Port0” (referring to the first port), specificy the desired SATA hard disk port.
10 VirtualBox programming
interfaces
VirtualBox comes with comprehensive support for third-party developers. The so- called “Main API” of VirtualBox exposes the entire feature set of the virtualization engine. It is completely documented and available to anyone who wishes to control VirtualBox programmatically.
With VirtualBox, all programming information (documentation, reference informa- tion, header and other interface files as well as samples) have been split out to a separate Software Development Kit (SDK), which is available for download from
http://www.virtualbox.org. In particular, the SDK comes with a “Program- ming Guide and Reference” in PDF format, which contains, among other things, the information that was previously in this chapter of the User Manual.
11 Troubleshooting
This chapter provides answers to commonly asked questions. In order to improve your user experience with VirtualBox, it is recommended to read this section to learn more about common pitfalls and get recommendations on how to use the product.
11.1 General
11.1.1 Collecting debugging information
For problem determination, it is often important to collect debugging information which can be analyzed by VirtualBox support. This section contains information about what kind of information can be obtained.
Every time VirtualBox starts up a VM, a log file is created containing some informa- tion about the VM configuration and runtime events. The log file is called VBox.log and resides in the VM log file folder. Typically this will be a directory like this: $HOME/.VirtualBox/Machines/{machinename}/Logs
When starting a VM, the configuration file of the last run will be renamed to .1, up to .3. Sometimes when there is a problem, it is useful to have a look at the logs. Also when requesting support for VirtualBox, supplying the corresponding log file is mandatory.
For convenience, for each virtual machine, the VirtualBox main window can show these logs in a window. To access it, select a virtual machine from the list on the left and select “Show logs...“ from the “Machine” window.
11.1.2 Guest shows IDE errors for VDI on slow host file system
Occasionally, some host file systems provide very poor writing performance and as a consequence cause the guest to time out IDE commands. This is normal behavior and should normally cause no real problems, as the guest should repeat commands that have timed out. However some guests (e.g. some Linux versions) have severe problems if a write to a VDI file takes longer than about 15 seconds. Some file systems however require more than a minute to complete a single write, if the host cache contains a large amount of data that needs to be written.
The symptom for this problem is that the guest can no longer access its files during large write or copying operations, usually leading to an immediate hang of the guest.
In order to work around this problem (the true fix is to use a faster file system that doesn’t exhibit such unacceptable write performance), it is possible to flush the VDI
after a certain amount of data has been written. This interval is normally infinite, but can be configured individually for each disk of a VM using the following command:
VBoxManage setextradata VMNAME
"VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/FlushInterval" [b]
The value [x] that selects the disk is 0 for the master device on the first channel, 1 for the slave device on the first channel, 2 for the master device on the second channel or 3 for the master device on the second channel. Only disks support this configuration option. It must not be set for CD-ROM drives.
The unit of the interval [b] is the number of bytes written since the last flush. The value for it must be selected so that the occasional long write delays do not occur. Since the proper flush interval depends on the performance of the host and the host filesystem, finding the optimal value that makes the problem disappear requires some experimentation. Values between 1000000 and 10000000 (1 to 10 megabytes) are a good starting point. Decreasing the interval both decreases the probability of the problem and the write performance of the guest. Setting the value unnecessarily low will cost performance without providing any benefits. An interval of 1 will cause a flush for each write operation and should solve the problem in any case, but has a severe write performance penalty.
Providing a value of 0 for [b] is treated as an infinite flush interval, effectively disabling this workaround. Removing the extra data key by specifying no value for [b] has the same effect.
11.1.3 Responding to guest IDE flush requests
If desired, the virtual disk images (VDI) can be flushed when the guest issues the IDE FLUSH CACHE command. Normally these requests are ignored for improved perfor- mance. To enable flushing, issue the following command:
VBoxManage setextradata VMNAME
"VBoxInternal/Devices/piix3ide/0/LUN#[x]/Config/IgnoreFlush" 0
The value [x] that selects the disk is 0 for the master device on the first channel, 1 for the slave device on the first channel, 2 for the master device on the second channel or 3 for the master device on the second channel. Only disks support this configuration option. It must not be set for CD-ROM drives.
Note that this doesn’t affect the flushes performed according to the configuration described in chapter 11.1.2, Guest shows IDE errors for VDI on slow host file system, page142. Restoring the default of ignoring flush commands is possible by setting the value to 1 or by removing the key.