Control Ubuntu Desktop from macOS via VNC

gistfile1.txt

# Control Ubuntu Desktop from macOS via VNC

A step-by-step guide to remotely control an Ubuntu 22.04 desktop from macOS using x11vnc.

## Prerequisites

- Ubuntu 22.04 (or similar) with a desktop environment
- macOS with built-in Screen Sharing
- Both machines on the same network

## Step 1: Switch Ubuntu to X11 (if using Wayland)

By default, Ubuntu 22.04 uses Wayland, which doesn't work well with VNC. Switch to X11:

```bash
sudo sed -i 's/#WaylandEnable=false/WaylandEnable=false/' /etc/gdm3/custom.conf
sudo reboot
```

Verify after reboot:

```bash
loginctl show-session $(loginctl list-sessions --no-legend | awk '{print $1}' | head -1) -p Type
```

Should output `Type=x11`.

## Step 2: Install x11vnc

```bash
sudo apt update
sudo apt install -y x11vnc
```

## Step 3: Set a VNC Password

```bash
mkdir -p ~/.vnc
x11vnc -storepasswd ~/.vnc/passwd
```

Enter and confirm your desired password when prompted.

## Step 4: Start the VNC Server

```bash
x11vnc -display :0 \
  -auth /run/user/$(id -u)/gdm/Xauthority \
  -forever \
  -rfbport 5900 \
  -rfbauth ~/.vnc/passwd \
  -bg \
  -o ~/.vnc/x11vnc.log
```

### Flags explained

| Flag | Purpose |
|------|---------|
| `-display :0` | Share the main desktop display |
| `-auth ...` | X authority file for GDM sessions |
| `-forever` | Keep running after client disconnects |
| `-rfbport 5900` | Listen on standard VNC port |
| `-rfbauth ~/.vnc/passwd` | Use password file for authentication |
| `-bg` | Run in background |
| `-o ~/.vnc/x11vnc.log` | Log to file |

### Verify it's running

```bash
ss -tlnp | grep 5900
```

## Step 5: Connect from macOS

### Option A: Finder

1. Open **Finder**
2. Menu bar → **Go** → **Connect to Server** (or press `⌘K`)
3. Enter: `vnc://<ubuntu-ip>:5900`
4. Click **Connect**
5. Enter the VNC password

### Option B: Screen Sharing app

1. Open **Screen Sharing.app** (search in Spotlight with `⌘Space`)
2. Enter: `<ubuntu-ip>:5900`
3. Click **Connect**
4. Enter the VNC password

### Find your Ubuntu IP

```bash
hostname -I | awk '{print $1}'
```

## Auto-start VNC on Boot

Create a systemd service so x11vnc starts automatically:

```bash
sudo tee /etc/systemd/system/x11vnc.service > /dev/null << 'EOF'
[Unit]
Description=x11vnc VNC Server
After=display-manager.service network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/x11vnc -display :0 -auth /run/user/1000/gdm/Xauthority -forever -rfbport 5900 -rfbauth /home/YOUR_USERNAME/.vnc/passwd -o /var/log/x11vnc.log
ExecStop=/bin/kill -TERM $MAINPID
Restart=on-failure
RestartSec=3

[Install]
WantedBy=graphical.target
EOF
```

Replace `YOUR_USERNAME` with your actual username, then enable it:

```bash
sudo systemctl daemon-reload
sudo systemctl enable x11vnc.service
sudo systemctl start x11vnc.service
```

## Troubleshooting

### "Connection refused" on macOS

- Check the VNC server is running: `ss -tlnp | grep 5900`
- Check the firewall: `sudo ufw allow 5900/tcp`

### Black screen or no display

- Make sure you're using X11, not Wayland (see Step 1)
- Verify the correct `-auth` path: `ps aux | grep Xorg` and look for the `-auth` argument

### Laggy or slow connection

- Use a wired connection if possible
- Reduce screen resolution on Ubuntu: **Settings → Displays**

### Stop the VNC server

```bash
x11vnc -R stop    # graceful stop
# or
killall x11vnc    # force stop
```

## Security Note

VNC traffic is **unencrypted** by default. For remote access over the internet, use an **SSH tunnel**:

```bash
# On macOS, create an SSH tunnel first:
ssh -L 5900:localhost:5900 user@ubuntu-ip

# Then connect Screen Sharing to:
vnc://localhost:5900
```

This encrypts all VNC traffic through SSH.

## Switching from Wayland to X11: What to Know

Switching to X11 is needed for VNC compatibility, but there are trade-offs worth understanding.

### What you lose on X11

| Feature | Wayland | X11 |
|---------|---------|-----|
| **Security** | Apps cannot capture other apps' input/screen | Any app can snoop on keyboard/screen (by design — this is what makes VNC work) |
| **Fractional scaling** | Native, crisp | Blurry on non-integer scales (125%, 150%) |
| **Multi-monitor with mixed DPI** | Each monitor scales independently | All monitors share one scale factor |
| **Screen tearing** | Tear-free by default | May tear without compositor tweaks |
| **Touchpad gestures** | Full support in GNOME | Some gestures may not work |

### What works better on X11

- **VNC / remote desktop tools** like x11vnc work directly
- **Screen sharing** in apps like Zoom, Teams, and Discord is more reliable
- **Older apps** and games that haven't been ported to Wayland work without issues
- **NVIDIA proprietary drivers** (older versions) work more reliably
- **Xdotool / xdg utilities** and automation scripts work as expected

### Potential issues after switching

1. **Screen recording may break in some apps** — apps using PipeWire screen capture (designed for Wayland) may need reconfiguration
2. **GNOME extensions** — most work on both, but a few are Wayland-only
3. **Electron apps** — some apps (VS Code, Slack, Discord) may default to XWayland on Wayland and behave slightly differently on native X11; usually not a problem
4. **Clipboard between Flatpak/Snap apps** — can occasionally behave differently under X11

### How to switch back to Wayland

If you want to revert:

```bash
sudo sed -i 's/WaylandEnable=false/#WaylandEnable=false/' /etc/gdm3/custom.conf
sudo reboot
```

Or simply choose **"Ubuntu on Wayland"** from the gear icon on the login screen (GDM) without editing any files.

### Can I keep Wayland and still use VNC?

Yes, but it's more limited:

- **GNOME Remote Desktop** (built-in on Ubuntu 22.04+) supports VNC on Wayland, but stores the password in the GNOME Keyring, which can be difficult to configure from a remote/SSH session
- **Third-party tools** like RustDesk or AnyDesk support Wayland via PipeWire, but are not standard VNC

For the simplest and most reliable VNC experience, X11 + x11vnc remains the best option.