Page 1 of 1

HOWTO: Use Guest Properties

PostPosted: 26. Oct 2008, 20:12
by TerryE

This article was written in 2008, at a time when the information did not exist in the User Manual. You may want to read the more up-to-date information in Chapter 8.33 VBoxManage guestproperty of the User Manual.

This was a piece of functionality that was added in Version 2, but has yet to be incorporated in the User Guide Documentation. It allows you to associate a set of properties with each guest and more importantly you can set, get and enumerate such properties from both the Host and the Guest OSs, thus allowing you to pass parameters between the guest and host OSs and applications.

On the Host the properties are accessed through VBoxManage command with the following qualifiers:
    guestproperty get <vmname>|<uuid> <property> [-verbose]
    guestproperty set <vmname>|<uuid> <property> [<value> [-flags <flags>]]
    guestproperty enumerate <vmname>|<uuid> [-patterns <patterns>]
and on the Guest with the corresponding VBoxControl commands
    guestproperty get <property> [-verbose]
    guestproperty set <property> [<value> [-flags <flags>]]
    guestproperty enumerate [-patterns <patterns>]
Note that the only difference here is that you on the host you need to specify the VM. Also note that on the Host these can also be set and retrieved through the VBox API using the corresponding get and set methods in the IMachine Interface; see the SDK for more details.

These properties are passed between the Host VMM and Guest VBox device driver using the HGCM service VBoxGuestPropSvc.

I haven't had a chance to chase down the patterns spec for enumerations. It certainly doesn't support standard regexps, but the use of * as a multi-character match, so -patterns *GUI* will list all properties containing "GUI".

In the case of a running VM, setting and getting the properties is immediate and synchronous so that you can use these to pass data dynamically between the host and guest.

PostPosted: 27. Oct 2008, 04:41
by TerryE
There have been various posts on how to mount a shared service on startup. I wanted to generalise this to be able to run one or more commands on VM startup where I could specify these on the host. This would allow me to do things like build VMs on the fly, driven entirely from the host through the API or even just VBoxManage. So I thought of using this parameter passing to do this by having a set up a set of parameters
    /Startup/Command/<seq>[<Once>] somecommand
where the Once qualifier clears down the command automatically after it is executed. Hence you could mount a share by doing something like
Code: Select all   Expand viewCollapse view
 VBoxManage guestproperty \
    set jeosLAMP /Startup/Command/1 \
                 "mount -t vboxsf -o fmode=777,dmode=777,uid=1000,gid=1000 HostCache /home/test/cache"

Anyway here is my Ubuntu script /etc/init.d/vbox-enumate-guest-startup:
Code: Select all   Expand viewCollapse view
#! /bin/sh
# Guest Startup script for VirtualBox Linux Additions
# Written by Terry Ellison, 27 Oct 2008
# This file is free software; you can redistribute it and/or modify
# without limitation, but WITHOUT ANY WARRANTY of any kind.

# Exit unless VBox Guest Additions are loaded and VBoxControl is supported
( lsmod | grep -q "^vboxvf" ) || exit
test -e /dev/vboxadd || exit
test -x /usr/bin/VBoxControl || exit

. /lib/lsb/init-functions

echo " * Running Guest Property Startup Commands"

# Now enumerate the /Startup guest properties
props=`VBoxControl -nologo guestproperty enumerate -patterns "/Startup/*" | sed -e's/^Name: //' -e 's/, value: .*$//' | sort`
# And process each of the properties /Startup/* in Ascending Collation order
for param in $props
  log_begin_msg "Running command $param"
  # Get the value associated with the parameter.  It's done this way to ensure to avoid
  # false delimeters embedded in the value
  value=`VBoxControl -nologo guestproperty get $param -verbose | grep ^Value: | cut -b 8-`
  # If the property has the format *Once then it is deleted once read
  case "$param" in
    VBoxControl -nologo guestproperty set $param

  eval $value
  log_end_msg $?
which you need to hook into /etc/rc.local et voilĂ !

controlling processes and shutdown?

PostPosted: 18. Jan 2009, 07:38
by sturban

Any good ideas on how to use this for controlling processes/services on a running guest? -In particular how could you use this to do a controlled shutdown of guest?

-I guess one answer would be to check a guestproperty from cron or similar every five minutes or so. But maybe someone else have a more sophisticated solution?

PostPosted: 19. Jan 2009, 02:17
by TerryE
I used the approach detailed in my last post to automate fully the provisioning of LAMP appliances. I now have a parameter driven host script which will download my VDIs in .vdi.7z format from a central repository, unpack them, configure the VM, start it, mount any shared services, and bootstrap into guest configuration. This way I can configure and build a complete VM service from a single host command. Nice.

One thing that the interface lacks is any form of event based notification. This would make a nice addition in a future release. Perhaps the lightest weight method of implementing this on Linux is as an ash script which dies every 24hrs (and is restarted by a cronjob). The heart of this is a sleep loop which executes a VBoxControl get every 60 secs or so. The loop timing is a balance between the granularity of the event notification and overhead of running the VBoxControl command each minute.

Of course the other alternative is to use SSH with authentication certificates set up between the host and guest so a specific host account can execute scripts on the guest system.

PostPosted: 8. Feb 2009, 21:08
by TerryE
One of the things that I noticed the developers kindly slipped into 2.1 or 2.1.2 without telling anyone is an extra guestproperty command wait <patterns> [-timestamp <last timestamp>] which does exactly as advertised: it suspends the process until there is a change in a property matching <patterns> or the timeout period. This works for both the host VBoxManage and the client VBoxControl versions. So using this you can easily create a low footprint event driven process on the client side to do orderly shutdown or on the host side to create coordinated backup processes.

A nice little addition. Thank-you, developers.

Re: controlling processes and shutdown?

PostPosted: 29. Dec 2009, 03:08
by karatedog
sturban wrote:-I guess one answer would be to check a guestproperty from cron or similar every five minutes or so. But maybe someone else have a more sophisticated solution?

A more elegant solution would be to optionally reroute the Sleep and Hibernate functions of the OS to Virtualbox's Pause and "Save Machine state" functions, respectively.

Re: HOWTO: Use Guest Properties

PostPosted: 5. Jan 2011, 23:10
by Technologov
Let's move this to "Howtos and Tutorials" section. OK ?