ctys-uc-VBOX

June, 2010

.

NAME

ctys-uc-VBOX - Use-Cases for VBOX


USE-CASES

General

This is an alpha version, where the post-install functionality is provided first. Thus the installation and configuration has to be performed by the provided means of the supplier for now.


Install and Configure a VBOX

For current version the standard facilities of VirtualBox(TM) has to be utilized.


CREATE a session

The following call starts a session:

  
  ctys -t vbox -a create=l:vbox001,b:$VMDIRPATH,console:vbox lab02
  

The filename option "b:" is used, which sets the root directory for the subtree to be scanned for the VM defined by the label parameter 'l:vbox001'. The evaluation could be processed from cacheDB and/or by scanning the filesystem on the execution target. The cacheDB is influenced by the option '-c'.

The console is of type VBOX, which is a tightly coupled synchronous console, where the execution states of client and server are correlated.

The directory VMDIRPATH could be any directory pointing to path containing the vdi-file and an optional ctys-file, either self or within the subtree..


CANCEL a session

The UnifiedSessionsManager implements the standard behaviour, to try a native call to the GuestOS first, if that fails or a timeout is hit, than the VMware hypervisor interface vmrun is called.

  
  ctys -t vbox -a cancel=l:vbox001,poweroff:0 lab02
  


LIST sessions

The simple LIST call

  
  ctys -a list lab02 ws2
  


produces the output:

  
  TCP-container|TCP-guest        |label       |stype    |accel|c|user  |group     
  -------------+-----------------+------------+---------+-----+-+------+----------
  ws2          |-                |vbox001     |RDP      |-    |C|acue  |ldapusers 
  ws2          |ws2.soho.        |-           |-        |HVM  |S|-     |-         
  ws2          |ws2              |-           |-        |HVM  |S|-     |-         
  ws2          |-                |vbox001     |SSH(VBOX)|-    |T|acue  |ldapusers 
  lab02.soho   |-                |LAB02       |VNC      |-    |C|root  |root      
  lab02.soho   |-                |tstCF       |VNC      |-    |S|acue  |ldapusers 
  lab02.soho   |-                |LAB02chkusr |VNC      |-    |S|chkusr|ldapusers 
  lab02.soho   |-                |LAB02       |VNC      |-    |S|root  |root      
  lab02.soho   |08:00:27:D2:9E:D9|vbox001     |VBOX     |HVM  |S|acue  |ldapusers 
  lab02.soho   |-                |vbox004     |VBOX     |-    |S|root  |root      
  lab02.soho   |lab02.soho.      |-           |-        |HVM  |S|-     |-         
  


This is the default case for two VMs - vbox001 and vbox004 - running on lab02 with CONNECTIONFORWARDING to ws2, and local only on lab02. The CONNECTIONFORWARDING mode is currently supported for any asynchronous console type. The intermediate SSH tunnel - here SSH(VBOX) is established automatically by the -L CF option.

The same call with the suboption 'machine' and 'titleidx'. The 'machine' suboption forces all available fields to be displayed. The 'tittleidx' displays the human readable names of the fields, including the canonical field index for selection, e.g. within custom tables.

  
  ctys -a list=machine,titleidx lab02 ws2
  


The output is simply formatted as a text-string to the screen width, thus without consideration of the content.

  
  ContainingMachine(1);SessionType(2);Label(3);ID(4);UUID(5);MAC(6);TCP(7);DISPLA
  Y(8);ClientAccessPort(9);ServerAccessPort(10);PID(11);UID(12);GUID(13);C/S-Type
  (14);JobID(15);IFNAME(16);RESERVED1(17);CONTEXTSTRG(18);EXECPATH(19);HYPERRELRU
  N(20);ACCELERATOR(21);ARCH(22)
  ws2;RDP;vbox001;;;;;;5950;;901;acue;ldapusers;CLIENT;;;;;/usr/bin/rdesktop;rdes
  ktop-1.6.0.;;x86_64
  ws2;;;/etc/ctys.d/vm.conf;;00:23:54:2e:eb:96;172.20.1.70;;;;1;;;SERVER;bond0;;;
  ;Linux-2.6.26-ws2-deb-005-ws2-deb-005;debian-5.0;HVM;x86_64
  ws2;;;/etc/ctys.d/vm.conf;;00:23:54:2e:eb:96;;;;;1;;;SERVER;eth0;;;;Linux-2.6.2
  6-ws2-deb-005-ws2-deb-005;debian-5.0;HVM;x86_64
  ws2;SSH(VBOX);vbox001;5950-5904;;;;;5950;5904;891;acue;ldapusers;TUNNEL;2010071
  3081630:22795:0:1:1;;;;;;;
  lab02.soho;VNC;LAB02;1;;;;1;;;27430;root;root;CLIENT;;;;;/usr/bin/vncviewer;Rea
  lVNC-4.1.2;;x86_64
  lab02.soho;VNC;tstCF;3;;;;3;5903;;2213;acue;ldapusers;SERVER;20100712104607:190
  37:0:1:1;;;;Xvnc;RealVNC-4.1.2;;x86_64
  lab02.soho;VNC;LAB02chkusr;2;;;;2;5902;;3267;chkusr;ldapusers;SERVER;2010071020
  0016:31650:0:1:1;;;;Xvnc;RealVNC-4.1.2;;x86_64
  lab02.soho;VNC;LAB02;1;;;;1;5901;;6475;root;root;SERVER;;;;;Xvnc;RealVNC-4.1.2;
  ;x86_64
  lab02.soho;VBOX;vbox001;/mntn/vmpool/vmpool05/vbox/test/initial/vbox001/vbox001
  .vdi;531f42f1-9c64-425e-bf88-319cbe592453;08:00:27:D2:9E:D9;;;5904;;5525;acue;l
  dapusers;SERVER;;;;;/usr/lib/virtualbox/VBoxHeadless;VirtualBox-3.1.2;HVM;x86_6
  4
  lab02.soho;VBOX;vbox004;;;;;;;;9920;root;root;SERVER;;;;;/usr/lib/virtualbox/VB
  oxHeadless;VirtualBox-3.1.2;;
  lab02.soho;;;/etc/ctys.d/vm.conf;;00:0E:0C:CF:5C:12;172.20.1.75;;;;1;;;SERVER;e
  th0;;;;Linux-2.6.18-164.15.1.el5;CentOS-5.4;HVM;x86_64
  


The formatted display of results could be arbitrarily varied by custom tables as shown in the following example. These could be either provided as a call parameter, or stored as MACROs persistently.

  
  ctys -a list=machine,\
     tab_gen:3_label_10%%2_TYPE_8%%1_PM_10%%5_UUID_12%%6_MAC_17%%7_TCP_13\
     lab02 localhost
  


The output results to:

  
  label     |TYPE    |PM        |UUID        |MAC              |TCP          
  ----------+--------+----------+------------+-----------------+-------------
  vbox001   |RDP     |ws2       |            |                 |             
            |        |ws2       |            |00:23:54:2e:eb:96|172.20.1.70  
            |        |ws2       |            |00:23:54:2e:eb:96|             
  vbox001   |SSH(VBOX|ws2       |            |                 |             
  LAB02     |VNC     |lab02.soho|            |                 |             
  tstCF     |VNC     |lab02.soho|            |                 |             
  LAB02chkus|VNC     |lab02.soho|            |                 |             
  LAB02     |VNC     |lab02.soho|            |                 |             
  vbox001   |VBOX    |lab02.soho|531f42f1-9c6|08:00:27:D2:9E:D9|             
  vbox004   |VBOX    |lab02.soho|            |                 |             
            |        |lab02.soho|            |00:0E:0C:CF:5C:12|172.20.1.75  
  


ENUMERATE sessions

The following call displays the main identifier of the test-pool VMs. For additional information refer to User-Manual:"Display of Available Sessions".

  
  ctys -a enumerate=macro:TAB_ENUM_LST,b:/mntn/vmpool/vmpool05/vbox/test/initial lab02
  


The resulting display is:

  
  label  |stype|TCP    |MAC    |UUID                            |ID                       
  -------+-----+-------+-------+--------------------------------+-------------------------
  vbox004|VBOX |       |       |                                |itial/vbox004/vbox004.vdi
  vbox001|VBOX |       |       |531f42f1-9c64-425e-bf88-319cbe59|itial/vbox001/vbox001.vdi
  vbox002|VBOX |       |       |                                |itial/vbox002/vbox002.vdi
  


The same executed on a machine with valid VirtualBox(TM) installation and set 'machine' parameters.

  
  ctys -a enumerate=machine,b:/mntn/vmpool/vmpool05/vbox/test/initial lab02
  


The resulting display is:

  
  lab02.soho;VBOX;vbox004;/mntn/vmpool/vmpool05/vbox/test/initial/vbox004/vbox004.vdi;;;;;
  ;;;;;;;;;;DISABLED;;;;;;;;;;VirtualBox-3.1.2;;;;;;;;;;;;;VERSION:VirtualBox-3.1.2;
  lab02.soho;VBOX;vbox001;/mntn/vmpool/vmpool05/vbox/test/initial/vbox001/vbox001.vdi;531f
  42f1-9c64-425e-bf88-319cbe592453;;;;5904;;;;;OpenBSD;;;;;DISABLED;;;;;;;;;;VirtualBox-3.
  1.2;HVM;;;;;;;;x86_64;;320;1;VERSION:VirtualBox-3.1.2;
  lab02.soho;VBOX;vbox002;/mntn/vmpool/vmpool05/vbox/test/initial/vbox002/vbox002.vdi;;;;;
  ;;;;;;;;;;DISABLED;;;;;;;;;;VirtualBox-3.1.2;;;;;;;;;;;;;VERSION:VirtualBox-3.1.2;
  


The same executed on a machine without installed VirtualBox(TM) and set 'machine' parameter.

  
  ctys -a enumerate=machine,b:/mntn/vmpool/vmpool05/vbox/test/initial 
  


The resulting display is:

The difference is the missing of any attribute where the usage of utilities contained within VirtualBox(TM) is required. This is basically the same case as the missing of access permissions.

  
  ws2;VBOX;vbox004;/mntn/vmpool/vmpool05/vbox/test/initial/vbox004/vbox004.vdi;;;;;;;;;;;;
  ;;;DISABLED;;;;;;;;;;;;;;;;;;;;;;;;
  ws2;VBOX;vbox001;/mntn/vmpool/vmpool05/vbox/test/initial/vbox001/vbox001.vdi;;;;;;;;;;;;
  ;;;DISABLED;;;;;;;;;;;;;;;;;;;;;;;;
  ws2;VBOX;vbox002;/mntn/vmpool/vmpool05/vbox/test/initial/vbox002/vbox002.vdi;;;;;;;;;;;;
  ;;;DISABLED;;;;;;;;;;;;;;;;;;;;;;;;
  


Display of Available Sessions

Once the basic installation and setup is accomplished, first a file-scan based start of a VM should be performed. Therefore the root directory for scanned subtree should be set in order to reduce the actual scan duration. The option -c off deactivates the use of the nameservice cache for an initially empty cacheDB, thus suppresses several warnings and error messages of internally called tools. For further informatio refer to the CREATE action.

The next step - after successful installation and configuration of the UnifiedSesssionsManager is the creation of a populated cacheDB by usage of ctys-vdbgen(1) for storage of a list of actually available instances. This is by default applicable on distributed machines and is performed by default as parallel-tasks with minor dependency on the count on targets. The following call scans a test group with 4VMs, where one has no access permission at all, thus is hidden.

  
  ctys-vdbgen \
     --replace ctys-vdbgen \
     --replace \
     --cacheDB=/homen/acue/.ctys/db/vbox01 \
     --base=/mntn/vmpool/vmpool05/vbox/test/initial \
     lab0
  
  
  ctys-vhost -o pm,label,ids app2 vmw acue tst-ctys
  


The following call of ctys-vhost(1) lists all available VMs with given constraints, in this case all instances of VBOX which could be started by the user "acue" on the host "app2". The set displayed has to be additionally of the set "tst-ctys", which is the testpool for the UnifiedSessionsManager.

  
  ctys-vhost -p /homen/acue/.ctys/db/vbox01/ -o  pm,label,ids .
  


The pm, the ids and the label are displayed as a result.

The additional string '.' is used as a awk-regexpr for any.

  
  lab02.soho;vbox001;/mntn/vmpool/vmpool05/vbox/test/initial/vbox001/vbox001.vdi
  lab02.soho;vbox002;/mntn/vmpool/vmpool05/vbox/test/initial/vbox002/vbox002.vdi
  lab02.soho;vbox004;/mntn/vmpool/vmpool05/vbox/test/initial/vbox004/vbox004.vdi
  


Change LIST Output by Custom Tables

The previous output, which is by default displayed in TERSE format could be formatted by a generic custom table. The following call displays the required canonical field indexes.

  
  ctys-vhost -p /homen/acue/.ctys/db/vbox01/ -o  pm,label,ids,titleidx .
  


The indexes in title line are prefixes as an extended table title by TITLEIDX. The values are the so calle 'Canonical Indexes' of the database records to be used for definition of custom tables.

  
  ContainingMachine(1);Label(3);ID(4);SSHport(27)
  lab02.soho;vbox001;/mntn/vmpool/vmpool05/vbox/test/initial/vbox001/vbox001.vdi
  lab02.soho;vbox002;/mntn/vmpool/vmpool05/vbox/test/initial/vbox002/vbox002.vdi
  lab02.soho;vbox004;/mntn/vmpool/vmpool05/vbox/test/initial/vbox004/vbox004.vdi
  


This values could be now used to define the output table as:

  
  ctys-vhost \
     -o pm,label,ids,tab_gen:1_PM_7%%3_label_4%%4_ID_30 \
     lab02
  



As could be seen in the following output, this table configuration is not really helpful. The field sizes are too short, and the common leading part of the pathnames for the ID fields is quite long.

  
  PM     |labe|ID                            
  -------+----+------------------------------
  lab02.s|vbox|/mntn/vmpool/vmpool05/vbox/tes
  lab02.s|vbox|/mntn/vmpool/vmpool05/vbox/tes
  lab02.s|vbox|/mntn/vmpool/vmpool05/vbox/tes
  


The following changes might help in advance of usability:

  
  ctys-vhost \
     -o pm,label,ids,tab_gen:1_PM_11%%3_label_9%%4_ID_30_L \
     lab02
  


Although this is much more helpful, the raise of the ID value should Ahelp some more.

  
  PM         |label    |ID                            
  -----------+---------+------------------------------
  lab02.soho |vbox001  |st/initial/vbox001/vbox001.vdi
  lab02.soho |vbox002  |st/initial/vbox002/vbox002.vdi
  lab02.soho |vbox004  |st/initial/vbox004/vbox004.vdi
  


Use MACROs for Custom Tables

The previous examples could be stored as MACROs and called just by their macro name. Several preconfigured macros arre available and could be listed with the utility Addtional Information on MACROs is available within the User-Manual. ctys-macros(1)


SEE ALSO

ctys(1) , ctys-CLI(1) , ctys-configuration-VBOX(7) , ctys-createConfVM(1) , ctys-groups(1) , ctys-macros(1) , ctys-plugins(1) , ctys-RDP(1) , ctys-uc-VBOX(7) , ctys-vdbgen(1) , 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:

Maintenance: <<acue_sf1 (a) sourceforge net>>
Homepage: <http://www.UnifiedSessionsManager.org>
Sourceforge.net: <http://sourceforge.net/projects/ctys>
Berlios.de: <http://ctys.berlios.de>
Commercial: <http://www.i4p.com>




COPYRIGHT

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

For BASE package following licenses apply,

This document is part of the DOC package,

For additional information refer to enclosed Releasenotes and License files.