June, 2010



ctys-uc-QEMU - Use-Cases for QEMU and KVM


Install and Configure a VM with ctys-createConfVM

The current version supports a new installer with minimal required remaining manual actions. The Installation process id described within the document ctys-configuration-QEMU for QEMU/KVM. This is basically a 2-stage-approach. The first stage is the call of the interactive tool ctys-configuration-QEMU for creation of a generic Wrapper-Script and an additional configuration file with appropriate values for most of practical cases. The second stage starts QEMU/KVM and begins the boot of the selected GuestOS from the configured bootmedia. This could be performed by several optional interfaces, either from the standard ctys call or by direct-execution of the wrapper-script.

The whole process is designed to be executed in a straight forward manner and should be prefered for the first steps instead of the following legacy-examples.

CREATE a session

The first tests and examples of the QEMU plugin are based on the "arm-tst" VM contained in the examples of QEMU. This is a ready to use VM, but the TCP/IP address is hardcoded to "" thus might be required to be configured. The coldfire test VM contained in the QEMU examples supports DHCP, thus is ready to use within the network. Anyhow, for the first tests the actual usage of the network is not yet required. All following examples, if not stated else, rely on the provided configuration file "arm-test.ctys" and the QEMU VM "arm-test". These have to be installed as described within the examples chapter for qemuInstall.

The first call now creates a session and starts the VM with VNC as a console which will be attached automatically.

  ctys -t qemu -a create=p:$HOME/qemu/tst/arm-test/arm-test.ctys,reuse,console:vnc lab00

When the vde_switch is not configured yet the following error message occurs:

  Missing management socket for "vde_switch" 
  Call: "ctys-setupVDE" on "lab00.soho"

The solution is simply to proceed as requested and just create the UNIX Domain sockets by the following call with root permissions:

  ctys-steupVDE -u $USER create

The call could be executed remote too:

  ctys-steupVDE -u $USER create root@lab00

The setup should be operational now. The support of the types of CONSOLEs depends on the actually implemented call within the "arm-tst.ctys" script, which is a shell script with a defined interface. The currently supported CONSOLE types by arm-test are: "CLI, SDL, VNC". The CLI and SDL types are supported as DISPLAYFORWARDING in synchronous mode only for this version.

The following call creates an SDL CONSOLE.

  ctys -t qemu -a create=p:$HOME/qemu/tst/arm-test/arm-test.ctys,reuse,console:sdl lab00

As might be expected, the following call creates a CLI CONSOLE.

  ctys -t qemu -a create=p:$HOME/qemu/tst/arm-test/arm-test.ctys,reuse,console:cli lab00

The monitor as configured within could be attache by usage of "netcat"


which could be generated by the function "netGetUNIXDomainSocket" and is derived from "QEMUMONSOCK" as raw-pattern, for additional information refer to the "arm-text.ctys" inline comments.

The QEMU monitor now could be entered by typing 'Ctrl-a'+'c'+'<RET>', the console is recovered by typing the same sequence again. For additional information refer to the QEMU User-Manual. A second terminal emulation to be used is the 'unixterm' command of VDE.

Alternatively EMACS could be used as a terminal emulation for CONSOLE access, either in "shell-mode" or in "ansi-term" mode. This work s the same way as an ordinary xterm session, where within the the "display-window" a cli is started connecting to a local UNIX domain socket. The socket has to be configured as a serial device within the GuestOS. For EMACS two additional variants exist for both modes, where the frame is divided into two windows, which connects the <execution-target> and the <machine-address> representing the GuestOS.

In the following example in the upper window a login-prompt of the GuestOS is displayed, whereas in the bottom window the "top" comman is shown for the hosting machine.


The console with pure CLI access could be combined with an VNC console allowing additional graphical access. This is particularly forseen, and will be offered soon, same as a debugging facility for GDB access to QEMU and to applications within the GuestOS.


CANCEL a session

The following call CANCELs the arm-test session.

  ctys -t qemu -a cancel=p:$HOME/qemu/tst/arm-test/arm-test.ctys,force,poweroff:0 lab00

LIST sessions

The following call LISTs all sessions:

  ctys -a list lab00

resulting to:

  TCP-container|TCP-guest  |label   |sesstype|c|user|group     
  lab00.soho   |-          |arm-test|VNC     |C|acue|ldapusers 
  lab00.soho   |-          |LAB00   |VNC     |C|root|root      
  lab00.soho   |-          |LAB00   |VNC     |S|root|root      
  lab00.soho   |tst109     |arm-test|QEMU-arm|S|acue|ldapusers 
  lab00.soho   |-          |Domain-0|XEN     |S|-   |-         
  lab00.soho   |lab00.soho.|lab00   |PM      |S|-   |-         

The following call LISTs all sessions by usage of a specific LIST-MACRO for QEMU:

  ctys macro:listconnpid lab00

Resulting in:

  label   |stype   |c|DIS|cport|sport|pid  |PM        |TCP            
  LAB00   |VNC     |C|1  |     |     |18933|lab00.soho|               
  LAB00   |VNC     |S|1  |5901 |     |5642 |lab00.soho|               
  arm-test|QEMU-arm|S|17 |     |25704|25832|lab00.soho|               
  Domain-0|XEN     |S|   |     |     |     |lab00.soho|               
  lab00   |PM      |S|   |     |     |1    |lab00.soho|   

ENUMERATE sessions

The following call ENUMERATEs all stored session configurations within the subdirectory of the HOME.

  ctys -t qemu -a enumerate=b:qemu/tst lab00

The following call displays a listing formatted as a table:

  ctys -t qemu macro:listconn lab00


The following call SHOWs dynamic data.

  ctys -t qemu -a show lab00


Particularly the available capabilities for QEMU are displayed, which contains a list of all available CPUs and the related system boards.

  ctys -t qemu -a info lab00

This leads to:

  Node:lab00.soho  -  ctys(01_04_001A03)
     System      :Linux
     OS          :Linux
     RELEASE     :2.6.18-8.1.15.el5.centos.plusxen
     MACHINE     :x86_64
           vendor_id           :GenuineIntel
           cpu family          :6
           model               :22
           model name          :Intel(R) Celeron(R) CPU 420  @ 1.60GHz
           stepping            :1
           cpu MHz             :1599.853
           cache size          :512 KB
        Flags assumed equal for all processors on same machine:
              vmx(VT-x - Pacifica)    = 0
              svm(AMD-V - Vanderpool) = 0
              PAE                     = 1
        MemTotal               :   523 M
        SwapTotal              :  2031 M
           bash        :GNU bash, version 3.1.17(1)-release 
           gawk        :GNU Awk 3.1.5
           sed         :GNU sed version 4.1.5
           SSH         :OpenSSH_4.3p2, OpenSSL 0.9.8b 04 May 2006
           top         :top: procps version 3.2.7
           wmctrl      :wmctrl is on this machine not available
           lm_sensors  :sensors version 2.10.0 with libsensors version 
           hddtemp     :hddtemp version 0.3-beta13
        QEMU:        Plugin Version:01.01.001a00pre
                     Operational State:ENABLED
                     QEMU version:
                        Verified Prerequisites:

        CLI:         Plugin Version:01.01.001a02
                     Operational State:DISABLED
        X11:         Plugin Version01.01.001a02
                     Operational State:DISABLED
        VNC:         Plugin Version:01.02.001b01
                     Operational State:DISABLED

QEMU Examples


After installation of QEMU and VDE as described the utility ctys-plugins should be called for validation of the operational state of the QEMU installation. The following call verifies the different plugins operational states for server functionality.

  ctys-plugins -T all -e

The client functionality could be verified with the call:

  ctys-plugins -T all

Now, with a properly installed test environment from QEMU and the additional ctys call-scripts setup as described before, the following call should start the arm-test QEMU VM with and CONSOLE of type SDL.

  ctys -t qemu -a create=f:qemu/tst/arm-test/arm-test.ctys,console:sdl lab00

In case of ambiguous filenames in the cacheDB e.g. due to multiple access paths on multiple nodes by NFS the following approaches could be applied

use "p:<pathname>"
When the full absolute path by p:<pathname> is provided, no local ambiguity may occur within the execution context. This is recommended for the first steps, because it does not require any additional action.

extend number of params from <machine-address>:
Additional entries may lead to non-ambiguity. This depends on the contents of the distributed caches and requires some knowledge of the system.

deactivate cacheDB:
Another quick solution is the disabling of any caching, therefore the options -c off and -C off could be set. This leads to a filesystem scan, which of course results in some performance degradation, which could be serious in case of deep filestructures with a "late match". The scan is performed by usage of the system utility find.

The supported CONSOLE types for the from-the-box "arm-test" VM are CLI, SDL, and VNC. Additional information is available as inline comment within the "arm-test.ctys" configuration from the


directory. After this call an SDL terminal window should be opened. In case of networking problems the most common error is the forgotten call of ctys-setupVDE -u <USER> create.


  ctys -t qemu -a create=f:/qemu/tst/coldfire-test-0.1/coldfire.ctys,console:cli lab00


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

For GuestOS Setups:

ctys-uc-Android(7) , ctys-uc-CentOS(7) , ctys-uc-MeeGo(7)


For KVM:

For HOWTOs on Serial-Console refer to:



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.