June, 2010



ctys-PM - Physical Machine Interface



In addition to the provided examples additional man pages for specific use-cases are available. The most important are ctys-WOL(7) and ctys-IPMI(7).


Due to the amount of required system tools and access permissions the utility ctys-plugins is introduced, which displays detailed reports for availability and required access permissions.

Configuration of Access Permissions

The plugin PM relays on a number of system resources, where numerous require by default root permissions.

These resources are mainly required in connection with CANCEL of a machine and in case of WoL/IPMI for the startup of a machine by CREATE.

The CREATE action is splitted into two security cases:

For the packet distribution to the local segment the tool "ethtool" is used which requires root permissions on the interface to be used. For the remote distribution an own script is utilized, which does not require any specific permissions on the sending host, but some preparation on routers connecting the target segment.

The CANCEL action is only executed on the target machines, but requires on these several system facilities. The minimal requirement are the "shutdown-tools" on machines with non-bridged interfaces. On machines with bridged interfaces without an additional WoL interface some facilities for controlling the bridge from 'bridge-utils' are eventually required.

The following access permissions are needed for full functional scope of the current release of ctys. For standard machines without the neccessity of bridge shutdown for setting "wol g":

For machines with bridges required to be shutdown for setting "wol g", typically Xen-3.0.2, the following additional permissions have to be configured:

The permissions should be configured as described in the related chapters.

Due to the timeout behaviour of ksu and sudo during probing when no user is configured, the default behaviour is not to probe for theese tools.

Additional information is provided in the example for handling WoL.

CREATE a session


This will switch on a machine previously which is shutdown with WoL-Attribute. The execution host for ctys tasks is "lab01", so root permission as required has to be granted on "lab01" only.

RESUME is internally mapped to WoL, thus the same.

  ctys -t pm -a create=wol,t:hostX,broadcast:hostXDirectedCast lab01


This will create a new session to a running machine with any of the CONSOLEs: CLI, XTERM, GTERM, EMACS, or VNC.

  ctys -t pm -a create=CONSOLE:cli

CANCEL a session


This cancels anything running on top of the PM, but by default not the PM itself. Thus the whole VM stack running on top of the PM will be powered off by recursive stack handling.

  ctys -t pm -a cancel=l:tst100,POWEROFF:0 lab01

The suboption FORCE just calls the lowest VM hypervisors for immediate - non-stack - poweroff. Contained upper VMs might not be able to store cached data, thus could be in erroneous state after switching them off abruptly.

  ctys -t xen -a cancel=l:tst100,force,POWEROFF:0 lab01

The suboption WOL without a BROADCAST suboption sends a broadcast packet for WoL into local segment only. Therefore the first interface - which could be a bonding device - is used. When this has to be altered, the broadcast parameter has to be supplied.

  ctys -t xen -a cancel=l:tst100,POWEROFF,wol lab01

The same with a "directed-broadcast".

  ctys -t xen -a cancel=l:tst100,POWEROFF,wol,broadcast: lab01

Directed broadcast is preferred here, due to support of the native OpenBSD based routers, and the internal-only usage. This could be seen as "somewhat secure", because of fine-grained and rigorous filtering rules in addition.


This call REBOOTs all VMs running on top of PM, but not the PM itself. In addition a LABEL is supported, which just names the current session for display purposes.

Therefore an appropriate stack-propagation is performed.

  ctys -t pm -a cancel=l:tst001,REBOOT lab01

The following call reboots in addition the PM itself.

  ctys -t pm -a cancel=l:tst001,REBOOT,SELF lab01

This call just reboots the PM, NO STACK-PROPAGATION is performed, thus OSs within upper VMs might be corrupted, at least require some kind of recovery mechanisms.

  ctys -t xen -a cancel=l:tst100,REBOOT,FORCE lab01


Current version just remaps this to a POWEROFF, therefore the user has to support the only supported Wake-Up mechanism WoL, refer to POWEROFF with WoL.


INIT is a transparently mapped action, which is almost the same as a native init-call. The difference is the call-relocation to the execution-target machine only.

Therefore the caller is responsible for the match of the requested init level with additional attributes, e.g. a WoL entry might not make too much sense, when called with "init 3".

  ctys -t PM -a cancel=l:tst100,INIT:0 lab01

PM - Using Wake-On-Lan - WoL a session

The WoL feature is described in detail within the document ctys-uc-WoL(7).

PM - Using Intelligent Platform Management Interface - IPMI

The WoL feature is described in detail within the document ctys-uc-IPMI(7).


ctys(1), ctys-uc-WoL(7), ctys-uc-IPMI(7), ctys-genmconf(1), ctys-plugins(1), ctys-vhost(1), ctys-wakeup(1), dmidecode(8), ether-tool(8), ether-wake(8), nc(1)<a.k.a. netcat>


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.