##############################################################################
#
PART I - BEFORE YOU START
#
##############################################################################
Make sure VirtualBox has been installed and your VMs can be started from VirtualBox Manager without any problem. Shutdown all the VMs and close VirtualBox Manager.
IMPORTANT: If you want to control your VMs with VRDP, enable remote display at display settings and assign a dedicated port for each individual VM (e.g. use: 3010 for Vm0, 3020 for Vm1, etc.). Do not use the standard port 3389, which is used by your host machine!
##############################################################################
#
PART II - INSTALLATION
#
##############################################################################
Step 1. Run the VBoxVmService setup program as Administrator
Step 2. Open up VBoxVmService.ini in installation folder and modify it to fit your needs. The file contains an example setup with two virtual machines.
Key / Value pair Description
[Settings]
VBOX_USER_HOME=C:\Users\YOUR_NAME_HERE.VirtualBox The actual path to your user’s .VirtualBox directory. It is usually located in your users’ personal folder.
RunWebService=no Whether or not start up VBoxWebSrv.exe, the VirtualBox HTTP web service automatically. Could be “yes” or “no”. Leave it to “no” if you don’t know what it is.
WebServiceParam= If necessary, you can specify additional parameters for VBoxWebSrv.exe, like “–port” for binding to non-default port.
PauseShutdown=5000 A pause parameter to slow down the Windows shutdown process and to prevent VMs from crashing on shutdown/reboot. (5000 = 5 seconds) Note Windows has a limit to how long the service controller could wait when system reboots. The time limit is specified in the WaitToKillServiceTimeout value of the following registry key: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control. Your PauseShutdown value should never exceed this time limit.
[Vm0]
VmName=ubuntu The name of the VM to start (case sensitive!)
ShutdownMethod=savestate The shutdown method (“savestate”, or “acpipowerbutton”). When “savestate” is used, the machine state is saved and will be resumed when you start VM next time. When “acpipowerbutton” is used, as long as client OS support it, the VM will get a clean shutdown. If your VM takes long time to poweroff, it’s recommanded to use savestate, which could be done very quickly.
AutoStart=yes Whether or not this VM will be started automatically, when VBoxVmService runs. Default to “yes”.
[Vm1]
VmName=winxp As you can see, the above values almost repeat for every [VmX] section of the file.
ShutdownMethod=acpipowerbutton
AutoStart=no This VM will not be started automatically.
Step 3. Reboot your system.
If everything goes on right, you could now connect to your VMs with VRDP clients (or ssh clients, if you’ve configured ssh server inside your VM). If not, refer to TROUBLESHOOTING section below for how to debug.
##############################################################################
#
PART III - UNINSTALL
#
##############################################################################
Step 1. Stop running VBoxVmService service. Run VmServiceTray.exe to stop VBoxVmService, then exit VmServiceTray.exe.
Step 2. Open Control Panel -> Programs, select Uninstall VBoxVmService.
##############################################################################
#
PART IV - TROUBLESHOOTING
#
##############################################################################
If the service does not bring your VMs up as desired, try the following steps:
Setp 1. Check config file.
Carefully re-check the settings you made in “VBoxVmService.ini”.
Setp 2. Debug with VmServiceControl.exe.
Switch to a command prompt, cd to the VBoxVmService directory and type:
VmServiceControl.exe -l [ENTER]
to list all the VMs you configured in “VBoxVmService.ini”, and their current states.
If something goes wrong, reduce the number of VMs in your ini file to one (= only have the section [Settings] and the section [Vm0] in your ini-file) in your ini-file, for debugging.
The command:
VmServiceControl.exe -su 0 [ENTER]
can be used to bring up the VM you set up in the section [Vm0] of the “VBoxVmService.ini” file.
If you have successfully started a VM, you should end up with a “VBoxHeadless.exe” process, running as the impersonated user (check in task manager).
The command:
VmServiceControl.exe -sd 0 [ENTER]
can be used to stop the VM targeting [Vm0]. Afterwards, there should be no running “VBoxHeadless.exe”-process. Additionally, you should see a “VBoxSVC.exe”-process terminating shortly after a successful shutdown of “VBoxHeadless.exe”.
Step 3. Read the log files
The file VBoxVmService.log logs everything imortant to VBoxVmService, like all commands it received, and their results. If something went wrong, you can find error code and/or message there.
If you see error like “Could not find a registered machine named…”, check if the environment variable VBOX_USER_HOME has been setup correctly.
If you made a mistake on VBOX_USER_HOME, however, fixing it at VBoxVmService.ini is not enough. Because the value was get written into environment variable during installation. You’ll need to uninstall VBoxVmService first, then install again.
After installation and everytime when you changed VBOX_USER_HOME later, a system reboot might be required to get VBoxVmService work correctly. So give it a try if you haven’t.
If you can’t see any error in VBoxVmService.log, but the VM just don’t run as expected, check if something goes wrong from VirtualBox’s own log, which is saved to file VBoxSVC.log under your VBOX_USER_HOME folder.
Step 4. Ask for help
Refer to the project wiki at https://github.com/onlyfang/VBoxVmService/wiki or https://github.com/onlyfang/VBoxVmService/issues for a list of known issues.
If you are still in trouble, you are welcome to create a support ticket at https://github.com/onlyfang/VBoxVmService/issues. Please be sure to include your VBoxVmService.ini and VBoxVmService.log, so that we can help checking what might be wrong. We might be on VirtualBox’s official forums now and then, so feel free to contact us there, too.
The VBoxVmService Development Team
Mattz, FB2000 and Runar
