2.20. Oracle VM VirtualBox Watchdog

The memory ballooning service, formerly known as VBoxBalloonCtrl, was renamed to VBoxWatchdog. This service now incorporates the following host services that are meant to be run in a server environment:

  • Memory ballooning control. This service automatically takes care of a VM's configured memory balloon. See Memory Ballooning. This service is useful for server environments where VMs may dynamically require more or less memory during runtime.

    The service periodically checks a VM's current memory balloon and its free guest RAM and automatically adjusts the current memory balloon by inflating or deflating it accordingly. This handling only applies to running VMs having recent Guest Additions installed.

  • Host isolation detection. This service provides a way to detect whether the host cannot reach the specific Oracle VM VirtualBox server instance anymore and take appropriate actions, such as shutting down, saving the current state or even powering down certain VMs.

All configuration values can be either specified using the command line or global extradata, whereas command line values always have a higher priority when set. Some of the configuration values also be specified on a per-VM basis. So the overall lookup order is: command line, per-VM basis extradata if available, global extradata.

2.20.1. Memory Ballooning Control

The memory ballooning control inflates and deflates the memory balloon of VMs based on the VMs free memory and the desired maximum balloon size.

To set up the memory ballooning control the maximum ballooning size a VM can reach needs to be set. This can be specified using the command line, as follows:

--balloon-max <Size in MB>

Using a per-VM basis extradata value, as follows:

VBoxManage setextradata <VM-Name> VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonSizeMax <Size in MB>
Note

If no maximum ballooning size is specified by at least one of the parameters above, no ballooning will be performed at all.

Setting the ballooning increment in MB can be either done using command line, as follows:

--balloon-inc <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonIncrementMB <Size in MB>

The default ballooning increment is 256 MB if not specified.

The same options apply for a ballooning decrement. Using the command line, as follows:

--balloon-dec <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonDecrementMB <Size in MB>

The default ballooning decrement is 128 MB if not specified.

The lower limit in MB for a balloon can be defined using the command line, as follows:

--balloon-lower-limit <Size in MB>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/BalloonCtrl/BalloonLowerLimitMB <Size in MB>

The default lower limit is 128 MB if not specified.

2.20.2. Host Isolation Detection

To detect whether a host is being isolated, that is, the host cannot reach the Oracle VM VirtualBox server instance anymore, the host needs to set an alternating value to a global extradata value within a time period. If this value is not set within that time period a timeout occurred and the so-called host isolation response will be performed to the VMs handled. Which VMs are handled can be controlled by defining VM groups and assigning VMs to those groups. By default no groups are set, meaning that all VMs on the server will be handled when no host response is received within 30 seconds.

Set the groups handled by the host isolation detection using the following command line:

--apimon-groups=<string[,stringN]>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/Groups <string[,stringN]>

Set the host isolation timeout using the following command line:

--apimon-isln-timeout=<ms>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationTimeoutMS <ms>

Set the actual host isolation response using the following command line:

--apimon-isln-response=<cmd>

Using a global extradata value, as follows:

VBoxManage setextradata global VBoxInternal2/Watchdog/APIMonitor/IsolationResponse <cmd>

The following response commands are available:

  • none. This has no effect.

  • pause. Pauses the execution of a VM.

  • poweroff. Shuts down the VM by pressing the virtual power button. The VM will not have the chance of saving any data or veto the shutdown process.

  • save. Saves the current machine state and powers off the VM afterwards. If saving the machine state fails the VM will be paused.

  • shutdown. Shuts down the VM in a gentle way by sending an ACPI shutdown event to the VM's operating system. The OS then has the chance of doing a clean shutdown.

2.20.3. More Information

For more advanced options and parameters like verbose logging check the built-in command line help accessible with --help.

2.20.4. Linux: Starting the Watchdog Service With init

On Linux, the watchdog service can be automatically started during host boot by adding appropriate parameters to the file /etc/default/virtualbox. There is one mandatory parameter, VBOXWATCHDOG_USER, which must be set to the user which will later start the VMs. For backward compatibility you can also specify VBOXBALLOONCTRL_USER.

The parameters in the following table all start with the VBOXWATCHDOG_ prefix string. For example: VBOXWATCHDOG_BALLOON_INTERVAL and VBOXWATCHDOG_LOGSIZE. Legacy parameters such as VBOXBALLOONCTRL_INTERVAL can still be used.

Table 2.3 Oracle VM VirtualBox Watchdog Configuration Parameters

Parameter

Description

Default

USER

The user which the watchdog service runs as

ROTATE

Number of log files, 0 disables log rotation

10

LOGSIZE

Maximum log file size to trigger rotation, in bytes

1MB

LOGINTERVAL

Maximum time interval to trigger log rotation, in seconds

1 day

BALLOON_INTERVAL

Interval for checking the balloon size, in milliseconds

30000

BALLOON_INCREMENT

Balloon size increment, in megabytes

256

BALLOON_DECREMENT

Balloon size decrement, in megabytes

128

BALLOON_LOWERLIMIT

Balloon size lower limit, in megabytes

64

BALLOON_SAFETYMARGIN

Free memory required for decreasing the balloon size, in megabytes

1024


2.20.5. Oracle Solaris: Starting the Watchdog Service With SMF

On Oracle Solaris hosts, the Oracle VM VirtualBox watchdog service daemon is integrated into the SMF framework. You can change the parameters, but do not have to if the defaults already match your needs:

svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
  config/balloon_interval=10000
svccfg -s svc:/application/virtualbox/balloonctrl:default setprop \
config/balloon_safetymargin=134217728

Table 2.3, “Oracle VM VirtualBox Watchdog Configuration Parameters” also applies for Oracle Solaris. The parameter names must be changed to lowercase and a prefix of config/ has to be added. For example: config/user or config/balloon_safetymargin. If you made any change, do not forget to run the following command to put the changes into effect immediately:

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

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

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

When everything is configured correctly you can start the Oracle VM VirtualBox watchdog service with the following command:

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

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