[BUG/FIX] Cursor invisible when using Webtop (Wayland) behind HAProxy Reverse Proxy

Open
#420 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
3/5
Estimated time
1-2 days
Newbie friendliness
45/100
Issue type
Bug
Clarity
Mostly clear
Activity status
Quiet
Tech stack
docker, linux
Domain
desktop, devops

Research direction

Start by reproducing the missing cursor with PIXELFLUX_WAYLAND=true through the HAProxy backend, then compare it with direct container access. Inspect the labwc/smithay cursor path and the WLR_NO_HARDWARE_CURSORS setting, along with the listed WebSocket proxy settings. Done means the cursor is visible through the proxy without an unexplained regression in the direct-access path.

Written by the indexing model from the issue text.

Description

no-issue-activity
Is there an existing issue for this?
  • I have searched the existing issues
Current Behavior

When accessing the Webtop container through an HAProxy reverse proxy (SSL Offloading), the mouse cursor is completely invisible, even though clicks are registered. The cursor is visible when bypassing the proxy (local IP access).

Expected Behavior

Root Cause:
By default, the Wayland compositor (labwc / smithay) attempts to use hardware cursor planes. When the stream is re-encoded or proxied through a WebSocket tunnel handled by a reverse proxy, the hardware layer of the cursor is not captured in the video frame, making it invisible to the client.

The Fix:
Adding the environment variable WLR_NO_HARDWARE_CURSORS=1 forces the compositor to use software-based cursor rendering, which ensures the cursor is drawn directly into the framebuffer and sent through the stream.
Without that fix, cursor was render only on Gamemode with fullscreen.

Steps To Reproduce

Setup a Webtop container with PIXELFLUX_WAYLAND=true.
Configure HAProxy to handle SSL and proxy the traffic to the container (Port 3000).
Access the Webtop via the public domain.
Observe that the mouse cursor is missing.

Environment
OS: Debian Stable
Image: lscr.io/linuxserver/webtop:latest and amd64-ubuntu-xfce
Display Protocol: Wayland (PIXELFLUX_WAYLAND=true)
Reverse Proxy: HAProxy (running on Host)
Browser: Chromium Webrowser (not tested with Firefox)
CPU architecture

x86-64

Docker creation
---
services:
  webtop:
    image: lscr.io/linuxserver/webtop:amd64-ubuntu-xfce
    container_name: webtop
    network_mode: host
    devices:
      - /dev/dri:/dev/dri
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Paris
      - PIXELFLUX_WAYLAND=true
      - DRINODE=/dev/dri/renderD128
      - DRI_NODE=/dev/dri/renderD128
      - CUSTOM_WS_PORT=8093
      - CUSTOM_PORT=3000
      - CUSTOM_HTTPS_PORT=3001
      - TITLE=Webtop
      - DISABLE_IPV6=TRUE
      - SUBFOLDER=/
      - CUSTOM_USER=xxxxxxxxxx
      - PASSWORD=xxxxxxxxx
      - WLR_NO_HARDWARE_CURSORS=1
    volumes:
      - /opt/docker/webtop/config:/config
      - /var/run/docker.sock:/var/run/docker.sock
    shm_size: "1gb"
    restart: unless-stopped

Additional Notes for Proxy Users:
For HAProxy users, the following backend settings were also necessary to ensure smooth input/output:

backend webtop
    mode http
    timeout tunnel 1h
    option http-no-delay
    no option http-buffer-request
    http-request set-header Upgrade websocket if { hdr(Upgrade) -i WebSocket }
    http-request set-header Connection Upgrade if { hdr(Upgrade) -i WebSocket }
    server webtop 127.0.0.1:3000 check

I hope this helps others facing the same issue with Wayland-based Webtops behind proxies!

Question / Technical Inquiry:
Is this behavior expected, and is there a "cleaner" way to handle hardware cursors through a proxy?
While WLR_NO_HARDWARE_CURSORS=1 works, it disables hardware acceleration for the pointer, which might increase CPU overhead. I noticed that:

The issue only occurs when the stream is proxied (HAProxy).
Direct access to the container (IP:Port) sometimes manages to display the cursor even without this flag (depending on the browser).

Questions for the maintainers:
Is there a specific KasmVNC or Labwc configuration that could "flatten" the hardware cursor plane into the primary buffer without disabling hardware cursors entirely?

Could this be related to how selkies-gstreamer or KasmVNC captures the Wayland output?

Are there specific Permissions-Policy or Feature-Policy headers that should be passed by the reverse proxy to allow the browser to better handle the hardware pointer lock/overlay?

Dominant language
Shell
Stars
4.4k
Forks
377
PR merge metrics
No merged PRs in 30d

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from linuxserver/docker-webtop

All issues in linuxserver/docker-webtop

Similar issues

More Shell/Bash issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.