Technology Tales

Remote access between Mac and Linux, Part 2: x11vnc for sharing physical desktops

29^th October 2025

This is Part 2 of a three-part series on connecting a Mac to a Linux Mint desktop. Part 1 introduced the available options, whilst Part 3 covers SSH, RDP and TigerVNC.

Sharing the existing physical desktop is the point at which x11vnc enters the picture. Unlike a virtual VNC server, x11vnc mirrors the live X display, so what appears on the Linux monitor is exactly what is seen remotely. This is often preferred when a process or window must be observed without starting another session, making it particularly useful for monitoring ongoing work or guiding someone seated at the machine.

Basic Setup

Installing x11vnc and creating a password with x11vnc -storepasswd sets up the basics. The command x11vnc -usepw -display :0 -forever shares the current display on port 5900. The -display :0 flag is the important part, as :0 corresponds to the active physical display.

On the Mac side, RealVNC Viewer can connect by supplying either the IP address alone or the address with :5900 appended. If an "Invalid endpoint: port not correctly specified" error appears, it almost always stems from an incorrect address format. The correct forms are 192.168.1.50 or 192.168.1.50:5900, whereas entries such as 192.168.1.50::5900 or 192.168.1.50:0 will fail.

If there is any uncertainty about the port in use, running netstat -tlnp | grep x11vnc on the Linux machine should show a listener on 0.0.0.0:5900 when sharing display :0.

VNC display numbers map directly to TCP ports, so :0 means 5900, :1 means 5901 and so on. When connecting with RealVNC Viewer, supplying the address alone will use the default VNC port, which suits x11vnc on display :0. If a port must be stated, use a single colon with the actual TCP port, not the X display number.

Performance Tuning

Performance tuning is possible with a few additional options. x11vnc can enable a client-side pixel cache with -ncache 10, which asks the viewer to keep a set of off-screen image buffers for faster redraws, and -ncache_cr improves visible smoothness when windows are moved by encouraging copyrect updates.

When scrolling seems to stutter, -scrollcopyrect can help by detecting scroll operations and drawing them efficiently. -grabptr can improve pointer synchronisation between client and server.

On composited desktops, the X DAMAGE extension is used by default to hint at changed regions, but some compositing window managers interfere with this. In such cases, adding -noxdamage can avoid issues where updates are missed, at the cost of more conservative screen polling. x11vnc prints guidance about these behaviours on startup, which can be useful if any anomalies are encountered.

Input Handling and Mouse Button Issues

Input behaviour over VNC often differs from what is experienced when using the Linux machine directly. x11vnc does not carry the Mac's system preferences for the mouse or trackpad across the network; rather, it synthesises standard events that the X server interprets. As a result, wheel scrolling may feel different and the mapping of mouse buttons can be surprising.

When everything works perfectly whilst sitting at the Linux desktop but changes when connecting remotely, it is often because the events are being translated in a generic fashion over VNC. Trying a different viewer on the Mac sometimes improves matters because each has its own handling of input. The macOS Screen Sharing app, RealVNC Viewer and the TigerVNC viewer are all viable choices, and they do not feel identical in use.

Working with KVM Switches

It is also worth noting that hardware in the path can alter what the Linux system receives. If a mouse is connected through a KVM switch, the KVM may re-encode USB Human Interface Device signals, so the computer sees a very generic device. This can remap buttons in unexpected ways, and that mapping can differ between direct local use and a VNC session that injects events at another layer.

One way to correct misassigned buttons is to ask x11vnc to translate them with -buttonmap, which swaps the first three buttons so that the injected events match what the desktop expects. In simple cases where, for example, middle and right are reversed, -buttonmap 132 can restore the standard order of left, middle and right.

However, when a device presents right-click as a higher-numbered button such as 8, x11vnc's simple mapping is not enough because it only translates the primary trio. In that situation, the correction needs to happen before x11vnc sees the events by using the X input system.

The xinput list command identifies the device and xinput get-button-map shows how its buttons are currently enumerated. Applying xinput set-button-map with the desired sequence, for instance xinput set-button-map <ID> 1 2 3 4 5 6 7 8 9, forces the right codes at the operating system level and resolves the issue for both local and remote sessions.

These changes are not persistent across reboots unless added to a startup script or represented with an Xorg configuration snippet. Alternatively, some KVM models offer a HID pass-through or transparent mode that preserves the device's native signalling, which avoids the need for remapping. Bypassing the KVM for the mouse entirely is another way to ensure that the Linux machine sees the expected button layout, though this obviously changes how inputs are switched between computers.

Even after addressing button mapping, some scrolling oddities can remain. Combining the caching options with -scrollcopyrect and -grabptr, then reconnecting with a different viewer if needed, often gets closer to the feel of direct use.

Clipboard Support

Clipboard support is an area that can require attention depending on the tools in use. With x11vnc, clipboard synchronisation for plain text is supported, though the exact behaviour and configuration requirements can vary. Version 0.9.16 includes clipboard functionality, but in practice users often report difficulties with bidirectional clipboard operation and may need to use helper utilities such as autocutsel to achieve reliable two-way clipboard sharing.

When properly configured, copying text on one side and pasting on the other should work in both directions, with Command-C and Command-V on macOS and the usual Ctrl shortcuts on Linux. Rich text and images are not transferred, and file copy-paste is not supported by x11vnc at all.

Troubleshooting Clipboard Synchronisation

If clipboard synchronisation is not working as expected, x11vnc can be run with verbose logging to observe clipboard events in real time. This is particularly useful for diagnosing whether clipboard data are being detected and transferred between the client and server.

To enable detailed logging, first stop any running x11vnc service:

sudo systemctl stop x11vnc.service

Then start x11vnc manually in a terminal with increased verbosity:

x11vnc -usepw -display :0 -forever -verbose -o ~/x11vnc_debug.log

Connect from the Mac via RealVNC Viewer and attempt to copy and paste text in both directions. In another terminal, monitor the log file:

tail -f ~/x11vnc_debug.log

Lines mentioning clipboard activity, such as "Clipboard: received new client data" or "Clipboard: sending text selection to X server", indicate that x11vnc is detecting and transferring clipboard changes. If no clipboard-related messages appear, the VNC viewer may have clipboard synchronisation disabled in its settings.

In RealVNC Viewer, check Preferences → Inputs to ensure that clipboard synchronisation is enabled. On the macOS Screen Sharing app, clipboard support should work by default when connecting to x11vnc.

After testing, stop the manual run with Ctrl+C and restart the service:

sudo systemctl start x11vnc.service

To make verbose logging permanent, the -verbose flag and log output option can be added to the systemd service file's ExecStart line, allowing clipboard activity to be monitored in /var/log/x11vnc.log at any time.

Running x11vnc as a System Service

If x11vnc is to be used regularly and convenience matters, it can be launched at startup as a service so that a remote viewer can connect without a preparatory shell session on the Linux side. Setting up x11vnc as a systemd service ensures that the VNC server starts automatically whenever the Linux Mint machine boots, even before logging in.

To create the service, run:

sudo nano /etc/systemd/system/x11vnc.service

Then paste the following configuration, adjusting the username as needed:

[Unit]
Description=Start x11vnc at startup for user johnh
After=display-manager.service
Requires=display-manager.service

[Service]
Type=simple
ExecStart=/usr/bin/x11vnc -auth guess -forever -loop -noxdamage 
  -display :0 -rfbauth /home/johnh/.vnc/passwd 
  -buttonmap 138456729 -ncache 10 -ncache_cr 
  -o /var/log/x11vnc.log
User=johnh
Group=johnh
Restart=on-failure

[Install]
WantedBy=multi-user.target

The -auth guess option allows x11vnc to attach to the X session automatically, whilst logging is directed to /var/log/x11vnc.log. The button mapping and caching options shown here incorporate the performance tuning and input corrections discussed earlier. Adjust /home/johnh and the username to match the account in use.

After creating the service file, reload systemd and enable the service:

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

Check that the service is running:

systemctl status x11vnc.service

The output should show Active: active (running). Once this is in place, the Mac can connect to vnc://<linux-ip>:5900 at any time, even immediately after the Linux machine boots.

If x11vnc does not reconnect cleanly after logging out of Cinnamon, adding ExecStopPost=/bin/sleep 2 to the [Service] section will give systemd a brief pause before restarting the service.

Security Considerations

Security considerations in a home setting are straightforward. When both machines are on the same local network, there is no need to adjust router settings. If remote access from outside the home is required, port forwarding and additional protections would be needed.

VNC should not be left open to the internet without an encrypted wrapper. For purely local use, enabling the service at boot as described above often suffices, but for external access an SSH tunnel or VPN is essential.

Conclusion

x11vnc provides a reliable way to share the physical desktop of a Linux machine with a Mac on the same network. The setup is not onerous, and once the service is configured and the few necessary commands are learned, the connection can become an ordinary part of using the machines. The pitfalls that appear repeatedly, such as port format in viewer applications, clipboard configuration, or the way KVM switches can alter mouse behaviour, are easily overcome with a little attention to detail.

In Part 3, we examine the alternatives: SSH for terminal access, RDP with Xfce for responsive remote desktop sessions, and TigerVNC for virtual Cinnamon desktops.