Initialize VNC Remote Access (Linux Client)

On a Linux client, after logging into the 10888 web console (see Update Linux Client Data), an "Initialize VNC" card appears. One click configures VNC and reports it to the console, which can then connect to this client remotely. In the vast majority of cases this is fully automatic — no manual setup needed; only when the automatic flow is blocked by the environment (x11vnc missing, a Wayland desktop, etc.) do you need the "Manual handling" section below.

What one-click initialization does

After you click "Initialize VNC", the client (vdclient, running as root) automatically does the following in order:

1. Disables the Apport crash popup (Ubuntu/Debian only): prevents the "System program problem detected" window from popping up over the desktop that is about to be taken over, in case installing x11vnc fails.
2. Checks the desktop session type: if it is a Wayland session, x11vnc cannot capture the screen, so it guides you to switch to Xorg (see Case 2 below).
3. Ensures x11vnc is installed: if missing, it auto-installs online via the distro package manager (apt / dnf / yum / zypper / pacman).
4. Generates an 8-character dynamic random password and writes it to the VNC password file.
5. Auto-discovers the graphical session's DISPLAY and XAUTHORITY and starts x11vnc on :0 at port 9015.
6. Reports the IP, port 9015 and dynamic password to the boot server automatically, so the console can connect remotely — you never enter a password.
7. Writes an auto-start marker: from then on, every time the client boots, vdclient automatically brings VNC back up once the desktop and server are ready — no need to click again.

The VNC port is fixed at 9015; the control password is a random one generated dynamically on each initialization and reported to the console automatically — it cannot and need not be set manually.

Automatic initialization steps

1. On the client machine itself, open http://localhost:10888 in a browser and log in with the admin account (default admin / 123456).
2. On the "Initialize VNC" card, click the "Initialize VNC" button.
3. The message "VNC initialized" means success — the console can now connect remotely.

Manual handling when the software can't do it automatically

If the click reports a failure, handle it according to the case below. Afterwards, go back to the console and click "Initialize VNC" again — you must retry via the button, because only the button reports the VNC information to the console; starting x11vnc by hand alone does not report it, and the console cannot connect.

Case 1: x11vnc not found and auto-install failed

Common when the client has no network access or no package repository configured. The message looks like "x11vnc not found and auto-install failed, please install manually: apt-get install -y x11vnc".

Install x11vnc manually in the client's terminal according to the system type (vdclient runs as root; manual install also needs root):

System	Install command
Ubuntu / Debian / Kylin / UOS (deb-based)	apt-get install -y x11vnc
openEuler / Anolis / RHEL / CentOS (newer)	dnf install -y x11vnc
RHEL / CentOS (older)	yum install -y x11vnc
openSUSE	zypper install x11vnc
Arch	pacman -S x11vnc

If x11vnc is not in the repository, first configure a working repository (or download x11vnc and its dependencies and install them offline). Once installed, go back to the console and click "Initialize VNC" again.

Case 2: The desktop is Wayland and VNC cannot capture the screen

Desktops such as GNOME use the Wayland compositor by default, but x11vnc captures the screen via X11 and cannot capture the desktop under Wayland. You must switch to an Xorg session.

Automatic switch from the console (recommended): after you click "Initialize VNC", if Wayland is detected, a confirmation dialog appears:

This machine uses a Wayland desktop, where VNC cannot capture the screen. Switching to Xorg will restart the display manager and log out the current desktop session (it returns to Xorg automatically in ~15s). Continue?

After you click OK, the client automatically modifies the GDM config (writes WaylandEnable=false, backing up the original as *.osvbak) and restarts the display manager to switch to Xorg. Once the desktop is back on Xorg (about 15 seconds), click "Initialize VNC" again.

Manual handling if the automatic switch fails: if it reports that the GDM config cannot be found, that restarting the display manager failed, or that the session is still Wayland after switching, operate manually in the client's terminal:

1. Edit the GDM config (/etc/gdm3/custom.conf on Debian/Ubuntu/Kylin/UOS, /etc/gdm/custom.conf on Red Hat-based systems) and add or change in the [daemon] section:

   [daemon]
   WaylandEnable=false

2. Restart the display manager (this logs out the current desktop, so save your work first):

   systemctl restart display-manager

   You can also just reboot the client; or, at the GDM login screen, click the gear at the bottom-right and choose "on Xorg" before logging in.

3. After confirming you are in an Xorg session, go back to the console and click "Initialize VNC" again.

Already set WaylandEnable=false but still Wayland: usually the current session has not re-logged-in — reboot the client or log back in to Xorg, then initialize again.

Case 3: After switching to Xorg, click once more

The automatic Xorg switch logs out and re-logs-in the desktop (about 15 seconds), which interrupts this initialization. Once the desktop is back, go back to the console and click "Initialize VNC" again to finish starting and reporting.

Verification and troubleshooting

• On the client, check whether x11vnc is running on port 9015:

  pgrep -a x11vnc
  ss -lntp | grep 9015

• The startup log is at log/x11vnc.log under the vdclient program directory; use it to diagnose failures (e.g. DISPLAY/XAUTHORITY not found, port in use, capture BadMatch, etc.).

• When the console shows that the client is available for remote connection, the report succeeded.

Notes

This feature is available on Linux clients only; Windows clients use a separate TightVNC link and have no such button.

The client must have a running graphical desktop session (X/Xorg); it cannot be initialized from a plain text terminal or when no desktop is logged in.

Once initialized, it auto-starts on boot — no need to click again after rebooting the client; each time (including auto-start) it regenerates the dynamic password and reports to the console.

Xinchuang clients (Kylin, UOS, openEuler, Anolis, etc.) follow exactly the same flow: handle deb-based systems per the Kylin / UOS row, and Red Hat-based systems per the openEuler / Anolis row.