Skip to content

Kimberley

Jump to bottom
Benjamin Gilbert edited this page Feb 19, 2013 · 2 revisions

Kimberley

The Kimberley system provides a mechanism for one machine to rapidly customize another with one or more applications. A common scenario in which this might be desirable is if a user, on-the-go, encounters a display that he would like to use for a short period of time. With Kimberlize, the user can quickly install a desired application on the display and use it for some amount of time, save any state he might want to keep and then end usage of the display.

Kimberley utilizes two subsystems, Kimberlize and the Display Control Manager (KCM) to provide a method for mobile devices to execute applications on large displays. It is assumed that the large displays do not necessarily have these applications installed prior to use, but do have good hardware and a strong network connection, and also a variety of connection types such as WiFi and Bluetooth used in service discovery. The target applications are those which may not function well on a mobile device due to a variety of hardware and software constraints, such as poor memory, network connection, compute ability or screen size, or the inability to cross-compile for a target processor architecture or software platform.

A pair of applications supply this functionality, referred to as the Mobile Launcher and the Display Launcher.

System Usage

Here is a typical usage of the Kimberley system:

  1. An administrator uses the Kimberlize tool to create a base virtual machine and one or more Kimberlize patches.
  2. The administrator then sets up several displays and distributes the base virtual machine to these displays. He executes the Display Launcher on these machines to broadcast their Kimberley services.
  3. The administrator gives the user the Kimberlize patches, which he either stores directly on a mobile device that he carries with him, or records the URLs at which the patches are available.
  4. The user, while in a mobile setting, encounters a display he would like execute an application on.
  5. The user executes the Mobile Launcher application, supplying it the filename or URL of the Kimberlize patch to use and the name of the virtual machine to which it should be applied. Optionally, the user may also supply a file, formatted as a floppy disk image, to hold any data the user creates that he would like to persist beyond usage of the system.
  6. The Mobile Launcher connects to a KCM running locally to search for Display Launcher services. It establishes a local TCP/IP connection to the KCM.
  7. Upon successful connection establishment between the mobile host and display host KCM processes, the Mobile Display application requires that the client authenticate itself before proceeding.
  8. The launcher programs then communicate the information required to execute the application, and provide thin-client VNC access to the display. If the latency between the mobile device and display is poor, the user will be presented the option to plug in a USB cable to use for data transfer.
  9. The user interacts with the application for some amount of time.
  10. When the user completes interaction with the display, he closes the VNC client on the mobile device, signaling the end of use. The Kimberlize patch is removed and deleted from the display, and the virtual machine reverts back to its base state. If a floppy disk was supplied, a binary difference patch of the new state created is sent back to the mobile device and applied to the original floppy disk image.

In this scenario, the Mobile Launcher and Display Launcher are jointly responsible for the authentication of the mobile device, the transfer of the Kimberlize patch to the display, the creation of a thin-client connection to control the application, and signaling that the user has completed interaction. Looking under the hood, we can see how this interaction occurs first when an administrator sets up a display, and secondly when a user interacts with the display.

Command Syntax

Syntax for the two launcher commands:

mobile_launcher [-d floppy_disk_image] <-f file | -i URL> <vm_name>
display_launcher

The display launcher takes a single option, the string by which the display's service will be known in the KCM. If the option is not present it uses a default string. Since the Display launcher resolves virtual machines at runtime and knows nothing about the patches it will execute, it does not need additional parameters.

The mobile launcher takes either a filename or a URL indicating where the Kimberlize patch exists, the virtual machine name to which this kimberlize patch applies, and optionally the name of the display to browse for. The display name may be physically noted on the display itself if the area contains multiple displays, in order to disambiguate the connection.

Technical Walkthrough of Administrative Setup

During administrative setup of the display,

  1. An administrator sets up a machine attached to the display and installs Kimberley.
    1. Any necessary SASL authentication configuration is performed by the administrator, including installing any custom plug-ins.
    2. If the administrator would like USB networking support, it may need to be enabled in the Linux kernel and appropriate USB network interfaces need to be added and configured. An example on how to do this can be found here.
  2. The administrator executes the Display Launcher.
  3. The Display Launcher immediately spawns a new thread which executes a Sun RPC server used for handling future connections. The Sun RPC server binds to a random port and listens for local connections.
  4. The Display Launcher makes a D-Bus call into the KCM, possibly executing the KCM as a side-effect, publishing services on any available service discovery mechanisms. The port on which the Sun RPC server is listening is supplied.
  5. The system waits for incoming connection requests.

Technical Walkthrough of Usage

Under the hood, the system executes the following steps during typical mobile usage:

  1. The user encounters a display in a mobile setting that he would like to execute an application on.

  2. The user executes mobile_launcher and passes parameters indicating the virtual machine name and location of the kimberlize patch, and optionally the filename of a floppy disk image to use.

  3. The Mobile Launcher makes a D-Bus call into the KCM (possibly executing the KCM as a side effect) browsing for display services of a default or optionally supplied name.

  4. The KCM performs its work, browsing for, connecting to and encrypting the connection to the display, and returning the an integer value representing the port on which a local TCP connection can be made.

  5. The Mobile Launcher receives the port and creates the local TCP connection. The DCM on the display creates a local TCP connection into the Display Launcher's Sun RPC server.

  6. The Mobile Launcher brings up a Sun RPC client on its connected socket.

  7. The Mobile Launcher executes zero or more authentication steps in the form of RPC calls to the Display Launcher. The parameters and results are opaque strings of bytes unknown to the launching system.

  8. The Mobile Launcher issues a series of null RPC pings to the Display Launcher to measure the latency of the connection.

    1. If the latency is above a certain threshold, the Mobile Launcher prompts the user to optionally connect a USB cable to the display to be used as a dedicated network link. This overcomes the sluggishness of a thin client across high latency wireless links in busy areas.
    2. If the user accepts and connects a cable, USB networking interfaces are established and connected between the mobile device and display.

  9. The Mobile Launcher sends the files it will need during the dekimberlize step to the Display Launcher by using a small file transfer protocol consisting of two RPCs:

     typedef opaque data<>;
 int send_file(string filename<1024>, int size);
 int send_file_partial(data part);

A send_file call is made first specifying the name of the incoming file and its size. Then, the Mobile Launcher executes enough send_file_partial calls (1MB per call maximum) to transfer the file. These files may include both a VM overlay and a floppy disk image. The files are collected in a namespace on the display rooted at /tmp/kimberley/, each stored under the basename of the filename provided. The files' actual intended use is specified with later RPCs. Optionally, if the user sent over a floppy disk image, its filename in the local namespace is specified by the following RPC:

    int use_persistent_state(string filename<1024>);

  1. The Mobile Launcher makes one of two RPC calls to the Display Launcher to indicate and possibly transfer Kimberlize state:

     int use_kimberlize_file(string vm_name<128>, string patch_file<2048>);
 int use_kimberlize_URL(string vm_name<128>, string patch_URL<2048>);

  2. Once the kimberlize patch is transferred to the Display Launcher, it executes a short script. The script executes dekimberlize with the parameters passed from the mobile device, and also brings up an x11vnc server on X display ":0.0". The Display Launcher registers the port on which the x11vnc server is listening with the display's KCM. In parallel, the Mobile Launcher begins browsing for VNC services published by the display by repeatedly calling into its KCM. The KCMs usually publish and resolve the new thin client service after a small number of attempts.

  3. The mobile launcher executes vncviewer for the thin-client connection, connecting locally to the port returned from the KCM or directly to the display's USB IP address when USB networking is enabled.

  4. dekimberlize continues to execute and the virtual machine resumes shortly thereafter. Once it is resumed, the user interacts with the application using the UI controls of the mobile device.

  5. When the user completes interaction, he terminates the vncviewer application. The Mobile Launcher receives notice the application has been terminated, and sends a final RPC to the Display Launcher indicating end of use, optionally specifying if the floppy disk delta will be retrieved. The Display Launcher blocks on the RPC, creating the file /tmp/dekimberlize_finished to signal to the dekimberlize script that the user's interaction has ended. The dekimberlize script then does its work, discarding the Kimberlize patch and reverting the virtual machine to its base state, as well as possibly calculating the delta of the floppy disk. When this completes, the Display Launcher returns success on the RPC providing the filename of the newly created floppy disk delta (or null, if none provided). Optionally, the Mobile Launcher retrieves the floppy disk delta file using a protocol of 2 RPCs similar to sending files:

     typedef opaque data<>;
 int     retrieve_file(string filename<1024>);
 data    retrieve_partial(void);

    The Mobile Launcher then executes xdelta to apply the binary difference patch to the original floppy disk image file.

  6. The Display Launcher closes its network connections and re-registers its Kimberley services with the KCM.

  7. The Mobile Launcher saves the persistent state by writing out and applying the patch received in the RPC call, and completes.

Clone this wiki locally