Skip to content

Kerbside Documentation

Welcome to the Kerbside documentation.

Documentation Version

This documentation covers:

  • SPICE Protocol Version: 2.2 (current as of spice-protocol 0.14)
  • Kerbside Version: Verified against kerbside/spiceprotocol/packets/constants.py
  • OpenStack Integration: Nova 2025.1 (Epoxy) and later

Protocol documentation is derived from the official SPICE protocol sources at gitlab.freedesktop.org/spice/spice-protocol and verified against Kerbside's implementation. Message IDs and constants reflect Kerbside's internal mappings.

Introduction

Kerbside is a SPICE protocol native VDI proxy responsible for providing rich VDI experiences to users of Shaken Fist, oVirt, OpenStack, or any other cloud where the hypervisor is capable of providing SPICE consoles over the network.

The SPICE protocol has existed for a long time, and still represents the richest and most performant option for remote desktops using Open Source technologies. Before Kerbside, consoles were generally provided by a HTML5 transcoded interface in a web client. Unfortunately, HTML5 interfaces do not support many of the more novel features of the SPICE protocol, nor do they support high resolution desktops. By avoiding transcoding to a HTML5 client, we avoid these problems.

Novel features of SPICE include high resolution desktops, multi-screen desktops, USB device passthrough, sound, multiple user connections to a single console, adaptive compression, and more.

Kerbside is Experimental

Kerbside is currently considered experimental. While it works, it has not yet seen large scale deployment and it is likely that it will need modifications as it is hardened for production use.

Kerbside is a Proxy, Not a Complete User Interface

Whilst Kerbside presents a simple administrative interface over HTTP and has REST APIs for orchestrating consoles, it is not intended as a complete SPICE desktop VDI solution. It is intended that Kerbside itself is orchestrated by an external system. That is, in order for a desktop to be presented to a user the following steps need to occur:

  1. The user requests a desktop via an external user interface that we call "the Broker". In Shaken Fist's case the broker is embedded in Shaken Fist itself and is initiated via a Shaken Fist REST API. In the OpenStack case this role is likely performed by Horizon or Skyline, although this is not yet implemented.

  2. The cloud boots the instance that runs the desktop. The Broker waits for the instance to be booted.

  3. The Broker requests a .vv virt-viewer compatible ini file from Kerbside, and delivers that to the requesting user. The configuration file describes a connection to Kerbside, along with short lived access token.

  4. The user opens the .vv file with a SPICE client such as remote-viewer. remote-viewer connects to Kerbside.

  5. Kerbside uses the access token to determine which instance in the cloud is the requested desktop and initiates a proxied connection to the hypervisor.

  6. The user then happily uses their SPICE console, largely unaware of these various steps.

Connection Flow Diagram

+------------------+              +-------------------+              +------------------+
|                  |              |                   |              |                  |
|  External Broker |  1. Request  |     Kerbside      |  5. Connect  |   Hypervisor     |
|  (SF/Horizon)    +------------->|   SPICE Proxy     +------------->|   (QEMU/KVM)     |
|                  |   .vv file   |                   |   to console |                  |
+--------+---------+              +---------+---------+              +------------------+
         |                                  ^
         | 2. Return                        |
         |    .vv file                      | 4. Connect with
         v                                  |    access token
+--------+---------+                        |
|                  |                        |
|   User's SPICE   +------------------------+
|   Client         |  3. User opens .vv file
|  (remote-viewer) |
|                  |
+------------------+

Implementation in OpenStack

OpenStack Nova now supports native SPICE direct consoles as of the 2025.1 Epoxy release. The Nova specification adds a new "spice-direct" console type that enables users to access virtual desktops using native SPICE clients like remote-viewer instead of HTML5 proxies.

When users request a SPICE direct console, Nova returns a URL pointing to Kerbside with an authentication token. Kerbside validates this token via the /os-console-auth-tokens/ API and establishes the proxied connection to the hypervisor. This provides users with a much richer virtual desktop experience including support for USB passthrough, audio, and multi-monitor configurations.

Kerbside needs to be deployed as a component of the OpenStack cluster to provide a safe mechanism for users to interact with their console. OpenStack is (wisely) unwilling to provide direct network connectivity from a client network to TCP ports on the hypervisor, and so Kerbside acts as an intermediary to protect those hypervisors. There is a sample implementation of Kerbside deployment using Kolla-Ansible in the Kerbside Patches repository.

What About Bumblebee?

The folks over at the NECTAR research cloud developed Bumblebee VDI, which is superficially similar to Kerbside in that it provides a mechanism to make it easier to obtain a virtual desktop as a user. The Kerbside description above would classify Bumblebee as a Broker to our model -- it orchestrates the creation and then access to virtual desktops for users. However, Bumblebee exclusively orchestrates HTML5 consoles using Apache Guacamole as its HTML5 proxy at the moment, so misses out on some of the richer features of SPICE and has the performance implications of a HTML5 desktop environment.

Documentation Index

Operator Documentation

Guides for deploying and configuring Kerbside:

  • Configuration - Configuration reference for all Kerbside settings including TLS, Keystone, API, and monitoring options

  • Console Sources - Configuring console sources (sources.yaml) for Shaken Fist, oVirt, and OpenStack

  • Database Schema - Database tables, columns, and relationships

Architecture Documentation

Internal design of the Kerbside proxy:

  • Proxy Architecture - Internal architecture including process model, connection state machine, traffic inspection, and worker management

  • ARCHITECTURE.md - High-level system architecture overview (in project root)

SPICE Protocol Documentation

Core protocol specifications covering connection handshake, authentication, and channel message formats:

  • Protocol Overview - Introduction to SPICE protocol fundamentals including channel types, message structure, capabilities, and security model

  • Link Protocol - Connection handshake details including SpiceLinkMess/SpiceLinkReply formats, RSA key exchange, and authentication flow

  • Channel Protocols - Detailed message formats for each SPICE channel:

  • Main channel - Session control, channel negotiation
  • Display channel - Screen updates, drawing operations, video streaming
  • Inputs channel - Keyboard and mouse input
  • Cursor channel - Cursor shape and position
  • Playback/Record channels - Audio streaming

  • Smartcard channel - Smart card redirection

  • Keyboard Scancodes - Complete reference for IBM PC XT scancodes used by the inputs channel, including standard keys, extended keys (E0 prefix), and media/browser keys

  • Compression Protocols - LZ and GLZ image compression formats used by the display channel, including header formats, command encoding, and dictionary-based decompression

  • Capabilities - Channel capability negotiation including common, display, audio, and input capabilities with recommended settings

Device Redirection Protocols

Protocols for redirecting client devices to the virtual machine:

  • USB Redirection - USB device redirection protocol (usbredir) including all control and data message formats, capability negotiation, and device filter rules

Guest Agent Protocol

Protocol for advanced guest integration features:

  • VD Agent Protocol - Guest agent protocol for clipboard sharing, file transfer, display configuration, and volume sync

Protocol Implementation Status

Feature Status Notes
SPICE Link Handshake Full Token-based auth extension
Main Channel Full Session control, agent passthrough
Display Channel Full All drawing ops, video streaming
Inputs Channel Full Keyboard, mouse, scancodes
Cursor Channel Full Shape, position, trail
Playback Channel Proxy Audio passthrough
Record Channel Proxy Audio passthrough
Smartcard Channel Proxy Passthrough
USB Redirection Proxy Passthrough with hello decoding
Port Channel (VMC) Full USB redir encapsulation
WebDAV Channel Proxy Passthrough
VD Agent Proxy Clipboard/file transfer passthrough

Full: Protocol decoded and logged during inspection Proxy: Traffic forwarded transparently without decoding

Quick Reference

Channel Types

ID Channel Purpose
1 main Session control
2 display Screen updates
3 inputs Keyboard/mouse
4 cursor Cursor rendering
5 playback Audio output
6 record Audio input
7 tunnel Obsolete
8 smartcard Smart card
9 usbredir USB devices
10 port VMC protocol
11 webdav File sharing

Error Codes

See Protocol Overview - Error Codes for the complete list of SPICE link error codes.

Common Capabilities

Bit Capability Description
0 AuthSelection Auth mechanism selection
1 AuthSpice SPICE native auth
2 AuthSASL SASL auth
3 MiniHeader Compact message headers

External References

Official SPICE protocol resources:

Contributing

When adding new protocol support or modifying existing implementations:

  1. Update the relevant documentation in this directory
  2. Include binary format descriptions with field offsets
  3. Document any deviations from the official SPICE protocol
  4. Add traffic inspection support in spiceprotocol/packets/
  5. Update constants in spiceprotocol/packets/constants.py

Document Conventions

Throughout this documentation:

  • Binary formats use little-endian byte order unless noted otherwise
  • Offset values are in bytes from the start of the structure
  • Size values are in bytes
  • uint32, uint16, uint8 refer to unsigned integers
  • int32, int16, int8 refer to signed integers
  • bytes refers to raw binary data
  • string refers to null-terminated ASCII/UTF-8 text
  • S->C means server to client direction
  • C->S means client to server direction

📝 Report an issue with this page