mw-pfeddersheim-workstation/docs/learnings/2026-07-03-remmina-wayland-crash-fix.md

---
description: >-
  Session record (2026-07-03): diagnosed a Remmina SIGSEGV on Wayland when
  keymap was set, traced it to a missing NULL check on XOpenDisplay in
  remmina-plugin-rdp, forked Remmina to gitlab.com/satware, built from
  source, verified the fix, and submitted MR !2757 upstream.
tags:
  - learning
  - remmina
  - wayland
  - rdp
  - crash-analysis
  - gitlab
  - upstream-contribution
last_updated: '2026-07-03'
---

# Remmina SIGSEGV on Wayland - diagnosis, fix, upstream MR - 2026-07-03

## Summary

Remmina crashed (SIGSEGV) every time the "Mothership" RDP profile was
selected. The root cause was a missing NULL check on `XOpenDisplay(0)` in
`remmina_get_rdp_kbd_remap()` (`plugins/rdp/rdp_plugin.c`), triggered only
when a `keymap` profile setting was non-empty (e.g. `Map Meta Keys`) and
the session was Wayland without accessible X11.

Forked Remmina to `gitlab.com/satware/Remmina`, built from source with
FreeRDP3, reproduced the crash, applied a 4-line fix, verified it, and
submitted merge request [!2757](https://gitlab.com/Remmina/Remmina/-/merge_requests/2757)
to the upstream project.

## Incident

| Field | Value |
|-------|-------|
| Symptom | Remmina closes immediately when selecting "Mothership" and clicking connect |
| Signal | SIGSEGV (segfault) |
| Crash location | `XKeysymToKeycode()` in `libX11.so.6`, called from `remmina-plugin-rdp.so` |
| Profile | `group_rdp_mothership_10-10-202-4.remmina` (server `10.10.202.4`) |
| Working profile | `srv-app-2` (`100.64.0.78`) - identical protocol, no crash |

## Diagnosis

### Stack trace (from coredumpctl)

```
#0  XKeysymToKeycode (libX11.so.6 + 0x92cd7)
#1  remmina-plugin-rdp.so + 0xff27
#2  remmina-plugin-rdp.so + 0x1296b
```

### Root cause

In `plugins/rdp/rdp_plugin.c`, function `remmina_get_rdp_kbd_remap()`:

```c
display = XOpenDisplay(0);           // Returns NULL on Wayland
// NO NULL CHECK
XKeysymToKeycode(display, table[i])  // SIGSEGV - dereferences NULL
```

The function is only called when `keymap` is non-empty in the profile.
The working profile had `keymap=` (empty), which skipped the entire code
path. The crashing profile had `keymap=Map Meta Keys`.

### Environment

| Component | Version |
|-----------|---------|
| OS | Manjaro Linux, Wayland session (`XDG_SESSION_TYPE=wayland`) |
| Remmina | 1.4.43 (git n/a) |
| FreeRDP | 3.27.0 |
| Display | `DISPLAY=:0` (Xwayland) but `XOpenDisplay(0)` fails from RDP worker thread |

### Key config difference

| Setting | Mothership (crashes) | srv-app-2 (works) |
|---------|---------------------|-------------------|
| `keymap` | `Map Meta Keys` | (empty) |

## Fix

4-line addition in `plugins/rdp/rdp_plugin.c`, function `remmina_get_rdp_kbd_remap()`:

```diff
 display = XOpenDisplay(0);
+if (!display) {
+    g_free(rdp_kbd_remap);
+    return NULL;
+}
 for (i = 0; table[i] > 0; i += 2) {
```

The caller at line ~2148 already checks `if (rdp_kbd_remap != NULL)` before
use, so returning NULL causes graceful degradation (empty
`KeyboardRemappingList`) instead of a crash.

## Verification

| Test | Result |
|------|--------|
| Reproduce crash (unpatched, `keymap=Map Meta Keys`) | SIGSEGV - new coredump at 12:05:54 |
| Apply fix, rebuild, same profile | No crash - exit code 0, no new coredump |
| Debug log after fix | `rdp_keyboard_remapping_list:` (empty, as expected) |

## Local workaround (applied)

| Item | Value |
|------|-------|
| Mothership profile `keymap` | Set to empty (`keymap=`) as safe setting |
| Patched plugin | `~/.config/remmina/plugins/remmina-plugin-rdp.so` (loads before system plugin) |
| Source build | `~/external/remmina/` (branch `fix/rdp-xopendisplay-null-check`) |

The patched plugin in `~/.config/remmina/plugins/` protects the system
Remmina (`/usr/bin/remmina`) even if `keymap` is set to a non-empty value.

## Upstream contribution

### GitLab.com setup (one-time)

| Item | Value |
|------|-------|
| GitLab.com group | `gitlab.com/satware` (public, ID 136548341) |
| User | `ironmikechw` (ID 39970188, Owner of `satware` group) |
| PAT | Stored in `~/.env` as `GITLAB_COM_API_TOKEN` |
| glab CLI | Authenticated to both `gitlab.satware.com` and `gitlab.com` |

### Fork and MR

| Item | Value |
|------|-------|
| Upstream | `gitlab.com/Remmina/Remmina` (canonical, project ID 7153509) |
| Fork | `gitlab.com/satware/Remmina` (project ID 84057632) |
| Local clone | `~/external/remmina/` with `upstream` remote added |
| Build | `cmake -Bbuild -H. -DCMAKE_BUILD_TYPE=Debug -DWITH_FREERDP3=ON` |
| Branch | `fix/rdp-xopendisplay-null-check` |
| Commit | `e6084bd7f` - "rdp: fix SIGSEGV when XOpenDisplay returns NULL on Wayland" |
| MR | [!2757](https://gitlab.com/Remmina/Remmina/-/merge_requests/2757) (opened, target: master) |

### Build notes

- CMake flag `-DWITH_FREERDP3=ON` is required (default is OFF/FreeRDP2)
- All build deps present on this workstation (FreeRDP3 3.27.0, GTK3 3.24.52, etc.)
- Build time: ~30 seconds (incremental, 16 cores)
- Plugin loads from `~/.config/remmina/plugins/` (alt dir, checked before system)

## Files touched

| File | Change |
|------|--------|
| `~/.local/share/remmina/group_rdp_mothership_10-10-202-4.remmina` | `keymap=Map Meta Keys` -> `keymap=` (safe setting) |
| `~/.config/remmina/plugins/remmina-plugin-rdp.so` | Patched plugin (built from source) |
| `~/external/remmina/plugins/rdp/rdp_plugin.c` | 4-line NULL check fix (committed + pushed) |
| `~/.env` | `GITLAB_COM_API_TOKEN` added (for glab CLI) |
| `~/.config/glab-cli/config.yml` | gitlab.com host added (glab auth login) |

## References

- MR: https://gitlab.com/Remmina/Remmina/-/merge_requests/2757
- Fork: https://gitlab.com/satware/Remmina
- Upstream: https://gitlab.com/Remmina/Remmina
- CONTRIBUTING.md: fork-and-pull model on GitLab