Read Me

vboxsvc
=======

SMF service wrapper for Sun/Oracle VirtualBox under Sun/Oracle Solaris 10+
and OpenSolaris builds (including OpenIndiana and illumos).

Detailed project description is available in the
link:usr/share/doc/vboxsvc/README-vboxsvc.txt[README-vboxsvc.txt] file

Discuss and get help in VirtualBox Forum thread 
link:https://forums.virtualbox.org/viewtopic.php?f=11&t=33249["[Free
as in beer\] SMF service for VirtualBox VM's"]

A replica is hosted (and would likely be the HEAD of development soon)
at https://github.com/jimklimov/vboxsvc

See also https://github.com/jimklimov/vboxconfig_sh.git for tweaks needed
to set up Oracle VirtualBox for Solaris packages (4.x, 5.0.x) on illumos
hosts. For recent OpenIndiana and OmniOS (since 2019) there are packages
provided by distributions, and these tweaks are not required then.

Features
~~~~~~~~

* Control VirtualBox VMs as Solaris SMF service instances, including VMs
  owned by unprivileged users and VMs running in Solaris local zones for
  extra resource control by the host OS
* Bring up a VBoxHeadless VM to manage it via X11 GUI console, then resume
  it as Solaris SMF service instance (service interrupted to savestate and
  resume the VM).
* Connect to VM serial consoles (without service interruptions).
* You can set up SMF dependencies between VM instances and system resources
  (as other SMF services) to ensure orderly startup and shutdown with the
  SMF in Solaris-based OSes
* "Hooks" to set up an external script to monitor that the VM is actually
  alive inside and does something useful. VM can be rebooted or placed into
  SMF maintenance if it is not really working.
  ** Since release 0.16 the monitoring script can be used to delay completion
    of the VM's SMF start method to better ensure proper startup of SMF
    dependencies.
* Main new feature of release 0.15 is the ability of vbox.sh to create snapshots
  of ZFS datasets backing the VM and/or its data after shutdown, before startup,
  or on command-line request. Datasets containing the VM config files, VirtualBox
  snapshot files, and HDD image files, can be found automatically.
  ** Since release 0.17, local ZVOLs dedicated to a VM as a virtual HDD (via
    VirtualBox internalcommands) can also be detected. Other datasets (such
    as raw ZVOLs passed with other methods -- i.e. iSCSI) can be listed in
    a special SMF attribute
* Different "VM hardware clock" timezones can be configured for each VM
  (unambiguous "UTC" is recommended however, generally in IT)
* Some other command-line features available (graceful poweroff, soft ACPI
  reboot, hard reset, rude poweroff, status check, take ZFS snapshots of
  backing storage, etc.)
* This project is in development since VirtualBox 2.x was current :)
  Relatively recently tested systems included:
  ** VirtualBox 3.0.12 on host systems from early Solaris 10 to OpenSolaris
    SXCE snv_117 (still Sun) and up to OpenIndiana OI_151a8 (illumos ~2013)
  ** VirtualBox 4.2.0 release and OpenIndiana OI_151a5 host system (~2012),
    most things just work ;)
    *** NOTE: For VirtualBox 4.x the 0.17+ dev SVN version of the script is
      needed, or a manual site-local tweak for earlier releases, to account
      for change in VBox command-line parameters -- vrdp vs. vrde, if you
      use NICE settings)
  ** VirtualBox 5.0.40 on OpenIndiana "hipster" rolling-release (tested/used
    since 2017 with 0.18 dev version)
  ** VirtualBox 5.2.24 built and provided by OpenIndiana "hipster" native
    packaging since early 2019
* Interactive and "dual-boot" VMs are also supported since release 0.17,
  so that the user manually starts up the interactive VM when needed,
  and SMF shuts it down properly when needed. A new `startgui -fg` mode
  and its symlink-based shortcuts allow the controlling script to remain
  in the terminal shell (or spawn a dedicated xterm) and when this shell
  is interrupted -- the VM gets properly shut down, savestated or how ever
  you configure it.
* For non-root users running VirtualBox with delegated local ZFS Volumes,
  a new service script was added in release 0.17 to save and restore via
  ZFS properties the customized (non-default) ZVOL device node ownership
  and access-rights attributes. Solaris and illumos currently lack a
  kernel-based capability to do this automatically :(
  ** See link:usr/share/doc/vboxsvc/README-zvolrights.txt[README-zvolrights.txt]
     for more details, including how to enable this service on your system
     (not done by default).
* The project dates back to 2009, with first CVS commits of our "fork" into
  our internal CVS on 2010-07-18. Published on SourceForge since 2010-12-07.
  Published on GitHub since 2019-03-11. There was little development in the
  later years, because the script "just worked" for everybody interested.
  I can only guess it is nearly perfect then :)
* Version 0.19 is currently in development -- grab a tarball from SVN or
  GitHub to see the bleeding-edge new features! URLs:
  ** http://vboxsvc.svn.sourceforge.net/viewvc/vboxsvc/?view=tar
  ** https://github.com/jimklimov/vboxsvc

Hope this project helps you tame your virtual boxes!

Jim Klimov