Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »

Introduction

This page is intended to document the OpenXT toolstack. Please feel free to contribute heavily.

xec / xec-vm

These are small haskell programs. Xec is a generic dbus access utility, similar to dbus-send, can be used to communicate with any dbus daemon though defaults to communication with xenmgr. Xec-vm is a wrapper around xec which is VM aware. Both have decent "--help" toggles.

Database daemon

Database daemon (dbd) is a small ocaml/dbus aplication which handles persistence of OpenXT configuration data. The database files are stored in /config/db and /config/vms.

The dbd reads config files (which are in json format) at startup and creates an in-memory representation of the database, which is primarily a simple tree of strings similar to xenstore. From now on it proceeds to work on memory representation only, marking it dirty in case of modifications. The dirty trees are flushed to disk in 3s intervals. Dbd features protection against power cuts / partial writes. It always flushes to temporary file first, then atomically renames the temporary file.

API presented by dbd

  • + read ( path:s, OUT value:s ) reads a string value at given path
  • + read-binary ( path:s, OUT value:ay ) reads byte array value at given path
  • + write ( path:s, value:s ) writes string value to given path
  • + dump ( path:s, OUT value:s ) dumps whole json subtree at given path *+ inject ( path:s, value:s ) writes whole json subtree to given path
  • + list ( path:s, OUT value:as ) lists child nodes at given path
  • + rm ( path:s ) removes subtree at given path
  • + exists ( path:s, OUT ex:b ) checks if a subtree/value at given path exists

RPC proxy

RPC proxy is a haskell application which supports proxying and filtering of RPC traffic used in OpenXT. The proxied traffic consists of either binary dbus (for most use cases) or json/websocket based dbus (for conversations with a web browser in the UIVM) and is transported using UNIX domain sockets or v4v sockets.

There are 3 instances of rpc-proxy running by default in Dom0, each of them having different function:

/usr/bin/rpc-proxy -s

This one forwards data between default incoming channel (v4v port 5555) to default outgoing channel (UNIX socket /var/run/dbus/system_bus_socket). The effect is that it's possible for any VM to connect to v4v port 5555 of Dom0 and get access to its system bus. Similar to connecting locally within the VM by binding the UNIX socket. V4V port 5555 is exposed only to reasonably trusted service VMs, such as NDVM and SyncVM since it's possible to export new services on the Dom0 bus by connecting to it. Rpc-proxy makes the decision whether to forward or drop messages based on the default rules file in /etc/rpc-proxy.rules

/usr/bin/rpc-proxy -i v4v:5556 -n com.citrix.xenclient.guest.uuid_$UUID --translate-anonymous-dests

This one is similar to the one above however slightly more "secure" and therefore exposed to user VMs as well. It forwards data between v4v port 5556 to the default outgoing channel (UNIX socket /var/run/dbus/system_bus_socket). The "-n com.citrix.xenclient.guest.uuid_$UUID" arguments causes any attempt to export named service on Dom0 to force a rename of the service to com.citrix.xenclient.guest.uuid_$UUID. Therefore, a guest connecting to this port can only export one service. This has been useful in the past for implementing an agent in Linux VMs exporting guest power management operations. This may have been replaced by xenstore/pv driver based functionality.

/usr/bin/rpc-proxy -i v4v:8080 --json-in --websockets-in -n com.citrix.xenclient.guest.uuid_$UUID --auto-auth

This one listens on v4v port 8080 and forwards to default outgoing channel (UNIX socket /var/run/dbus/system_bus_socket). It expects incoming data in json format (--json-in) wrapped in websocket protocol (--websockets-in). It limits ability to export service names on Dom0 bus via "-n com.citrix.xenclient.guest.uuid_$UUID". This is used for communications with browsers used in UIVM. "--auto-auth" is just a shortcut to avoid the browser having to do dbus authentication, rpc-proxy will do it on its behalf (we don't use dbus authentication for any security purposes, all it does is state that we are connecting as root).

RPC rules format

The default rpc rules are stored in /etc/rpc-proxy.rules file. Extra rules can be attached to VM config trees and will take effect when the VM is started and be torn down when the VM is stopped. The format of the rules is relatively straightforward, for example:

# nothing can be done by default deny all
# allow stubdoms to talk to surfman,xenmgr,dbus allow stubdom true destination com.citrix.xenclient.surfman allow stubdom true destination com.citrix.xenclient.xenmgr allow stubdom true destination org.freedesktop.DBus interface org.freedesktop.DBus
# allow guests to call 'gather' on diagnostics interface (required by xc-diag)allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.diag member gather
# allow anybody to do some vm queries required for switcher bar allow destination com.citrix.xenclient.xenmgr interface org.freedesktop.DBus.Properties member Get allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr member list_vms allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.vm member get_db_key allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.vm member read_icon allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.vm member switch allow destination com.citrix.xenclient.input interface com.citrix.xenclient.input member get_focus_domid allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr member find_vm_by_domid
# allow guest to do some requests allow destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.guestreq member request_attention
# allow conditional domstore (private db space) access allow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member read if-boolean domstore-read-access true allow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member read_binary if-boolean domstore-read-access trueallow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member list if-boolean domstore-read-access true allow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member exists if-boolean domstore-read-access true
# allow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member write if-boolean domstore-write-access true allow destination com.citrix.xenclient.db interface com.citrix.xenclient.db member rm if-boolean domstore-write-access true

  • Only allow/deny rules are supported. The rule type specification is followed by a dbus message matcher where "destination " "interface " and "member " can be specified to match the corresponding fields of an incoming dbus message.

  • stubdom rules

Of some interest are stubdom rules marked as "stubdom true". They only match on messages coming from stub domains.

  • rules based on configuration of VM sending the message It is also possible to make rules based on any boolean fields in an incoming VM config tree. In the example above "if-boolean domstore-read-access true" matches only if the VM which has sent the message has a "domstore-read-access" boolean config in its tree set to true. Therefore, it is possible to disable/enable VM's domstore access (which boils down to allowing it to access dbd remotely) simply by manipulating its config tree.

  • rules based on domain type Sometimes it's useful to grant rpc permission to all VMs of particular type (such as "NDVM", "SyncVM"). This can be achieved by adding "dom-type " matcher to the rule, for example: allow dom-type syncvm destination com.citrix.xenclient.xenmgr interface com.citrix.xenclient.xenmgr.vm member add_disk

  • No labels