X.Org Server | 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 precisely 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
After=display-manager.service
Requires=display-manager.service

[Service]
Type=simple
ExecStart=/usr/bin/x11vnc -auth guess -forever -loop -noxdamage 
  -display :0 -rfbauth /home/user/.vnc/passwd 
  -buttonmap 138456729 -ncache 10 -ncache_cr 
  -o /var/log/x11vnc.log
User=user
Group=user
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/user 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.

Installing FreeBSD in a VirtualBox Virtual Machine

2^nd March 2014

With UNIX being the basis of Linux, I have a soft spot for trying out any UNIX that can be installed on a PC. For a while, I had OpenSolaris on the go and even vaguely recall having a look at one of the BSD's. However, any recent attempt to install one of the latter, and there are quite a few around now, got stymied by some sort of kernel panic caused by using AMD CPU's. With the return to the Intel fold arising from the upgrade of my main home PC last year, it perhaps was time to try again.

The recent release of FreeBSD 10.0 was the cue and I downloaded a DVD image for a test installation in a VirtualBox virtual machine with 4 GB of memory and a 32 GB virtual hard drive attached (expanding storage was chosen so not all the allocated space has been taken so far). The variant of FreeBSD chosen was the 64-bit x86 one, and I set to installing it in there. Though not as pretty in appearance as those in various Linux distros, the installer was not that user unfriendly to me. Mind you, I have experience of installing Arch Linux, which might have acclimatised me somewhat.

Those installation screens ask about the keyboard mapping that you want, and I successfully chose one of the UK options. There was limited opportunity for adding extras, though there was a short list of a few from which I made some selections. Given that user account set up also was on offer, I would have been better off knowing what groups to assign for my personal user account to have to avoid needing to log in as root so often following system start up later. Otherwise, all the default options were sufficient.

When the installation process was complete, it was time to boot into the new system and all that was on offer was a command line log in session. After logging in as root, it was time to press pkg into service to get a desktop environment in place. The first step was to install X:

pkg install xorg

Then, it was time to install a desktop environment. While using XFCE or KDE were alternatives, I chose GNOME 2 due to familiarity and more extensive instructions on the corresponding FreeBSD handbook page. Issuing the following command added GNOME and all its helper applications:

pkg install gnome2

So that GNOME starts up at the next reboot, some extra steps are needed. The first of these is to add the following line into /etc/fstab:

proc /proc procfs rw 0 0

Then, two lines were needed in /etc/rc.conf:

gdm_enable="YES" gnome_enable="YES"

The first enables the GNOME display manager, while the second activates other GNOME programs that are needed for a desktop session to start. With each of these in place, I got a graphical login screen at the next boot time.

With FreeBSD being a VirtualBox Guest, it was time to consult the relevant FreeBSD manual page. Here, there are sections for a number of virtual machine tools, so a search was needed to find the one for VirtualBox. VirtualBox support for FreeBSD is incomplete in that there is no installation media for BSD systems, while Linux and Solaris are supported along with Windows. Therefore, it is over to the FreeBSD repositories for the required software:

pkg install virtualbox-ose-additions

Aside from the virtual machine session not capturing and releasing the mouse pointer automatically, that did everything that was needed, even if it was the open source edition of the drivers and their proprietary equivalents. To resolve the mouse pointer issue, I needed to temporarily disable the GNOME desktop session in /etc/rc.conf to drop to a console only session where xorg.conf could be generated using the following commands:

Xorg -configure cp xorg.conf.new /etc/xorg.conf

In the new xorg.conf file, the mouse section needs to be as follows:

Section "InputDevice" Identifier "Mouse0" Driver "vboxmouse" EndSection

If it doesn't look like the above, and it wasn't the case for me, then it needs changing. Also, any extra lines from the default set up also need removing, or the mouse will not function as it should. The ALT+F1 (for accessing GNOME menus) and ALT+F2 (for running commands) keyboard shortcuts then become crucial when your mouse is not working as it should and could avert a panic too; knowing that adjusting a single configuration file will resolve a problem when doing so is less accessible is not a good feeling as I discovered to my own cost. The graphics settings were fine by default, but here's what you should have in case it isn't for you:

Section "Device" ### Available Driver options are:- ### Values: <i>: integer, <f>: float, <bool>: "True"/"False", ### <string>: "String", <freq>: "<f> Hz/kHz/MHz" ### [arg]: arg optional Identifier "Card0" Driver "vboxvideo" VendorName "InnoTek Systemberatung GmbH" BoardName "VirtualBox Graphics Adapter" BusID "PCI:0:2:0" EndSection

The next step is to ensure that your HAL settings are as they should. I needed to create a file in /usr/local/etc/hal/fdi/policy called 90-vboxguest.fdi that contains the following:

<?xml version="1.0" encoding="utf-8"?>  <deviceinfo version="0.2"> <device> <match key="info.subsystem" string="pci"> <match key="info.product" string="VirtualBox guest Service"> <append key="info.capabilities" type="strlist">input</append> <append key="info.capabilities" type="strlist">input.mouse</append> <merge key="input.x11_driver" type="string">vboxmouse</merge> <merge key="input.device" type="string">/dev/vboxguest</merge> </match> </match> </device> </deviceinfo>

With all that set, it is time to ensure that the custom user account is added to the wheel and operator groups using this command:

pw user mod [user name] -G wheel operator

Executing the above as root means that the custom account can run the su command so that logging in as root at the start of a desktop session no longer is needed. That is what being in the wheel group allows, so anyone in the operator group can shut down or restart the system. Since both are facilities readily available on Linux, so I fancied having them in FreeBSD too.

Being able to switch to root in a terminal session meant that I could go on to add software like Firefox, LibreOffice, GIMP, EMACS, Geany, NetBeans, Banshee and so on. Though there may be a line of opinion that FreeBSD is a server operating system, all of these make it more than passable for serving as a desktop one too. There may be no package management GUI as such and the ones that come with GNOME do not work either, yet anyone familiar with command line working will get around that.

While FreeBSD may be conservative, that has its place too, and being able to build up a system one item at a time teaches far more than getting everything already sorted in one hit. So far, there is enough documentation to get me going, leaving me to see where else things go too. So far, the OS hasn't been that intimidating, which is good to see.

VMware Workstation in full screen mode hobbles my keyboard

14^th May 2008

Recently, I have encountered an odd situation following my recent upgrade to Ubuntu 8.04: when I use VMware Workstation to run Windows XP in full screen mode, the keyboard no longer acts as it should. For instance, the Caps Lock and Num Lock keys stop working, as does the Shift key. Logging out and back in again is the least that's needed to set things right, but there has to be a better way to resolve the problem. While I am not saying that it's limited to the scenario where I saw it happen, it's still very odd behaviour. If you have a solution, please let me know. Of course, I'll keep you posted if I find one. Meanwhile, I'll be avoiding full screen mode with VMware as much as I can.

Update 1:

I have done a spot of digging on this one since and gained the impression that there might be a conflict between VMware and the version of X.org Server that comes with Ubuntu. A restorative trick that I have seen suggested is to issue the following command in a terminal, replacing "gb" with your own locale, but I have yet to see if it works:

setxkbmap -rules xorg -layout "gb"

In any case, it looks as if it is not a permanent fix but just a way to keep working without resorting to system restarts, logging off and back on, etc.

Update 2:

I can now verify that the command quoted above works for me. Of course, it would better to find a permanent fix and even better for the behaviour never to occur at all. For now, though, any fix is better than none whatsoever.