TOPIC: CUT
Remote access between Mac and Linux, Part 2: x11vnc for sharing physical desktops
29th October 2025This 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.serviceThen start x11vnc manually in a terminal with increased verbosity:
x11vnc -usepw -display :0 -forever -verbose -o ~/x11vnc_debug.logConnect 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.logLines 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.serviceTo 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.serviceThen 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.targetThe -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.serviceCheck that the service is running:
systemctl status x11vnc.serviceThe 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.
Something to try when you get a message like this caused by a filename with a leading hyphen: "mv: illegal option -- u"
3rd December 2024Recently, I downloaded some WEBP files from Ideogram and attempted to move them to another folder. That is when I got the message that you see in the title of this entry. Because I had not looked at the filenames, I baffled when I got this from a simple command that I had been using with some success until then. Because I was using an iMac, I tried the suggestion of installing coreutils to get GNU mv and cp to see if that would help:
brew install coreutils
The above command gave me gmv and gcp for the GNU versions of mv and cp that comes with macOS. Trying gmv only got me the following message:
gmv: cannot combine --backup with --exchange, -n, or --update=none-fail
The ls command could list all files, but not the WEBP ones. Thus, I executed the following to show what I wanted:
ls | grep -i webp
That got around the problem by doing a subset of the directory listing. It was then that I spotted the leading hyphen. To avoid the problem tripping me up again, I renamed the offending file using this command:
mv -- -iunS9U4RFevWpaju6ArIQ.webp iunS9U4RFevWpaju6ArIQ.webp
Here, the -- switch tells the mv command not to look for any more options and only to expect filenames. When I tried enclosing the filename in quotes, I still got problems, even that might have because I was using double quotes instead of single quotes. Another option is to escape the leading hyphen like this:
mv ./-iunS9U4RFevWpaju6ArIQ.webp iunS9U4RFevWpaju6ArIQ.webp
Once the offending file was renamed, I could move the files to their final location. That could have used the -- option too, saving me an extra command, only for my wanting this not to trip me up again. Naturally, working in Finder might have avoided all this as much as not having a file with a leading hyphen in its name, but there would have been nothing to learn then.
Removing duplicate characters from strings using BASH scripting
30th March 2023Recently, I wanted to extract some text from the Linux command by word number only for multiple spaces to make things less predictable. The solution was to remove the duplicate spaces. This can be done using sed, but you add the complexity of regular expressions if you opt for that solution. Instead, the tr command offers a neater approach. For removing duplicate spaces, the command takes the following form:
echo "test test" | tr -s " "
Since I was piping some text to the command, that is what I have above. The tr command is intended to replace or delete characters, and the -s switch is a shorthand for --squeeze-repeats. The actual character to be deduplicated is passed in quotes at the end; here, it is a space, but it could be anything that is duplicated. The resulting text in this example becomes:
test test
After the processing, there is now only one space separating the two words, which is the solution that I sought. It certainly cut out any variability that I was encountering in my usage.
Picking out a word from a string by its position using BASH scripting
28th March 2023My wanting to execute one command using the text output of another recently got me wondering about picking out a block of characters using its position in a space-delimited list. All this needed to be done from the Linux command line or in a shell script. The output text took a form like the following:
text1 text2 text3 text4
What I wanted in my case was something like the third word above. The solution was to use the cut command with the -d (for delimiter) and -f (for field number) switches. The following yields text3 as the output:
echo "text1 text2 text3 text4" | cut -d " " -f 3
Here, the delimiter is the space character, but it can be anything that is relevant for the string in question. Then, the "3" picks out the required block of text. For this to work, the text needs to be organised consistently and for the delimiters never to be duplicated, though there is a way of dealing with the latter as well.