June, 2010



ctys-setupVDE - manages on-the-fly network configuration



   [-b <virtual-bridge>]
   [-d <level>]
   [-g <sbit-group>*]
   [-H <help-options>]
   [-i <interface>]
   [-l <remote-user>]
   [-r <remote-hosts>]
   [-u <non-privileged-user>[.<group>]]
   [-Z <set-sudo-ksu>]


ctys-setupVDE creates and manages the complete set of Network-Devices required for interconnection by KVM and QEMU. The creation and deletion is performed by just one call. Therefore ctys-setupVDE encapsulates and combines the subbset of functionality of required tools supporting the TAP/TUN devices by VDE ( Virtual Switches) .

QEMU/KVM-Network Interconnection

The utility could be performed locally or remotely by full support of remote ctys-addressing, including context specific target-options, MACROS and GROUPS. E.g. the required system permissions could be preconfigured for specific users by "ksu" and/or "sudo", for additional information refer to 'VDE Remote Configuration'.

QEMU/KVM-Network Interconnection - Components

A specific behaviour of the current version is applied to the created main-bridges. These will get the same IP and MAC addresses as the logical interface, anyhow it works perfectly, as long as you can cope with multiple interfaces with same address information within applied tools. For the functionality of the UnifiedSessionsManager this is handled by a "sort -u" on resulting enumeration IF-lists. The current debian setup works the same way, where even the name of the first interface is reused as the name of the created bridge.

One reason for "doing" the bridge allocation this way within the UnifiedSessionsManager is the minimized risk of detaching the remotely handeled VMs for too long from the network services, which might make them unusable from than on. This aspect has to be emphasized due to the intention of frequent on-the-fly creation of networking devices. This naming and address-assignment concept will probably be modified slightly in future versions. Anyhow, the remote usage of "ctys-setupVDE", once the authentication is configured properly and security facilities are setup thoroughly, offers a simple interface for centralized setup of VM stacks ( Nested Networking-Stack with Xen+QEMU) . This is particuarly true in combination of remote usage of GENMCONF and PLUGINS.

The usage of ctys-setupVDE assures the appropriate environment for the used of the wrappers "vdeq" and "vdeqemu" of the package VDE-SOURCEFORGE, which is the recommended tool when TAPTUNbyVDE has to be created. This utility could be used in any comparable case too, but fit particularly for QEMU setup.

The configuration files if QEMU are shared here, thus the consistency of QEMUSOCK is ssured. The variable QEMUSOCK is based on the variable CTYS_SOCKBASE, which is the default base directory, where UNIX domain sockets are created. This should be used for eventual additional UNIX domain sockets, such as tcp based serial ports or monitoring devices, too. For additional applicability refer to the user manual of QEMU and to the templates provided by UnifiedSessionsManager.

The following tools are combined within this script:

QEMU/KVM-Network Interconnection - Details

Two types of virtual bridges/switches( see figure:NestedProtocolStacks StackedNetworking) are managed by ctys-setupVDE.

TAPTUNbyVDE prepares a TAP device with a attached new bridge, therefore it requires the VirtualDistributedEthernet - sourceforgeVde package. Additional information within a WiKi containing some helpful tutorials for virtualsquare-basicnet working could be found at the website of VirtualSquare.

In current implementation some assumptions are made in order to ease design and implementation. Anyhow, for practical application these constraints might not be an important matter.


The default bridge used is the first found in alphabetical order. For some default installations this might not be the intended. When DHCP is used the first to check in case of errors is the actual used bridge. The bridge to be used could be forced by the -b option.

The following steps are performed by ctys-setupVDE:

  1. Creation of a TAP device.
      "vde_tunctl -u <user-without-root-permission>"
      vde_tunctl -u acue
    Returns a line like:

    Set 'tap3' persistent and owned by uid 4711

  2. Use the returned 'tapX' for networking.
      ifconfig $1 up
      brctl addif $2 $1
    Does the same as:
      /etc/xen/qemu-ifup tap3 xenbr0

    Which brings up the newly created interface 'tap3' and adds an interface to the virtual Xen bridge connecting it to the world outside.

    The results could be verified with:
  3. Connect the device.

    Now this interface will be connected to another virtual switch, the vde_switch in order to provide an internal multiplexer for multiple QEMU instances to be connected to the external interfaces e.g. via a present Xen-bridge.

      vde_switch -d \
                 -tap tap3 \
                 -s ${QEMUSOCK} \
                 -M ${QEMUMGMT}
      chown -R <userX.groupX> ${QEMUSOCK}
      chown -R <userX.groupX> ${QEMUMGMT}

    The state could be veriefied with:
      unixterm ${QEMUMGMT}

    For additional information refer to examples of the manual.




-b <virtual-bridge>

The virtual bridge connected to the external network to be attached by TAP device. Default is to use the first bridge detected by brctl. If none is present, tha by default a new one is created with the name "ctysbr0", and the first found interface is added to the bridge.

When an interface is provided by "-i" option and a new bridge has to be created, this will be used instead of the first valid.

-d <level>

Sets debug.


Forces execution even when processing seems to be critical.

-g <sbit-group>

Sets the s-bit for the group, this has to be the same as the resulting owner's group.

If not set, the resulting permissions for QEMUSOCK are





Print help, refer to "-H" for additional information.

-H <help-option>

The extended help option is based on system interfaces for display of manpages, PDF and HTML documents. This comprises the man pages and installed manuals.

For additional help refer to the documents or type ctys -H help.

-i <interface>

The interface to be added to a newly created bridge, see "-b" option.

-l <remote-user>

Refer to "ctys" generic options for additional information.

-r <remote-hosts>

List of remote hosts for execution. Either a list of valid hostnames, ipaddresses, or EMail-Format hostnames.


A file-socket to be used for communications peer via virtual switch. Default is set by common QEMUSOCK configuration.


A file-socket to be used for management console of virtual switch. Default is set by common QEMUMGMT configuration.

Could be used with "unixterm $QEMUMGMT" of VDE.

-u <non-privileged-user>[.<group>]

Owner of the created TAP device. Default is current user.




See ctys, terse for machine output.


See ctys.





0: OK:
Result is valid.

1: NOK:
Erroneous parameters.

2: NOK:
Missing an environment element like files or databases.


ctys use-cases

ctys plugins
ctys-CLI(1), ctys-PM(7), ctys-VNC(7), ctys-X11(7)

ctys executables
ctys-distribute(1), ctys-extractARPlst(1), ctys-extractMAClst(1), ctys-genmconf(1), ctys-vping(1), ctys-plugins(1), ctys-vhost(1), ctys-wakeup(1)

system executables
vde_tunctl, vde_switch, unixterm, ifcfonfig(8), brctl(8), ether-tool(8), nc(1)<a.k.a. netcat>


Written and maintained by Arno-Can Uestuensoez:

Maintenance: <<acue_sf1 (a) users 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, 2011 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.