November, 2010



ctys-uc-debian - Use-Cases for Setup of debian



The current document shows the basic installation of Debian.

The following host environment is used here:

The following client environment is used here:

The following common assumptions and simplifications are choosen, when multiple approaches are valid.

  1. The initial start of the machines are executed before scanning these into the inventory database. Thus the call is frequently executed by the suboption BASEPATH of <machine-address> or for short 'b:$PWD', which defines the filesystem scan to be started at the given directory, in this case the current dir. This is particularly helpful in NFS based distributed environments with processing nodes containing identical directory structures.

  2. The initial installation is proceeded by the vendor tools, when available. This avoids some deeper knowledge for the application of varios options.

  3. The example setups are generally the provided defaults by the distributions. This should be also the first trial to become familiar with the environment.


Setup of Host-OS and Hypervisor

The installation for the following variants has to be performed by the appropriate standard setup of the HostOS, which quite straight forward:

Setup of the UnifiedSessionsManager

Install tgz-Packages

  1. Apply the standard installation procedure:

      ctys-distribute -F 2 -P UserHomeCopy root@myHost
    For short
      ctys-distribute -F 2 -P uhc root@myHost

  2. Open a Remote Shell by call of CLI plugin:
      ctys -t cli -a create=l:myHost root@myHost

  3. Check the plugins states by calling ctys-plugins:
      ctys-plugins -T all -E

Install rpm-Packages

The following steps are required for a RPM based setup on CentOS. The installation is relocatable, but located at '/opt', and installed locally by 'ctys-distribute'.

  1. Install BASE package.
      rpm -i ctys-base-01.11.011.noarch.rpm

  2. Now install a a local version, here by copy. The PATH prefix is important here, particularly in case of updates. The path is resolved to it's actual path by eliminating any symbolic link, and used for consistent link of libraries.
      /opt/ctys-01.11.011/bin/ctys-distribute -F 2 -P UserHomeCopy

  3. Next the menu is setup.
      ctys-xdg --menu-create

  4. Now the help is available as eihter a Gnome or KDE menu. Alternatively could be called from the commandline.

Setup of the Gnome Menu

The setup of the Gnome Menu is quite simple, the contained tool ctys-xdg sets up a standard menu by the call:

  ctys-xdg --menu-create

Default Menu

The call

  ctys-xdg --menu-cancel

removes the installed files. For current version no checks for changed files is done.

The menues could be edited and extended by the call

  ctys-xdg --menu-edit

which opens the related directories for modification of '*.menu', '*.desktop', and '*.directory' files.

Creation of the the Raw-VM

Creation of the Raw-VM with QEMU/KVM

The demo example VM is here named tst004, this is the hostname of GuestOS too.

  1. Login into the machine where QEMU/KVM is installed.
      ssh -X app2

    When just the processing node of mounted filesystem has to be changed, the following call could be applied. This works in case of identical mount paths:
      ctys -t cli -a create=l:tst004,cd:$PWD root@lab02

  2. Change to the vmpool and create a directory and change into.
      mkdir tst004

  3. Call the install and configuration utility for VMs. Here some values are set by environment variables, a complete list including the actually assigned values could be displayed by the option --levo.
      ARCH=x86_64 \
      DIST=debian \
      DISTREL=5.0.6 \
      OS=Linux \
      OSREL=2.6.32-6 \
      ctys-createConfVM -t qemu --label=tst004
    This call creates a virtual image(hda.img), the call-wrapper(tst219.sh), and the configuration file(tst004.ctys). The files are created from templates by assigning configuration values either from pre-configured default values, or interactive variation. The whole process of createion could be batch-proceeded by using the either teh --auto, or the --auto-all option when appropriate default values are preconfigured.

    When no MAC database nor DHCP is available, the MAC and IP addresses might be provided too.

  4. Once the set of files is created the virtual machine is prepared for startup. For some other systems complete installation routines are available, e.g. debian and CentOS. The current state could be checked now by the following call.

      ./tst004.sh --console=vnc  --vncaccessdisplay=47 --print --instmode --check

  5. The installation could be started now e.g. on the install host by:
      ./tst004.sh --console=vnc  --vncaccessdisplay=47 --print --instmode
    Alternatively a remote call could be proceeded:
      ctys -t qemu -a create=l:tst004,b:${VMPATH},instmode app2

    In case of appropriate defaults(refer to tst004.ctys) this starts e.g. the CD/DVD installation.

    Start Debian installation - CD/DVD

  6. Proceed with standard installation.

    Standard Debian installation

  7. After the installation either a manual reconfiguration of the boot device within the monitor, or by rebooting without the install suboption is required.

    Reboot without changing install media

    The shutdown could be proceeded by the 'quit' command within the monitor. The monitor mode is entered e.g. by Ctrl-Alt-2.

    Reboot without changing install media

  8. In case of a first start the call could look like:
      ctys -t qemu \
         -a create=l:tst004,id:${PWD}/tst004.ctys,console:vnc \
    The default console is here VNC.


    Proceed with standard configuration from now on.

Creation and Installation on VirtualBox

The creation of the raw VM is the first step to be executed at the host operating system. This could be either performed locally or remote and requires the usage of the provided tools by VirtualBox(TM).

  1. Login into the machine where VirtualBox is installed.
      ssh -X lab02

  2. Execute the VirtualBox(TM) console.

  3. Create the VM, the machine is called here 'tst002'. The OS is 'Linux', the version is 'Linux 2.6'.

    Create Virtual Machine

  4. Set RAM to 640MByte.

    Set virtual RAM

  5. Create a virtual HDD, here 8GByte is choosen. When finished the raw VM is present and could be used as required, for basic functions of ctys no additional configuration is required.

    Create Virtual HDD

    Check HDD image file

  6. The network device should be set to 'PCnet-Fast III' with DHCP, either NAT or bridged.

    Network device

  7. The audio card has to be set preferably to 'Sound Blaster 16'.

    Audio device

  8. When additional information should be stored coallocated to the VM and scanned automatically into a database, than the tool ctys-createConfVM(1) should be applied. This generates additional detailed information related to the specific VM and the inherent guest OS. The call could be executed either interactive or automatic.

    Call within the same directory for first inspection:

      DIST=debian \
      DISTREL=5..6 \
      OS=Linux \
      OSREL=2.6-26.2 \
      ctys-createConfVM -t vbox --label=tst002 --levo

    This lists some defaults for the specific hypervisor. These could be preconfigured by specific template files within the configuration directory ctys-createCOnfVM.d. The result should look like the following:

      Not all values require to be set, some will be requested later by 
      Thus it is not neccessary to have values assigned to the complete 
      displayed set.
      Actually used sources for default values:
        no-marker  = Pre-Set value, either from defaults configuration, 
                     or by commandline.
        no-value   = Either requested by dialog later, or the defaults 
                     of the finally called application are used.
        (c)        = Read from actual configuration file, e.g. vmx-file.
        (d)        = Read from database.
        (g)        = Dynamically generated.
        (h)        = Used from current host as default.
        (m)        = Received from mapping definitions.
      Applicable modifications:
        blue       = By call option, defines dependency for others.
        green      = By environment, 'could be set almost independent' 
                     from other values.
        cyan       = By miscellaneous facilities, but is dependent from 
                     E.g. LABEL defines by convention the network 'hostname', 
                     thus the TCP/IP params.
                     This could ..., but should not be altered!
      Most of the missing values will be fetched during actual execution of 
      this tool by dynamic evaluation.
                          VAR name:Initial Value
                               MAC:00:50:56:13:11:32 (c)
                                IP:: (m)
                               TCP:tst002 (m)
                              UUID:a610968d-8cfd-40d1-bf26-30c72e0f4684 (c) 
                              DIST:debian (h)
                           DISTREL:5.0.6 (h)
                                OS:Linux (h)
                             OSREL:2.6.26-2-amd64 (h)
                              ARCH:x86_64 (h)
                       ACCELERATOR:VT  (c)
                               SMP:1 (c)
                           MEMSIZE:640 (c)
      Remember that his is a draft pre-display of current defaults.
      No consistency-checks for provided values are performed at this stage.
      Some missing values are evaluated at a later stage dynamically.

    When the call is finished without the '--levo' option the file 'tst002.ctys' with additional configuration information information is stored.

  9. The start of the VM could be proceeded either by calling VirtualBox, or by the VBOX plugin.

    Install media

    The following call starts the VirtualBox console.

    The following call variant starts the remote VM with a VirtualBox console:
      ctys -t vbox \
       -a create=l:tst002,id:${TST002}/tst002.ctys,console:vbox\

  10. Now boot the VM and choose 'Installation Only' to start the installation.

    Install menue

  11. HDD partitioning, defaults for simplicity.

    Format vHDD

  12. Use for all following dialogues the default until installation starts.

    Proceed Installation

  13. After the installation unmount the install media and boot into debian. In case of a first start the call could look like:
      ctys -t vbox \
         -a create=l:tst002,id:${PWD}/tst002.ctys,console:vbox \
    The default console is here RDP.


    Proceed with standard configuration from now on.

Installation of the GuestOS - debian

  1. Finish innstallation and configuration.

Creation of the Inventory - cacheDB

In case of a common mounted NFS filesystem for the pool VMs for simplicity just change into the directory of the VM on any machine. Call for the first check ctys-vdbgen with the --stdio option for display only.

  ctys-vdbgen --append --base=$PWD --stdio -- lab02

When the result is displyed correctly just call

  ctys-vdbgen --append --base=$PWD -- lab02

The following output should be displayed:

  Prepare execution-call:
  Require DB-PATH,        USE: DEFAULT_DBPATHLST="/homen/acue/.ctys/db/default"
  Require DB-PATH,        USE: -o => "/homen/acue/.ctys/db/default"
  APPEND mode                : ON(1)
  STDIO mode off             : OFF(0)
  Set TYPE scope          ADD: DEFAULT="-t ALL"
  Preload TYPE set        ADD: DEFAULT="-T ALL"
  For splitted operations ADD: DEFAULT="-b sync,seq "
  Nameservice cache       OFF: DEFAULT="-c off "
  Data cache              OFF: DEFAULT="-C off "
  Resulting ENUMERATE     ADD: DEFAULT="-a enumerate=...
      b:/mntn/vmpool/vmpool05/vbox/test/tst-ctys/tst137 \
      -C off  -c off  -T ALL  "
  -> generate DB(may take a while)...
  Cached data:
    Mode:                    APPEND
    Pre-Appended:            834 records
    Appended:                1 records
    Fetched Records Raw:      records
    Fetched Records Unique:   records
    Final:                   835 records

This shows that only one entry is appended to the existing database with 834 VM-Entries. Now check the database entry by calling:

  ctys-vhost tst137

The following result should be displayed:

  label |stype|accel|distro|distrorel|os   |osrel|PM   |if |TCP
  tst137|VBOX |     |CentOS|1.0.0    |Linux|2.6  |lab02|0  |

Graphical Start of the Virtual Machine

Now call the menue item for start of the VM 'tst137'.

Start Menu

The created cacheDB record for thr VM 'tst137' is now automatically visible in the list of startable virtual machines.

CentOS VM Selection

Confirm the selected entry.

CentOS Call Confirmation

Manage the VM

Common Syntax

Prepare CentOS

  1. Set yum repository in '/etc/yum.repo.d/'
  2. Install the following additional Packages:
    1. openssh-server
    2. make
    3. gcc
    4. kernel-devel
    5. kernel-netbook-devel

Almost absolutely required is a Single-Sign-On facility for OpenSSH. This is due to the required multiple remote remote calls for a number of operational modes. Recommended is either the usage of SSH-Keys, or Kerberos by GSSAPI.

Install UnifiedSessionsManager in GuestOS - CentOS

Apply standard procedure:

  ctys-distribute -F 2 -P UserHomeCopy root@tst137

Open a Remote CLI-Terminal

Call CLI plugin:

  ctys -t cli -a create=l:tst137 root@tst137

Check Plugins States

Call ctys-plugins:

  ctys-plugins -T all -E

Open a Remote RDP-Desktop


Open a Remote VNC-Desktop

Call VNC plugin:

  ctys -t vnc -a create=l:tst137,reuse root@tst137

Open a Remote X11-Terminal

Call VNC plugin:

  ctys -t x11 -a create=l:tst137,reuse root@tst137


ctys-VBOX(1), ctys-QEMU(1), ctys-uc-VBOX(7), ctys-uc-QEMU(7), ctys-configuration-VBOX(7), ctys-configuration-QEMU(7)


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 (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.