.
ctys - Commutate To Your Session
[-t <session-type>] [-a <action>] [<generic options>] [--] <arguments>
The utility ctys is the core interface to be used within the UnifiedSessionsManager.
ctys encapsulates the user interfaces of the whole set of supported hypervisors and
native sessions into a common syntax with a single call interface.
The installation and configuration is descibed within the HowTo manual and the specific
configuration guides.
The basic installation should work almost from the box, once the prerequisites are present.
The most valuable tool for verifying the setup of ctys is ctys-plugins which performs
a validation of local and remote installations and displays a detailed report.
The majority of the preset default values could be changed by configuration files
and environment variables.
The configuration files are installed by default within $HOME/.ctys directory tree.
The most important aspect for the introduction of a common interface is the unique namenbinding for addressing the user sessions to physical machines, supported hypervisors and guest OSs. The session in this case is defined as a representation of the lifetime for the active state of the runtime entity.
Each session could span multiple logins from multiple users, dependent from the individual setup. Thus the namebinding of the sessions and their related attributes becomes the most important feature for the management of the distributed user environments.
The specific actions required for the evaluation of the sessions namebinding are distinguished by their types:
Two basic access-approaches are provided for VMs:
The scanning approach does not require additional preparation, just some basic setup like the root-directory to start. The caching approach requires the previous scan of a list of targets and the storage of their resulting inventory data into a so called local cacheDB (Address-Resolution) .
The supported core utilities are:
These provide particularly the dynamic network related data for caching and offer
an enhanced query interface.
The options are grouped into two sections:
These are options directly related to specific plugins. ACTIONS are suboptions to the -a option and are preset by the actual loaded plugin controlled by -t and -T options.
These are the options which are mostly generic within the whole set of utilities.
They influence the ACTIONS, but are related to the runtime environment.
.
.
ctys supports the following actions:
CANCEL=(<machine-address>){1}|ALL
(
[FORCE|STACK][,]
[SELF][,]
[
RESET
|REBOOT
|(INIT:<init-state>)
|(PAUSE|S3)
|(SUSPEND|S4)
|((POWEROFF|S5)[:<timeoutBeforeKillVM>]
][,]
[(CLIENT|SERVER|BOTH)][,]
[TIMEOUT:<timeout-value>]
[,USER:<user>[%[(<credentials>|-)][%<domain>]]]
)
CANCEL terminates running sessions of present plugins.
This includes HOSTs, VMs, and PMs.
Thus beneath the handling of virtual and login sessions the management of physical machines is included.
The CANCEL method includes therefore the handling of state dependencies in a hierarchical manner too.
This is e.g. when a physical machine is going to be canceled - shutdown, than the contained remaining
sessions are going to be canceled too.
Therefore a vertical dependency is defined, which recognizes and handles the nested execution of
contained sub-sessions too.
CANCEL works by default asynchronously, thus is usable in parallel for emergency shutdowns by typing quickly a short syntax.
CREATE=<machine-address>{1}
[
CONNECT
|REUSE
|RECONNECT
|RESUME
][,]
[USER:<user>[%[(<credentials>|-)][%<domain>]]][,]
[CONSOLE:<console-type>][,]
[BOOTMODE:<boot-mode>[%<boot-img-pathname>]][,]
[(CHDIR|CD):<working-directory-change-to>][,]
[INSTMODE:
<boot-mode>%<inst-boot-source>%<insttargetmode>%<insttarget>%<inststage>]
[,]
[PING:(OFF|<#repetition>%<sleep>)][,]
[SSHPING:(OFF|<#repetition>%<sleep>)][,]
[STACKCHECK:<stack-check>][,]
[(STUBMODE|STUB)[:ON]][,]
[(VNCDESKIDLIST|VDIL):<list-of-custom-ids>][,]
[WAITC:<timer>][,]
[WAITS:<timer>][,]
[<callopts>][,]
[<xopts>]
The CREATE action starts local and remote sessions for supported plugins.
The desribed part within this document is the generic superset for all plugins,
where specific plugins may support less options than depicted here.
This is due to specific restrictions.
For example the CLI session may not require a configuration file due it's solely dynamic
nature.
In some exceptional cases the specific plugin may provide an additional attribute,
what should be avoided when ever possible.
The CREATE has to basic modes, the operational creation of session by starting an entity
and the initial creation of a session, which could be the installation of a VM.
Therefore the optional parameters BOOTMODE for variation of the default boot for CREATE of
a VM and the INSTMODE for the initial boot mode from a specific installation medium
are provided.
This is the case for the current version for some 'complete open source' solutions, where as
the more commercial products are for now foreseen to handle the installation of guest systems
with their own utilities.
The CREATE action is additionally supported by several utilities, for the virtual machines in particular
by the guest system installer and configurator
ctys-createConfVM(1)
.
This provides currently for some plugins the plug-and-play installation of virtual machines including
the guest system, while for some commercial products for now the creation of additional configuration
information is provided only.
This temporary restriction is due to the actual amount of proprietary interfaces to be adapted, which
is going to be provided.
The particular support for the CREATE session is given by persistently provided default values, which
omit long commandline strings and represent a distributed database for example for the mapping of
user defined strings as execution shortcuts.
The main advance of the common seamless syntax for CREATE ist the unique interface syntax for the start
of plugins with various frontends.
This particularly provides for the various application fields with either user desktops, or server
based backend setups.
Therefore following in addition to the various BOOTMODEs and INSTALLMODEs, the available CONSOLEs
are listed.
Another point to be mentioned here is the advanced addressing feature, which is the generic superset for
all provided pluging.
This so called <machine-address> provides particularly a common set of attributes to be used either in
combination or solely - when unambitious - is provided.
Again some attributes may be omitted case by case, but some in general.
So the UUID is not applicable by definition for a CLI session, which is just a remote login.
Whereas it might not be available in some cases only for a VM or a PM, e.g. due to access permissions.
The CREATE action also provides options, which are listed as generic options but may effect the frame of
the created session only.
These are particularly related to sharing and restarting of sessions as well as for their presentation
on graphical desktops.
These include sizes as well as screen and workspace position.
The following given sub-options are not order dependent, the keywords are case-insensitive. For call details refer to the specific package.
BOOTMODE:
(
KERNEL
|PXE
|FDD
|CD
|vHDD|HDD
|ISO
|INSTALL
)
The BOOTMODE parameter supports the alteration between pre-configured
boot setups, which is specific to the boot media and the applied hypervisors.
The usage of this parameters requires a wrapper script specific to
the UnifiedSessiosnManager or a specific configuration variant to be in place.
For additional information refer to the test-cases and pattern within the installed
directory tree in $HOME/ctys.
The following table lists the various support options for current base-plugins.
| Mode | KVM | OVZ | QEMU | VBOX | VMW | XEN |
|---|---|---|---|---|---|---|
| CD/DVD | OK | ffs | OK | (BIOS) | (BIOS) | OK |
| FDD | OK | ffs | OK | (BIOS) | (BIOS) | X |
| USB | OK | ffs | OK | (BIOS) | (BIOS) | X |
| ISO | OK | ffs | OK | (BIOS) | (BIOS) | OK |
| KERNEL | X | ffs | X | - | - | OK |
| PXE | OK | ffs | OK | (BIOS) | (BIOS) | OK |
| VHDD/HDD | OK | ffs | OK | OK | OK | OK |
| Supported Boot/Install-Modes |
|---|
| Mode | KVM | OVZ | QEMU | VBOX | VMW | XEN |
|---|---|---|---|---|---|---|
| CD | ffs | ffs | ffs | - | - | - |
| DVD | ffs | ffs | ffs | - | - | - |
| FDD | OK | ffs | OK | - | (BIOS) | ffs |
| ISO | ffs | ffs | ffs | - | - | - |
| USB | OK | ffs | OK | (BIOS) | (BIOS) | ffs |
| VHDD/HDD | OK | ffs | OK | (BIOS) | (BIOS) | OK |
| Supported Install-Targets |
|---|
| CONSOLE | CLI | KVM | OVZ | PM | QEMU | VBOX |
|---|---|---|---|---|---|---|
| CLI | X | X | ffs | X | X | ffs |
| EASYECLIPSE | ffs | ffs | ffs | ffs | ffs | ffs |
| ECLIPSE | ffs | ffs | ffs | ffs | ffs | ffs |
| EMACS | - | X | ffs | X | X | ffs |
| EMACSM | - | X | ffs | X | X | ffs |
| EMACSA | - | X | ffs | X | X | ffs |
| EMACSAM | - | X | ffs | X | X | ffs |
| FIREFOX | - | ffs | ffs | ffs | ffs | ffs |
| GTERM | - | X | ffs | X | X | ffs |
| NONE | - | X | ffs | X | X | X |
| RDP | - | - | ffs | - | - | X |
| SDL | - | X | ffs | - | X | X |
| VBOX | - | - | - | - | - | X |
| VNC | - | X | ffs | X | X | ffs |
| VMW | - | - | - | - | - | - |
| VMWRC | - | - | - | - | - | - |
| XTERM | . | X | ffs | X | X | ffs |
| Supported Console-Types - Table 1 of 2 |
|---|
| CONSOLE | VMW | VNC | X11 | XEN |
|---|---|---|---|---|
| CLI | - | - | - | X |
| EASYECLIPSE | ffs | ffs | ffs | ffs |
| ECLIPSE | ffs | ffs | ffs | ffs |
| EMACS | - | - | X | X |
| EMACSM | - | - | (X) | X |
| EMACSA | - | - | X | X |
| EMACSAM | - | - | X | X |
| FIREFOX | X | - | - | - |
| GTERM | - | - | X | X |
| NONE | (*) | X | - | X |
| RDP | - | - | - | (*) |
| SDL | - | - | - | (*) |
| VBOX | - | - | - | - |
| VNC | (X) | X | - | X |
| VMW | X | - | - | - |
| VMWRC | X | - | - | - |
| XTERM | - | . | X | X |
| Supported Console-Types - Table 2 of 2 |
|---|
STACKCHECK:
OFF
|
(
[(CONTEXT|NOCONTEXT)][%]
[(HWCAP|NOHWCAP)][%]
[(STACKCAP|NOSTACKCAP)]
)
for additional information refer to STACKCHECK-REF
and to STACKEDSESSIONS-REF.
ENUMERATE
[=
(
(
(
[ACCELERATOR|ACCEL][,]
[ARCH][,]
[CATEGORY|CAT][,]
[CONTEXTSTRING|CSTRG][,]
[CTYSRELEASE][,]
[DIST][,]
[DISTREL][,]
[EXECLOCATION][,]
[EXEPATH|EXEP][,]
[GATEWAY][,]
[HWCAP][,]
[HWREQ][,]
[HYPERREL|HYREL][,]
[HYPERRELRUN|HRELRUN|HRELX|HRX][,]
[IDS|ID][,]
[IFNAME|IF][,]
[LABEL|L][,]
[MAC|M][,]
[NETMASK][,]
[NETNAME][,]
[OS][,]
[OSREL][,]
[PLATFORM|PFORM][,]
[PM|HOST][,]
[PNAME|P][,]
[RELAY][,]
[RELOCCAP][,]
[SERIALNUMBER|SERNO][,]
[SERVERACCESS|SPORT|S][,]
[SSHPORT][,]
[STACKCAP|SCAP][,]
[STACKREQ|SREQ][,]
[STYPE|ST|TYPE][,]
[TCP|T][,]
[USERSTRING|USTRG][,]
[UUID|U][,]
[VCPU][,]
[VERSION|VERNO|VER][,]
[VMSTATE|VSTAT][,]
[VNCBASE][,]
[VNCDISPLAY|DISP][,]
[VNCPORT|CPORT][,]
[VRAM][,]
)
[TITLE|TITLEIDX|TITLEIDXASC][,]
[MACHINE|MAXKEY][,]
)
)
[
(REC_GEN|REC):<tab-args>
| (SPEC_GEN|SPEC):<tab-args>
| (TAB_GEN|TAB):<tab-args>
| (XML_GEN|XML):<tab-args>
]
[IP|DNS][,]
[,TERSE]
[,PKG:<pkglist>]
[,SORT[:[ALL|EACH][%UNIQUE][%<sort-key>]]]
[,(BASEPATH|BASE|B):<base-path>[%<base-path>]{0,n}]
[,MATCHVSTAT:<vstat-list>]
]
vstat-list:=<vstat-enum>[%<vstat-list>]
vstat-enum:=(
ACTIVE | DISABLED | BACKUP
| CUSTOM | TEMPLATE | TESTDUMMY
| EMPTY | PRESENT
| ALL | ENABLED
| IGNORE
)
ENUMERATE collects the stored static configuration data of all VMs.
Therefore the filesystem is scanned for all known types of configuration files with specific matching
filters.
These could be displayed in various formats and content-sets as selected by suboptions.
The display could be either formatted for human display, e.g. by table output,
or for machine processing in database conformant ASC-II formats.
The set of content is controlled by the provided constraints for specific attributes.
The enumeration is applied for local and remote sessions, where lists of start-directories for
filesystem scans could be individually defined.
The data is collected for each loaded plugin with stored configuration such as VMs and PMs, dynamic
plugins such as of type HOSTs have for now no individual static configuration data, thus are not
included in the enumeration.
These are displayed by the dynamic method LIST.
The enumeration includes beneath the filtering for specific VM attributes in addition the filtering
for some dynamic operational states.
This comprises additionally the actual availability of the hypervisor, which depends of the
present runtime configuration.
In case of Xen for example the appropriate kernel has to be running, or in case of QEMU on x86 the
KVM or KQEMU kernel modules define whether QEMU is used in emulation mode only, or as KVM with
kernel based acceleration.
The same for KQEMU.
The scan could be either proceeded for collection of the actually executable hypervisors on each node, or for the presence of any configuration of potentially executable stored VMs. In case of multiple installed hypervisors, which could be used e.g. by the boot with a different kernel, the latter has some advantages when a test environment is to be setup. Another application is to control the exclusion of templattes and backups, which may cause some ambiguity within the database else.
The scope of the scanned states is controlled by the vstat-enum with the commandline attribute by the suboption MATCHVSTAT, which controls the output dependent of the dynamic and/or static state. Currently the following enumeration attributes are defined.
The output is as listed in the following record description. Some exceptions occur, when multiple interfaces are configured within a VM. Each interface is assigned with each of it's IP address to a seperate output record, containing a single MAC address and a single assigned TCP address. Thus the number of output records is increased for multihomed VMs and PMs resulting in one entry for each interface address.
Some additional values are supported for basic management of VMs by simply adding masked keywords to present configuration files and/or directories. When "-X" option is set, the output is prepared as ";" semicolon seperated list for post-processing. The same is true, when setting TERSE. The MACHINE keyword for full data set as a canonical record implies TERSE.
| Processing-Key | Short Description |
|---|---|
| ALL | Sets the output to a superset of valid fields. |
| DNS | Transforms TCP addresses to numeric format. |
| IP | Transforms TCP addresses to numeric format. |
| MACHINE | Sets the output to the canonical full-set. |
| VSTAT | Alters the VMSTATE attribute, to be semantically matched. |
| MAXKEY | Sets the output to common subset. |
| PKG:<pkg-list> | Constrains on output to defined list. |
| REC_GEN | Activates proprietary record filter. |
| SORT | Activates sort filter. |
| SPEC_GEN | Activates record filter for visual checks. |
| TAB_GEN | Activates table filter. |
| TERSE | Output for post processing. |
| TITLE | Output of field names. |
| TITLEIDX | Output of field names with indexes. |
| TITLEIDXASC | Field names with additional spreadsheet column-refs. |
| XML_GEN | Activates XML record export filter. |
| Processing Suboptions |
|---|
The following table depicts the complete set of fields for current data record.
| Nr | FieldKey | Fieldname | Common |
|---|---|---|---|
| 1 | PM or HOST | ContainingMachine | X |
| 2 | TYPE | SessionType | X |
| 3 | LABEL or L | Label | X |
| 4 | ID | ID | X |
| 5 | UUID | UUID | X |
| 6 | MAC | MAC | X |
| 7 | TCP | TCP | X |
| 8 | DISPLAY | DISPLAY | - |
| 9 | CPORT | ClientAccessPort | - |
| 10 | SPORT | ServerAccessPort | - |
| 11 | VNCBASE | VncBasePort | - |
| 12 | DIST | Guest-Distro | - |
| 13 | DISTREL | The release of the distribution. | - |
| 14 | OS | Guest-OS | - |
| 15 | OSREL | OS-Release | - |
| 16 | VERNO | VM-Config version number | - |
| 17 | SERNO | VM-SerialNo | - |
| 18 | CATEGORY | Category | - |
| 19 | VMSTATE | The state of the VM | X |
| 20 | HYPERREL | Hypervisor used for installing the VM. | X |
| 21 | STACKCAP | The capabilites supported. | - |
| 22 | STACKREQ | The list of capabilites required. | - |
| 23 | HWCAP | Offered virtual HW. | - |
| 24 | HWREQ | Required HW, either virtual or physical. | - |
| 25 | EXECLOCATION | Defines the possible execution locations. | - |
| 26 | RELOCCAP | Defines LOCATION behaviour. | - |
| 27 | SSHPORT | Alternative port for p option of SSH. | - |
| 28 | NETNAME | DNS name of current interface. | - |
| 29 | HYPERRELRUN | Release of present hypervisor. | - |
| 30 | ACCELERATOR | Present accelerator. | - |
| 31 | EXEPATH | Pathname for execution frontend. | - |
| 32 | RESERVED10 | For future use. | - |
| 33 | IFNAME | Interface within the GuestOS. | - |
| 34 | CTYSRELEASE | MAGICID of the originator for each record. | - |
| 35 | NETMASK | Internet NETMASK. | - |
| 36 | GATEWAY | Internet Gateway. | - |
| 37 | RELAY | The interconnection interface. | - |
| 38 | ARCH | Architecture presented to the GuetsOS. | - |
| 39 | PLATFORM | Virtual device. | - |
| 40 | VRAM | The pre-configured amount of RAM. | - |
| 41 | VCPU | The pre-configured number of V-CPUs. | - |
| 42 | CONTEXTSTRG | A private context storage for the plugin | - |
| 43 | USERSTRING | A string to be customized by the user. | - |
| Output Record-Format for MACHINE suboption |
|---|
Returns the port for attaching the front end client services to the server component.
GETCLIENTPORT=<label>|<id>{1}
This will be used internally only, or within plugins and macros. Security is based on SSH for ctys execution and the appropriate options of the current VM for restricting to local access only.
The output is presented as follows:
"CLIENTPORT(<type,<FQDN-host>,<vm-label>)=<client-access-port>"
Which could be for example:
"CLIENTPORT(VMW,host01.fantasy,linuxBox)=904"
Displays miscellaneous static information for the given hosts. This action is under development and is planned to be extended. Currently some OS and Machine information is displayed. Particularly the present HW-Virtualization registers of CPUs the are shown. For now the Display is given as:
bash-3.1$ ctys -a info -W delphi ############################# Node:delphi.soho System :Linux OS :GNU/Linux RELEASE :2.6.21.6-delphi-005 MACHINE :i686 KERNEL#CPU :SMP-KERNEL CPU-INFO processor:0 vendor_id :GenuineIntel cpu family :6 model :11 model name :Intel(R) Pentium(R) III CPU ... stepping :4 cpu MHz :1266.131 cache size :512 KB processor:1 vendor_id :GenuineIntel cpu family :6 model :11 model name :Intel(R) Pentium(R) III CPU ... stepping :4 cpu MHz :1266.131 cache size :512 KB Flags assumed equal for all processors on same machine: flags vmx(VT-x - Pacifica) = 0 svm(AMD-V - Vanderpool) = 0 PAE = 1 MEM-INFO MemTotal : 4018 G SwapTotal : 24579 G VNC :VNC Viewer Free Edition 4.1.2 for X - ... wmctrl :wmctrl is on this machine not available ------------ ctys: :01_02_003a10 Plugings: : VNC
LIST[=
(
(
(
[ACCELERATOR|ACCEL][,]
[ARCH][,]
[CONTEXTSTRG|CSTRG][,]
[CPORT][,]
[DISPLAY][,]
[EXECPATH|EXEP][,]
[GROUP|GID][,]
[HYPERRELRUN|HRELRUN|HRELX|HRX][,]
[ID|PATHNAME|PNAME|P][,]
[IFNAME|IF][,]
[JOBID|JID][,]
[LABEL][,]
[MAC][,]
[PID][,]
[PM|HOST][,]
[PNAME|P]
[SITE][,]
[SPORT][,]
[TCP][,]
[TUNNEL | (CLIENTS|C) | (SERVER|S) | (BOTH|B)][,]
[TYPE|ST|STYPE][,]
[USER|UID][,]
[UUID][,]
)
[TITLE|TITLEIDX|TITLEIDXASC][,]
[MACHINE|MAXKEY][,]
)
)
[
(REC_GEN|REC):<tab-args>
| (SPEC_GEN|SPEC):<tab-args>
| (TAB_GEN|TAB):<tab-args>
| (XML_GEN|XML):<tab-args>
][,]
[IP|DNS][,]
[,SORT[:[ALL|EACH][%UNIQUE][%<sort-key>]]][,]
[PKG:<pkg-list>][,]
[TERSE][,]
[USER:<user>[%[(<credentials>|-)][%<domain>]]][,]
]
LIST disyplays the realtime runtime data related to actually running local and remote sessions.
Therefore the LIST action is a dynamic method in difference to the ENUMERATE action displaying
static data.
Even though the LIST action is focussing on dynamic data some additional static data is required for
mapping purposes and completion of the human readable information.
Therefore the dynamic runtime information of the plugins may contain at least some identifiers in order
to access the persistently stored data within the configuration files.
Also some dynamic data related to the control of jobs and their forked and parallel executed background subjobs
is stored in semi-persistend caches.
This is particularly required for some nested distribution of subjobs.
All loaded types are listed by filtering according to provided suboptions.
The base set to be filtered is defined by the options "-t"
and/or "-T". If "-t" is not present, the default "-t ALL" will
be applied to all pre loaded plugins.
For changing the selection scope of listed users refer to "-s" option.
The LIST action is deeply influenced by the setting of the option "-b"
concerning the performance, and the option "-C" concerning the way the output data is displayed.
The basic influence on the display is described in "Parallel And Background Operations"
the perfomance repercussion is presented in "Performance Measures".
LIST supports various display modes, where the displayed
subset of fields could be configured by switching on with
the assigned keyword.
| Field-Name | Content |
|---|---|
| TCP-Container | PM |
| TCP-guest | (MAC|TCP|DNS) |
| Label | <label> |
| ID | <ids>|<id> |
| Sesstype | (PM|CLI|X11|VNC|VMW|XEN|QEMU) |
| C | (C|S) |
| User | $USER |
| Group | <group> |
"TAB_TCP:7%%6%%3%%"This defines the following sizes:
| Field-Name(index) | Size | Default |
|---|---|---|
| TCP-Container(1) | 7 | 17 |
| TCP-guest(7) | default | 17 |
| Label(3) | 6 | 20 |
| Sesstype(2) | default | 8 |
| C(14) | 3 | 1 |
| User(12) | default | 10 |
| Group(13) | default | 10 |
TAB_GEN:<idx>_<colname>_<width>[%<idx>_<colname>_<width>]{0,n}
The underscore "_" is here reserved as field
seperator, thus could not be used within regular values.
Enclosed empty fields are not allowed.
For each column the triple of data is required:
| Nr. | Field-Key | Fieldname | Common |
|---|---|---|---|
| 1 | PM-HOST-H | ContainingMachine | X |
| 2 | TYPE | SessionType | X |
| 3 | LABEL-L | Label | X |
| 4 | ID-I-PNAME-P | ID | X |
| 5 | UUID | UUID | X |
| 6 | MAC | MAC | X |
| 7 | TCP-T | TCP | X |
| 8 | DISPLAY | DISPLAY | - |
| 9 | CPORT | ClientAccessPort | - |
| 10 | SPORT | ServerAccessPort | - |
| ffs | VNCBASE | VncBasePort | - |
| 11 | PID | PID | - |
| 12 | UID | UID | - |
| 13 | GID | GID | - |
| 14 | CSTYPE | C/S-Type | - |
| 15 | JOBID | JobID | - |
| 16 | IFNAME | IFNAME | - |
| 17 | RESERVED | RESERVED1 | - |
| 18 | CONTEXTSTRG | CONTEXTSTRG | - |
| 19 | EXECPATH | EXECPATH | - |
| 20 | HYPERRELRUN | HYPERRELRUN | - |
| 21 | ACCELERATOR | ACCELERATOR | - |
| 22 | ARCH | ARCH | - |
| Output-Format for MACHINE suboption |
|---|
| Processing-Key | Short Description |
|---|---|
| DNS | Transforms TCP addresses to numeric format. |
| IP | Transforms TCP addresses to numeric format. |
| MACHINE | Sets output to canonical format. |
| MAXKEY | Sets output to common subset. |
| PKG:<pkg-list> | Constrains on output to defined list. |
| SORT:[:<sort-args>] | Activates sort filter |
| TAB_GEN:<tab-args> | Activate table filter |
| TERSE | Output for post processing. |
| TITLE | Output of field names. |
| TITLEIDX | Output of field names with indexes. |
| TITLEIDXASC | Output of canonical idx numbers. |
| Processing suboptions |
|---|
Displays dynamic information for the given hosts. For now the Display is given as:
bash-3.1\$ ctys -a show -W delphi ############################# Node:delphi.soho System :Linux OS :GNU/Linux RELEASE :2.6.21.6-delphi-005 MACHINE :i686 MEM-INFO MemTotal : 4018 G MemFree : 96 G SwapTotal : 24579 G SwapFree : 24579 G Top : iterations=10 top - 10:25:33 up 1 day, 12:39, 1 user, load aver... Tasks: 241 total, 1 running, 240 sleeping, 0 st... Cpu(s): 0.4%us, 0.4%sy, 0.0%ni, 98.6%id, 0.5%wa... Mem: 4018724k total, 3922936k used, 95788k fr... Swap: 24579420k total, 4k used, 24579416k fr... PID USER PR NI VIRT RES SHR S %CPU %MEM ... 28241 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28246 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28247 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28248 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28249 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28250 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28251 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28252 vadmin 5 -10 388m 308m 296m S 0 7.9 ... 28253 vadmin 15 0 388m 308m 296m S 0 7.9 ... 28230 vadmin 15 0 99216 32m 16m S 0 0.8 ... 3640 root 15 0 41332 27m 3596 S 0 0.7 ... 23299 acue 15 0 45984 24m 14m S 0 0.6 ... 20011 root 15 0 42340 22m 13m S 0 0.6 ... 23147 acue 15 0 31344 22m 4448 S 0 0.6 ... 19842 root 15 0 27016 20m 4220 S 0 0.5 ... 29259 root 18 0 43420 19m 12m S 0 0.5 ... 23249 acue 15 0 113m 16m 11m S 0 0.4 ... 2939 root 15 0 21188 16m 4836 S 0 0.4 ... 19945 root 18 0 109m 15m 11m S 0 0.4 ... 23247 acue 15 0 77020 14m 9656 S 0 0.4 ... 23264 acue 16 0 85696 13m 9.8m S 0 0.3 ... 23280 acue 15 0 85696 13m 9.8m S 0 0.3 ... HEALTH Total ALARMs=0
Allow ambiguity, this has several effects on values which may or may not be allowed to be ambiguous.
<ambiguity-mode>=<0|off|1|on>
Allow ambiguity(-A 1) or disallow(-A 0:default).
Background and/or parallel execution. This option combines the control of detachment from console and the job distribution to multiple targets.
<background-mode>=
-b
stack
|
(
(sync|off|0)|(async|on|1)
[,
(sequential|seq|2)
|(parallel|par|3)
]
)
In addition this option controls the execution of VM-Stacks, which are closely coupled to GROUPS as well as to the background mode, refer to "Stacks As Vertical Subgroups".
<args>=(
ON
[,(BOTH|LOCAL|REMOTE)]
[,ONLY]
)
|OFF
The operations of ctys utilize special virtual-nameservice information which optionally could be read from the inventory database. Either from the local host, or the remote hosts allocated local database. This option controls the usage and selection of the location of these distributed caches at the local and/or remote site.
| Distributed Caches |
|---|
Even though the considerable gain of performance by usage of cached data could be abandoned, the availability of the cache facility is mandatory required for the utilisation of stacked VMs. This is due to required information of the contained environment, which is the runtime environment of the nested VM.
The UnifiedSessionsManager itself is designed as a distributed client-server system operating itself by distributing it's tasks to the managed entities, and propagation of the required states within the vertical stack-dependencies. For this tasks at almost each point of operations ctys requires access data for it's managed objects.
Therefore the UnifiedSessionsManager supports a distributed cache model consisting of multiple cache databases - cacheDBs - which has to be in sync if present, atleast might not contain inconsistent data. Partly present data will be handeled by match-priority. Alternatively the filesystem is scanned for available configuration files of VMs, once the execution target is entered.
The following flags are supported in order of control for the selection of the nameservice-caches to be used, or ignored. The default behaviour is to use "BOTH" caches optionally, and to scan the filesystem on the execution target if no cache-hit occurs. For additional information refer to Section "Distributed Nameservice and CacheDB"
<args>=(
ON
[,KEEP]
[,ONLY]
[,RAW]
[,(FIN|FOUT):<cache-filepath>]
[,LIFETIME:<seconds>]
[,AUTO]
)
|OFF
For ctys two basic types of data-caches are used. The first one is the plugin specific in-mem cache, where frequent operations like "ps" for LABEL mapping will be cached for the lifetime of a process. The second is the cacheDB on-disk cacheing, which could span multiple calls to a specific executable.
The in-mem caching is active by default, because the assumption is made that the systems state might not alter relevant to ctys within a call-cycle. This could be deactivated for the common plugins by with the "OFF" option, which additionally.
The on-disk caching is used for two specific reasons.
<debug-args>=
<debug-bit-array>[,(PATTERN|P)|MIN|MAX]
[,(SUBSYSTEM|S):<subsystem-bit-array>]
[,(WARNING|W):[0-9]]
[,(INFO|I):[0-9]]
[,(FILELIST|F):<file-list>[,(EXCLUDE|INCLUDE)]]
[,(PRINTFINAL|PFIN)[:[0-9]]]
<debug-bit-array>=
2#(0|1){1,32}|[0-9]*|<any-bash-format-32bit>
<subsystem-bit-array>=
2#(0|1){1,32}|[0-9]*|<any-bash-format-32-bit>
<file-list>=
<file>[%<file-list>]
DEFAULT:
-d <#integer>
is equal to:
-d <#integer>,MAX,WARNING:1,INFO:1
Sets the level and range of debug output.
<debug-bit-array>=2#(0|1){1,32}|[0-9]*|<any-bash-format-32bit>
<subsystem-bit-array>=2#(0|1){1,32}|[0-9]*|<any-bash-format-32-bit>
The following variables are predefined to be used for subsystems.
<file-list>=<file>[%<file-list>]
This option controls the output of local display.
The values are mapped to the DISPLAY variable, but due to security
resons for localhost only.
Thus this is practically applicable to the display target VNC and
physical multi-monitor configurations only.
VMs are from the point of view for TCP/IP generally different hosts.
Force execution and ignore minor warnings. Basically no
"destructive" operation, particularly nothing irreversible will
be performed.
Force remote version.
The geometry for client-side representation. It is the exact syntax of X client "--geometry" parameter with an additional screen parameter as alias or index for usage with Xorg multiple displays.
ATTENTION: In order of using xorg.conf and saving effort some minor assumptions as requirements concerning the xorg.conf file are made. Current implementation requires due to stateless filtering the field "Identifier" as first entry in "ServerLayout" sections.
Supported variants:
<x-size>x<y-size>[[+,-]<x-offset>[+,-]<y-offset>]
<geometryExtended>:=
<Xorg-style>
[:[<ScreenSection>|<ScreenIndex>]
[:[<ServerLayout>]
[:[<alternateConfigFile>]
]
]
]
All values are evaluated and calculated at the callee's site, thus has
to be in conformance of the actual targeted XServer, which e.g. could be a
remote DISPLAY in case of DISPLAYFORWARDING.
Print help, refer to "-H" for additional information.
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 chapter
Online-Help or type ctys -H help.
The ID of current job. This is an internal call and therefore should just used by developers for test purposes. Any variation of the JOB_IDX for the CLI call may severe job execution seriously and even can damage user data when set for a CANCEL operation.
The originating CLI call should not use this option in productive operations, any subcall may have a propagated value as required. The value within the originating interactive CLI call is set to "JOB_IDX=0". This is the value for the starting point of internal task-scheduler data, and thus the index for the first performed task too. The value is evaluated by plugins for handling job specific PROLOG and within EPILOG for decision of the state of passed job and eventual required post-processing.
In addition a variable "CTYS_SUBCALL" is set.
The users, which will be used for hosts without an exlicitly given
user. The hosts/groups entries provide the common EMail-Style
"<user>@<execution-target>".
The default is "$USER", when neither "-l", nor an explicit user is provided.
<execution-location>=(
(LOCALONLY|LO)
|(CONNECTIONFORWARDING|CF)
|(DISPLAYFORWARDING|DF)
|(CLIENTONLY|CO)
|(SERVERONLY|SO)
)
This option controls the location and possible split of the involved client and server parts of current session. When connecting a user interface with it's server components the following basic constellations could be distinguished:
Free text to be used as prefix for target exec. It will be
printed before output.
Just display, do not execute. For test only.
Path list to directories containing DBs for name resolution, same for each <db-directory-path> as for ctys-vdbgen. ctys will internally handle names by multiple levels of resolution, which depends on the actual executing plugin. The most sophisticated address resolution is frequently required for VMs when using them in a roaming manner on groups of machines, where after some plugin specific resolution of convenient VM-addressing by user an TCP/IP service-access-point for OpenSSH has to be addressed.
The second case to be handled is the addressing of execution
entities of type HOSTs transparently within a VM or PM. This
will be supplied by ctys-nameservice too.
For almost all of the nameservice tasks additionally required
for plugin-specific address resolution actions the ctys-vhost
command is used internally. This option sets the databases for
operations of ctys-vhost. If not present ctys-vhost defaults
will be applied.
Use default <db-directory-path>.
Remote resolution, which is by default the same as local client size given by "-g" option. This configures the virtual graphic card of the server with the provided resolution. This parameter is not applicable to any application. It has to be defined in the application specific package. The current supported applications are:
Restrics/expands the scope/selected set for mode of operations.
Sets the signal spectrum to be ignored. The values are accepted as numeric values only. Applicable values could be displayed by "trap -l"(within bash).
The default values are "1,3,19", which is set for CLI0 consoles only by default.
In case of CLI, generally for any multi-session call, it has to be
considered thoroughly whether and which signals could be set.
Defines the context of execution and the resulting applicable feature set. This could be a flat endpoint-user-session in case of VNC, or a virtual OS-starter in case of a VM session e.g. in case of VMW or XEN. Suboptions specify more detailed characteristics.
Thus this parameter has to be set first. To load multiple plugins for one call, the environment variable CTYS_MULTITYPE or the "-T" option could be set.
Preloads given list of <session_type> instead of loading the plugins of requested types by "-t" option. Alternatively the environment variable CTYS_MULTITYPE could be pre-set, which has the same result. If CTYS_MULTITYPE and the "-T" option are provided, the option has priority.
This option is required for the scope control of generic actions, which generally will be applied by calling of all current loaded <session_type> interfaces. E.g. the "-a LIST" action lists active sessions for all actually loaded <session_type>. For display of current active sessions of all available <session_type>, the "-T all" has to be used.
Show version. Current version scheme is as follows:
Show version. Current version scheme is as follows:
This parameter requires the tool 'wmctrl' to be present, if not the usage is not provided and an error message is generated before exiting ctys.
When provided by system and successully detected, the following applies:
Defines the resolution of required nested access to a chain of servers. This is e.g. the case when from the machine CLIENT01 the HOST01 is accessed. When now HOST01 required some information from the HOST02 there are basically the options to fetch theses from HOST01 or reply with an open issue and fetch the information from CLIENT01. For requirements exist both cases, but for the common task of user-logins the SSO-keys are only present on the CLIENT01, atleast in case of OpenSSH the ssh-agent might run on CLIENT01 only. When using Keberos with the ticket forwarding option, the CHAIN option should be prefered.
Generate terse output for post processing. The '-v Verbose'
flag is not effected and should be only used for testing.
Activates some terminal capabilities, mainly coloring of ERROR,
WARNING, and WARNINGEXT. Very handy when debugging, but
not yet supported for Emacs-Consoles.
As an alternate the variable "CTYS_TERM_COLORS" could be set to
"0".
When selected the local and remote settings are both set at once.
In current version this is set by default when the variable TERM is set to "xterm".
Activate 'ForwardAgent yes'/'-A' of OpenSSH.
If not active, another SSH authentication is required for each hop.
When no mechanism like keys or Kerberos is in place, password authentication will be used.
The basic configuration of SSH has to be prepared appropriately.
Control the allocation of a pseudotty by ssh. Therefore one or two "-t" options could be set for the internal "ssh" call.
NOPTY : Eliminates "-l" of standard bash-call
and "-t" for ssh-call.
PTY : "-t"
PTY,PTY : "-t -t"
1 : "-t"
2 : "-t -t"
Controls call permission-grant. The calls requiring impersonation to another users ID, frequently "root" for restricted system resources, are supported to use "ksu" and/or "sudo". This option replaces the default settings from the configuration file. The mechanisms could be switched on/off selectively.
KSU : use Kerberos NOKSU : do not use Kerberos (DEFAULT) SUDO : use sudo NOSUDO : do not use sudo (DEFAULT) ALL : use al provided
As an persistent alternative following environment variables could be pre-set.
USE_KSU (0=>off 1=>on) (DEFAULT:0=>off) USE_SUDO (0=>off 1=>on) (DEFAULT:0=>off)
The evaluation is implemented as a generic check for first match of hard-coded call-check. The following order of permission tests is performed for each system callee.
[--] \
['('<any-options global for all remote>')'] \
(([user@]<hostname>)|<groupname>)['('<any-options>')'][ ...]
These are the remote options which are given as global and individual options for each host. The options are (almost) the same as for common call.
ATTENTION:
R_CREATE_MAX=${R_CREATE_MAX:-20}
default:'uname -n'(`uname -n`)
...-d 6 -- ( -d 3 ) host01 host02( -d 1) host02(-d 0)...So, the given options results in the following scenario:
-> localhost: -d 6 = -d 6 -> host01: -d 3 = -d 3 -> host02: -d 3 -> -d 1 = -d 1 -> host03: -d 3 -> -d 0 = -d 0
| Arno-Can Uestuensoez | <https://arnocan.wordpress.com/> |
| <https://unifiedsessionsmanager.sourceforge.io/> | |
| <https://github.com/unifiedsessionsmanager> | |
 |
Copyright (C) 2008, 2009, 2010, 2011, 2020 Ingenieurbuero Arno-Can Uestuensoez
This is software and documentation from BASE package,
For additional information refer to enclosed Releasenotes and License files.
