9.21. Starting the VirtualBox web service automatically

The VirtualBox web service (vboxwebsrv) is used for controlling VirtualBox remotely. It is documented in detail in the VirtualBox Software Development Kit (SDK); please see Chapter 11, VirtualBox programming interfaces. As the client base using this interface is growing, we added start scripts for the various operation systems we support. The following sections describe how to use them. The VirtualBox web service is never started automatically as a result of a standard installation.

9.21.1. Linux: starting the webservice via init

On Linux, the web service can be automatically started during host boot by adding appropriate parameters to the file /etc/default/virtualbox. There is one mandatory parameter, VBOXWEB_USER, which must be set to the user which will later start the VMs. The paramters in the table below all start with VBOXWEB_ (VBOXWEB_HOST, VBOXWEB_PORT etc.):

Table 9.2. ignored

ParameterDescriptionDefault
USERThe user as which the web service runs 
HOSTThe host to bind the web service tolocalhost
PORTThe port to bind the web service to18083
SSL_KEYFILEServer key and certificate file, PEM format 
SSL_PASSWORDFILEFile name for password to server key 
SSL_CACERTCA certificate file, PEM format 
SSL_CAPATHCA certificate path 
SSL_DHFILEDH file name or DH key length in bits 
SSL_RANDFILEFile containing seed for random number generator 
TIMEOUTSession timeout in seconds; 0 disables timeouts300
CHECK_INTERVALFrequency of timeout checks in seconds5
THREADSMaximum number of worker threads to run in parallel100
KEEPALIVEMaximum number of requests before a socket will be closed100
LOGFILEName of file to write log to 
ROTATENumber of log files; 0 disables log rotation10
LOGSIZEMaximum size of a log file in bytes to trigger rotation1MB
LOGINTERVALMaximum time interval in seconds to trigger log rotation1 day


Setting the parameter SSL_KEYFILE enables the SSL/TLS support. Using encryption is strongly encouraged, as otherwise everything (including passwords) is transferred in clear text.

9.21.2. Solaris: starting the web service via SMF

On Solaris hosts, the VirtualBox web service daemon is integrated into the SMF framework. You can change the parameters, but don't have to if the defaults below already match your needs:

svccfg -s svc:/application/virtualbox/webservice:default setprop config/host=localhost
svccfg -s svc:/application/virtualbox/webservice:default setprop config/port=18083
svccfg -s svc:/application/virtualbox/webservice:default setprop config/user=root

The table in the previous section showing the parameter names and defaults also applies to Solaris. The parameter names must be changed to lowercase and a prefix of config/ has to be added, e.g. config/user or config/ssl_keyfile. If you made any change, don't forget to run the following command to put the changes into effect immediately:

svcadm refresh svc:/application/virtualbox/webservice:default

If you forget the above command then the previous settings will be used when enabling the service. Check the current property settings with:

svcprop -p config svc:/application/virtualbox/webservice:default

When everything is configured correctly you can start the VirtualBox web service with the following command:

svcadm enable svc:/application/virtualbox/webservice:default

For more information about SMF, please refer to the Solaris documentation.

9.21.3. Mac OS X: starting the webservice via launchd

On Mac OS X, launchd is used to start the VirtualBox webservice. An example configuration file can be found in $HOME/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist. It can be enabled by changing the Disabled key from true to false. To manually start the service use the following command:

launchctl load ~/Library/LaunchAgents/org.virtualbox.vboxwebsrv.plist

For additional information on how launchd services could be configured see http://developer.apple.com/mac/library/documentation/MacOSX/Conceptual/BPSystemStartup/BPSystemStartup.html.