.

NAME

ctys-VBOX - VirtualBox(TM) Interface

SYNTAX

   ctys -t VBOX  -a action[=<suboptions>] ...
   ctys -T VBOX  -a action[=<suboptions>] ...
   ctys -T ALL   -a action[=<suboptions>] ...

DESCRIPTION

ATTENTION:

Current version of VBOX-Plugin is an ALPHA RELEASE with partial function, refer to releasenotes. Contained functions comprise CREATE, CANCEL, LIST, ENUMERATE, INFO, and SHOW. Some toolset functions may be missing for now, the following description is defined as a draft for the target version. Current version may not yet contain e.g. the automated inventory registration and the autonomous installer tools.

The VBOX plugin adds support for sessions to VirtualMachines of type VirtualBox - Oracle(TM).

The management of the virtual machines include particularly the support of boot and shutdown for local and remote virtual machines including an inventory with accessible machines. Stored machines on network devices could be accessed by multiple worker-machines, providing a multipath-registration within the inventory. The inventory is populated automatically by scanning the local and remote filesystems and collecting the information of detected VMs into a local ASCII file-database.

The access to VMs is supported by the full scope of the <machine-address>, thus e.g. a user defined LABEL as a shortcut-alias could be used. The VBOX plugin is "VM-STACK safe" as it handles running embedded virtual machines and emulators by propagating state change events(e.g. SHUTDOWN) of the execution platform to contained hypervisors and emulators.

The supported product versions are automatically detected, thus no furter parameters for version distinction are required.

For now in case of usage of ctys-RDP. protocol the access permissions have to be set before by the user. This could be either performed from the standard GUI of the VirtualBox command, or by e.g. VBoxManage with the following call:

• VBoxManage controlvm vrdp=on

Optionally for required shared mode:

• VBoxManage modifyvm vrdpmulticon=on

Additional information for installation is available from ctys-configuration-VBOX, information containing use-cases with application examples is available from ctys-uc-VBOX.

OPTIONS

-a action[=<suboptions>]

For the complete Syntax refer to the depicted generic superset within the call-framework ctys(1) .

-a CANCEL

The client server communications is handeled basically by two different types of client server communications. Following applies to the generic framework interface:

1. Tightly coupled synchronous stateful communications, where the cancellation of the client terminates the server too.

2. Loosely coupled asyncronous stateless communications, where the server exists independently from the client. Thus a cancel ot the client(s) does not influence the existence of the server processes. This mode could be applied in the so called 'headless' mode.

_

Particularly the wildcard-attribute ALL is provided for application on all sessions of selected and permissive user-scope.

-a CREATE

This starts a VM, where following could be applied.

CONSOLE

All available console types for the supported versions could be used. An overview of provided CONSOLE types is listed within the description of the standard call for CREATE. Particularly the following console types are available for VBOX:

VBOX

The standard frontend, but is of type synchronous, where the states of client and server as tightly coupled. This could be used in DISPLAYFORWARDING mode only.

VBOXSDL

Similar to the standard frontend, is of type synchronous too, where the states of client and server as tightly coupled. This could be used in DISPLAYFORWARDING mode only.

RDP

This is functionally similar to the VNC type, where the access is loosely coupled by an stateless asynchronous GUI protocoll. Thus this type could be arbitrarily attached and detached.

Current version supports the rdesktop client only, which is detected automatically, the order of scan for the location of the binaries could be varied by configuration files.

NONE

The initially headless mode.

-a ENUMERATE

Enumerates all VBOX sessions, therefore first the created ctys-files are searched, which are required by convention to be coallocated with the vdi-file of the virtual system storage. When missing the vdi-files are scanned and for any found the information is accomplished by call of VBoxManage. A prerequisite is here the previous registration of the VM, which could be automated by the ctys scanners.

The current version requires for several functions a valid installation of VirtualBox(TM) on the executing machine. When no installation is found only very basic information is collected and the 'VMSTATE' is set to 'DISABLED'. This is due to the requirement of VBoxManage as the interface for transformation and mapping of the label/name and UUID of the VMs. This is also utilized for the match-filters within the automated scanners.

Once the VM is detected the second optional requirement is the pre-registration of the VMs due to the required analysis of some virtual hardware parameters. These comprise for example the architecture, the virtual RAM, the number of emulated CPUs, and more. When these parameters are not detected they are just ignored and an empty field is added to the machine record.

The next requirement is the access permission to the information, which first requires access to the containing directory and files.

REMARK: This behaviour may be changed and expanded within the next releases.

-L <execution-location>

  
  <execution-location>=(
     (LOCALONLY|LO)
     | (CONNECTIONFORWARDING|CF)
     | (DISPLAYFORWARDING|DF)
     | (SERVERONLY|SO)
    )
  

Currently the following selections are supported:

PREREQUISITES

Supported products:

SEE ALSO

ctys(1) , ctys-CLI(1) , ctys-configuration-VBOX(7) , ctys-createConfVM(1) , ctys-plugins(1) , ctys-RDP(1) , ctys-uc-VBOX(7) , ctys-vhost(1) , ctys-VNC(1) , ctys-X11(1)

For System Tools:
rdesktop: [ http://www.rdesktop.org ]

AUTHOR

Written and maintained by Arno-Can Uestuensoez:

COPYRIGHT

Copyright (C) 2008, 2009, 2010 Ingenieurbuero Arno-Can Uestuensoez

For BASE package following licenses apply,

• for software see GPL3 for license conditions,
• for documents see GFDL-1.3 with invariant sections for license conditions,

This document is part of the DOC package,

• for documents and contents from DOC package see
  'Creative-Common-Licence-3.0 - Attrib: Non-Commercial, Non-Deriv'
  
  
  with optional extensions for license conditions.

For additional information refer to enclosed Releasenotes and License files.