Skip to main content

KasmVNC Blank Screen on AWS Ubuntu 22.04 - DBus Connection Issue

Updated

When using the KasmVNC module with xfce desktop environment on AWS Ubuntu 22.04 VMs, the browser displays a blank screen instead of the desktop interface. The xfce4-session process runs but desktop tools fail to load.

Root Cause

The xfce4-session launched via KasmVNC's select-de.sh script does not connect to dbus on certain AWS Ubuntu 22.04 VM configurations. The exec xfce4-session command lacks the dbus-launch wrapper required for proper desktop environment initialization.

Note: This issue does not affect Cinnamon or Gnome desktop environments, as the KasmVNC module already uses dbus-launch for these options.

Affected Environments

  • Cloud Provider: AWS
  • OS: Ubuntu 22.04
  • Desktop Environment: xfce
  • KasmVNC Module: All versions

Solution

Prerequisites

  • Access to modify Coder templates
  • Local copy of the KasmVNC module

Implementation Steps

1. Clone KasmVNC Module Locally

Pull your existing template and create a local modules directory: 

coder templates pull <template-name>
mkdir -p ./modules/kasmvnc

Clone or copy the KasmVNC module from the registry into ./modules/kasmvnc: 

git clone https://github.com/coder/registry.git
cp -r registry/registry/coder/modules/kasmvnc/* ./modules/kasmvnc/

2. Update Template to Use Local Module

In your template's main.tf, modify the KasmVNC module block: 

module "kasmvnc" {
  count               = data.coder_workspace.me.start_count
  source              = "./modules/kasmvnc"  # Changed from registry.coder.com
  # version           = "1.2.5"              # Comment out version
  agent_id            = coder_agent.main.id
  desktop_environment = "xfce"
  subdomain           = false
}

3. Modify the Module's run.sh Script

Edit ./modules/kasmvnc/run.sh at approximately line 291, immediately after the line: 

printf "Starting KasmVNC server...\n"

Add the following sed command:

sudo sed -i.bk 's/exec xfce4-session/exec dbus-launch xfce4-session/g' /usr/lib/kasmvncserver/select-de.sh

What this does: Modifies KasmVNC's desktop environment selector to wrap xfce4-session with dbus-launch before the VNC server starts.

4. Push Updated Template

coder templates push --yes

5. Test

  • Create a new workspace from the updated template
  • Connect via KasmVNC
  • Verify the xfce desktop loads with all tools visible

Alternative Methods Considered

Method 1: Manual Desktop Environment (Not Recommended)

Setting desktop_environment = "manual" and directly modifying run.sh to add dbus-launch to the exec line. This approach was rejected because:

  • Requires using an undocumented "manual" option
  • More invasive changes to module behavior
  • Less maintainable

Technical Details

Why This Happens

On certain AWS Ubuntu 22.04 configurations, the dbus daemon is not automatically available to processes launched via exec. Desktop environments require dbus for inter-process communication between desktop components (panels, window managers, system trays, etc.).

Why Gnome/Cinnamon Work

The KasmVNC module's select-de.sh already includes dbus-launch for Gnome and Cinnamon desktop environments, which is why this issue is isolated to xfce.

Diagnostic Commands

If troubleshooting similar issues:

# Check if xfce4-session is running
ps aux | grep xfce4-session

# View KasmVNC logs
cat ~/.vnc/*.log

# Check dbus status
echo $DBUS_SESSION_BUS_ADDRESS

# Manually test dbus-launch
dbus-launch xfce4-session

Future Considerations

  • This issue may not persist on Ubuntu 24.04
  • Consider contributing this fix upstream to the coder/registry repository
  • Monitor for similar reports on other cloud providers or distributions

Related Documentation

Related to

Related articles