HOWTO: Use Guest Properties

Everything which doesn't fit into the other sections.
Post Reply
TerryE
Volunteer
Posts: 3572
Joined: 28. May 2008, 08:40
Primary OS: Ubuntu other
VBox Version: PUEL
Guest OSses: Ubuntu 10.04 & 11.10, both Svr&Wstn, Debian, CentOS
Contact:

HOWTO: Use Guest Properties

Post by TerryE »


ModEdit
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.
Read the Forum Posting Guide
Google your Q site:VirtualBox.org or search for the answer before posting.
TerryE
Volunteer
Posts: 3572
Joined: 28. May 2008, 08:40
Primary OS: Ubuntu other
VBox Version: PUEL
Guest OSses: Ubuntu 10.04 & 11.10, both Svr&Wstn, Debian, CentOS
Contact:

Post 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

 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

#! /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.
#

PATH=$PATH:/bin:/sbin:/usr/sbin
#
# 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
do
  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
*Once)
    VBoxControl -nologo guestproperty set $param
    ;;
*)
    ;;
  esac

  eval $value
  log_end_msg $?
done
exit
which you need to hook into /etc/rc.local et voilà!
Read the Forum Posting Guide
Google your Q site:VirtualBox.org or search for the answer before posting.
sturban
Posts: 12
Joined: 8. Dec 2008, 10:57

controlling processes and shutdown?

Post by sturban »

Interesting!!

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?
TerryE
Volunteer
Posts: 3572
Joined: 28. May 2008, 08:40
Primary OS: Ubuntu other
VBox Version: PUEL
Guest OSses: Ubuntu 10.04 & 11.10, both Svr&Wstn, Debian, CentOS
Contact:

Post 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.
Read the Forum Posting Guide
Google your Q site:VirtualBox.org or search for the answer before posting.
TerryE
Volunteer
Posts: 3572
Joined: 28. May 2008, 08:40
Primary OS: Ubuntu other
VBox Version: PUEL
Guest OSses: Ubuntu 10.04 & 11.10, both Svr&Wstn, Debian, CentOS
Contact:

Post 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.
Read the Forum Posting Guide
Google your Q site:VirtualBox.org or search for the answer before posting.
karatedog
Posts: 8
Joined: 2. Apr 2009, 22:10
Primary OS: Ubuntu other
VBox Version: OSE Debian
Guest OSses: Ubuntu 9.10, Windows XP, Windows 7, Debian 5 server 64-bit

Re: controlling processes and shutdown?

Post 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.
Technologov
Volunteer
Posts: 3342
Joined: 10. May 2007, 16:59
Location: Israel

Re: HOWTO: Use Guest Properties

Post by Technologov »

Let's move this to "Howtos and Tutorials" section. OK ?
Post Reply