 VirtualBox Control Service
============================
v 0.3.3 (c) 2010 vu1tur.eu.org

DESCRIPTION
-----------
This program is a win32 service that runs under SYSTEM account and provides 
automatic start/shutdown for a VirtualBox virtual machine. Installing this 
service gives you the ability to start a virtual machine on system start and 
gracefully shut it down on system shutdown. You can use following actions: 
poweroff, savestate, acpipowerbutton or acpisleepbutton.


CONFIGURATION
-------------
Configuration is done via .ini file with the same name as the service 
executable. A default configuration file is included in distribution archive.

Configuration options:
 VboxInstallPath:
     Set this to a folder where VirtualBox is installed
 VboxUserHome:
     Set this to a location of your .VirtualBox homedir
 VmName:
     The name of the virtual machine this service will control
 ShutdownCommand:
     The command used to shutdown a VM: poweroff, savestate, acpipowerbutton,
     acpisleepbutton
 ServiceName:
     An optional service display name
 Loglevel:
     Log level: 0=Disabled, 1=Enabled, 2=Verbose
 Priority:
     Priority of the VM process: Idle, Below Normal, Normal, Above Normal, High
     
You should create/modify a configuration file before installing the service. 
And before that you should already have all your VMs created and configured 
using VirtualBox GUI or CLI.

Configuration of tray helper application is done via vboxctrltray.ini file.
For each VirtualBox machine add a new section with a name of your choice and
specify the location of vboxctrl.ini file with ConfigFile option. Refer to
sample configuration file for details.


INSTALLATION
------------
Place vboxctrl.exe and vboxctrl.ini in a folder of your choice.

To install a service run:
    vboxctrl -i

To uninstall a service run:
    vboxctrl -u

The name for the service to be installed is taken from the executable filename, 
while the display name (if given) is taken from a configuration file.
    
If you need to have several VMs to be controlled by the service make a copy of 
vboxctrl.exe and vboxctrl.ini with a different name, edit VmName, ServiceName,
ShutdownCommand and run:

    vboxctrl_copy -i
       to install a new service
       
    vboxctrl_copy -u
	   to uninstall a new service

Place vboxctrltray.exe and vboxctrltray.ini in a folder of your choice. Edit
vboxctrltray.ini file to match services you have configured above.

Be sure to update all vboxctrl.exe executables and reinstall services if
upgrading from previous version unless stated otherwise.


PRINCIPLES OF OPERATION AND LIMITATIONS
---------------------------------------
Because VirtualBox is meant to be run under user account (with per-user 
configuration) in order to run it under SYSTEM account it would require you to 
run VirtualBox GUI and create virtual machines from that same SYSTEM account. 
Since it's not very convenient to do so, an easy workaround would be to copy 
your .VirtualBox folder (%USERPROFILE%\.VirtualBox) to the SYSTEM profile folder
(%SYSTEMROOT%\system32\config\systemprofile) after creating and configuring all
virtual machines from GUI. Actually, the location of .VirtualBox folder is set 
by a user environment variable %VBOX_USER_HOME% and by overriding it for 
VirtualBox process running as a SYSTEM account you won't even need to copy it. 
And this is exactly what this service does. And since 0.2.0 VirtualBox COM 
interface is used to control VMs.

But because of some locking techniques in VirtualBox as soon as you start at 
least one virtual machine as a system service, any changes you make to 
configuration (like adding/renaming VMs) in the GUI/CLI (that was run as a user)
will be unavailable to the service until all of the VMs have been shut down 
(powered off or saved state).

If you absolutely need to make changes while one or more VMs is running you 
would have to use psexec to run VirtualBox GUI or VBoxManage as a SYSTEM 
account. Moreover, you need to have at least one vboxctrl service running for 
having VBoxSVC started with %VBOX_USER_HOME% variable set.

For Windows XP/2003 that would simply be:
    psexec -sdi "%VBOX_INSTALL_PATH%\VirtualBox.exe"

Windows Vista/2008 and Windows 7 introduced Session 0 Isolation, so the command
is slightly different:
    psexec -sd -i 0 "%VBOX_INSTALL_PATH%\VirtualBox.exe"
    
and then you need to click 'Show me the message' button in the interactive 
services dialog detection dialog.

Note for Windows XP/2003 users. If a virtual machine takes too long to shutdown
or save state Windows will just terminate it. How long is too long depends on a
number of things, so if you see that VM doesn't shut down cleanly you will have
to stop the service manually before shutting down or restarting the system.


LICENSE AND CREDITS
-------------------
VirtualBox Control Service is free software; you can redistribute it and/or 
modify it under the terms of the GNU General Public License as published by the 
Free Software Foundation; either version 2 of the License, or (at your option) 
any later version.

VirtualBox Control Service is distributed in the hope that it will be useful, 
but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 
or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for 
more details.

Icons from Silk icon set by Mark James were used in this program.
(http://www.famfamfam.com/lab/icons/silk/)


CHANGELOG
---------
0.3.3
      * Fixed yet another bug in communication between tray helper and service
0.3.2
      * Fixed a bug in communication between tray helper and service (resulted 
	    in disabled VRDP console menu item);
      * Fixed service installation procedure not setting correct permissions 
	    in localized versions of Windows.
0.3.1
      * New feature: open VRDP console from tray helper;
      * Fixed tray icon disappearing on explorer crash.
0.3.0
      * Added tray helper application to control vboxctrl services.
0.2.1
      * Updated to support VirtualBox 3.2.0 (for versions up to 3.1.8 use 
        vboxctrl 0.2.0). Don't forget to update vboxctrl.ini file to reflect 
        possible VirtualBox installation path change if upgrading from 0.2.0.
0.2.0
      * Completly rewritten to use VirtualBox COM interface since during the
        shutdown we can't rely on spawning a VBoxManage process. Now there are 
        2 separate builds for x86 and x64 architectures.
      
0.1.1
      * Fixed incorrect handling of shutdown signal

0.1     
        First public release


=============================
http://vu1tur.eu.org/vboxctrl
