Remote-desktop to a host using VNC

This guide describes how to use VNC to connect to a remote Clear Linux* OS host.

VNC is a client-server GUI-based tool that allows you to connect via remote-desktop to your Clear Linux OS host.

Install the VNC server and misc. components on your host

To configure VNC to work on your Clear Linux OS host, install these bundles:

• desktop-autostart: Installs GDM, sets it to start automatically on boot, and installs TigerVNC Viewer.

• vnc-server: Installs the TigerVNC server.

Follow these steps:

1. Open a terminal window.

2. Install the Clear Linux OS bundles.

   sudo swupd bundle-add desktop-autostart vnc-server
   

3. Reboot your Clear Linux OS host.

Configure a VNC-server-start method on your host

There are three methods you can use to configure and start the VNC server on your Clear Linux OS host:

Table 1: VNC-server-start Configuration Methods

Attribute	Method 1: Manually start a VNC session	Method 2: Automatically start a VNC session via a systemd service script	Method 3: Create multi-user logins with authentication through GDM
Description	This is the traditional method where you SSH into the Clear Linux OS host, manually start a VNC session to get a display ID, and connect to it by supplying the display ID.	The system administrator sets up a systemd service script for you with a pre-assigned display ID. You make a VNC connection and supply your pre-assigned display ID.	The system administrator configures GDM to accept connection requests. When you make a VNC connection to the Clear Linux OS host, you see the GDM login screen and authenticate as if you are local.
Who configures VNC settings?	You	System administrator	System administrator
Who starts VNC session?	You	Set to start automatically on boot by system administrator	Set to start automatically on boot by system administrator
Who ends VNC session?	You	You	System administrator can disable VNC service altogether
Requires VNC password to authenticate?	Yes	Yes	No. Use Clear Linux OS account username and password through GDM

Although all three methods can coexist on the same Clear Linux OS host, we recommend you pick a method that suits your needs.

For simplicity, the rest of this guide refers to these methods as Method 1, Method 2, and Method 3.

Method 1: Manually start a VNC session

You (and each user) must perform these steps to initialize your VNC settings.

1. Log in.

2. Open a terminal window.

3. Start VNC with the vncserver command. Since this is your first time starting VNC, it adds default configuration files and asks you to set a VNC password.

   vncserver
   

   Example output:

   You will require a password to access your desktops.
   
   Password:
   Verify:
   Would you like to enter a view-only password (y/n)? n
   xauth:  file /home/vnc-user-a/.Xauthority does not exist
   
   New 'clr-linux:2 (vnc-user-a)' desktop is clr-linux:2
   
   Creating default startup script /home/vnc-user-a/.vnc/xstartup
   Creating default config /home/vnc-user-a/.vnc/config
   Starting applications specified in /home/vnc-user-a/.vnc/xstartup
   Log file is /home/vnc-user-a/.vnc/clr-linux:2.log
   

   Upon completion, you can find the default configuration files and the password file hidden in the .vnc directory in your home directory.

   A VNC session starts and shows a unique display ID, which is the number following the hostname and the colon “:”. In the above example, the display ID is 2. In a later step, you will supply the display ID to your VNC viewer app for connection.

4. Kill the active VNC session for the time being with the vncserver -kill :[display ID] command. Substitute [display ID] with your active VNC session display ID. For example:

   vncserver -kill :2
   

   Note

   If you do not recall the active session display ID, use the vncserver -list command to find it.

5. Optional configurations:

   • To customize settings such as screen size, security type, etc., modify the $HOME/.vnc/config file.

   • To customize the applications to run at startup, modify the $HOME/.vnc/xstartup file.

Method 2: Automatically start a VNC session via a systemd service script

To configure VNC for this method, you must have root privileges. You will set up a systemd service file for all intended VNC users with their own preassigned unique display ID.

1. Log in.

2. Make sure the user accounts already exist. Use the following command to list all users.

   sudo cut -d: -f1 /etc/passwd
   

3. Create the path /etc/systemd/system.

   sudo mkdir -p /etc/systemd/system
   

4. Create a systemd service script file vncserver@:[X].service, where [X] is the display ID, for each user in /etc/systemd/system Each user must be assigned a unique display ID. Be sure the correct username is entered in the User field. The example below shows user vnc-user-b who is assigned the display ID 5.

   sudo tee -a /etc/systemd/system/vncserver@:5.service << EOF
   
   [Unit]
   Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
   After=syslog.target network.target
   
   [Service]
   Type=simple
   User=vnc-user-b
   PAMName=login
   PIDFile=/home/%u/.vnc/%H%i.pid
   ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :'
   ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -alwaysshared -fg
   ExecStop=/usr/bin/vncserver -kill %i
   
   [Install]
   WantedBy=multi-user.target
   
   EOF
   

5. Have each user log into their account and set a VNC password with the vncpasswd command before proceeding to the next step.

6. Start the VNC service script and set it to start automatically on boot for each user. Replace the [X] with the display ID.

   sudo systemctl daemon-reload
   sudo systemctl enable vncserver@:[X].service
   sudo systemctl start vncserver@:[X].service
   

7. After starting the services, verify they are running.

   systemctl | grep vnc
   

   The example below shows 2 VNC sessions that were successfully started for users vnc-user-b with display ID 5 and vnc-user-c with display ID 6.

   systemctl | grep vnc
   
   vncserver@:5.services   loaded active running  VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
   vncserver@:6.services   loaded active running  VNC Remote Desktop Service for "vnc-user-c" with display ID "6"
   system-vncserver.slice  loaded active active system-vncserver.slice
   

Method 3: Multi-user logins with authentication through GDM

For this method, VNC is configured as a systemd service that listens on port 5900 and GDM is configured to accept access requests from VNC. When you make a VNC connection to your Clear Linux OS host, you are presented with the GDM login screen and you authenticate as if you are local. You must have root privileges to perform this configuration.

1. Log in.

2. Create the path /etc/systemd/system.

   sudo mkdir -p /etc/systemd/system
   

3. Create a systemd socket file xvnc.socket with the following content:

   sudo tee -a /etc/systemd/system/xvnc.socket << EOF
   
   [Unit]
   Description=XVNC Server on port 5900
   
   [Socket]
   ListenStream=5900
   Accept=yes
   
   [Install]
   WantedBy=sockets.target
   
   EOF
   

4. Create a systemd service file xvnc@.service with the following content:

   sudo tee -a  /etc/systemd/system/xvnc@.service << EOF
   
   [Unit]
   Description=Daemon for each XVNC connection
   
   [Service]
   ExecStart=-/usr/bin/Xvnc -inetd -query localhost -geometry 2000x1200 -once -SecurityTypes=None
   User=nobody
   StandardInput=socket
   StandardError=syslog
   
   EOF
   

5. Create the path /etc/gdm.

   sudo mkdir -p /etc/gdm
   

6. Create a GDM custom.conf file with the following content:

   sudo tee -a /etc/gdm/custom.conf << EOF
   
   [xdmcp]
   Enable=true
   Port=177
   
   EOF
   

7. Start the VNC socket script and set it to start automatically on boot.

   sudo systemctl daemon-reload
   sudo systemctl enable xvnc.socket
   sudo systemctl start xvnc.socket
   

8. After starting the socket, verify it is running.

   systemctl | grep vnc
   

   The example below shows the xvnc.socket is running.

   systemctl | grep vnc
   
   xvnc.socket               loaded active listening XVNC Server on port 5900
   system-xvnc.slice         loaded active active    system-xvnc.slice
   

See the vncserver Man page for additional information.

Install a VNC viewer app and an SSH client on your client system

You need a VNC viewer app on your client system to connect to your Clear Linux OS host. An SSH client is only needed if you chose to use Method 1 or you plan to encrypt your VNC traffic, which is discussed later in this guide.

Perform the steps below to add these apps to your client system.

Install a VNC viewer app

On Clear Linux OS:

sudo swupd bundle-add desktop-autostart

On Ubuntu*, Mint*:

sudo apt-get install xtightvncviewer

On Fedora*:

sudo dnf install tigervnc

On Windows*:

• Install RealVNC for Windows

On macOS*:

• Install RealVNC for macOS

Install an SSH client

• On most Linux distros (Clear Linux OS, Ubuntu, Mint, Fedora, etc.) and macOS, SSH is built-in so you don’t need to install it.

• On Windows, you can install Putty.

Establish a VNC connection to your host

Depending on the VNC-server-configuration method chosen, use the appropriate VNC connection:

• If you chose Method 1, you must take a few extra steps by using SSH to connect to your Clear Linux OS host and then manually launching VNC.

• If you chose Method 2, get your preassigned VNC display ID from your system administrator first and then proceed to the Connect to your VNC session section below.

• If you chose Method 3, proceed to the Connect to your VNC session below.

SSH into your host and launch VNC

1. SSH into your Clear Linux OS host

   1. On Linux distros and macOS:

      ssh [username]@[clear-linux-host-ip-address]
      

   2. On Windows:

      1. Launch Putty.

      2. Under the Category section, select Session. See Figure 1.

      3. Enter the IP address of your Clear Linux OS host in the Host Name (or IP address) field.

      4. Set the Connection type option to SSH.

      5. Click the Open button.

         

         Figure 1: Putty - configure SSH session settings

2. Log in with your Clear Linux OS username and password. Do not use your VNC password.

3. Start a VNC session.

   vncserver
   

   Example output:

   New 'clr-linux:3 (vnc-user-c)' desktop is clr-linux:3
   
   Starting applications specified in /home/vnc-user-c/.vnc/xstartup
   Log file is /home/vnc-user-c/.vnc/clr-linux:3.log
   

4. Take note of the generated display ID because you will input it into the VNC viewer app to establish the connection. The above example shows the display ID is 3.

   Note

   VNC automatically picks a unique display ID unless you specify one. To specify a display ID, enter a unique number that is not already in use after the colon. For example:

   vncserver :8
   

5. You can now end the SSH connection by logging out. This does not terminate your active VNC session.

Connect to your VNC session

For Method 1 and Method 2, you must connect to a specific active session or display ID using one of two options:

• Use a fully-qualified VNC port number, which consists of the default VNC server port (5900) plus the display ID

• Use the display ID

For example, if the display ID is 3, it can be specified as 5903 or just as 3. For Method 3, VNC does not expect a display ID. Use 5900. For simplicity, the instructions below use the fully-qualified VNC port number.

On Linux distros:

1. Open a terminal window and enter:

   vncviewer [clear-linux-host-ip-address]:[fully-qualified VNC port  number]
   

2. Enter your credentials.

   • For Method 1 and Method 2, enter your VNC password. No username is required.

   • For Method 3, enter your Clear Linux OS account username and password through GDM.

     Note

     With Method 3, you cannot remotely log into your Clear Linux OS host through VNC if you are logged in locally and vice versa.

On Windows and macOS using RealVNC app:

1. Start the RealVNC viewer app. See Figure 2.

2. Enter the IP address of the Clear Linux OS host and the fully-qualified VNC port number.

   The following screenshot shows connecting to Clear Linux OS host 192.168.25.54 with a fully-qualified VNC port number 5902.

   

   Figure 2: RealVNC Viewer

3. Press the Enter key.

4. Enter your credentials.

   • For Method 1 and Method 2, enter your VNC password. No username is required.

   • For Method 3, enter your Clear Linux OS account username and password through GDM.

     Note

     With Method 3, you cannot remotely log into your Clear Linux OS host through VNC if you are logged in locally and vice versa.

Optional: Configure RealVNC Image Quality

To increase the RealVNC viewer image quality, manually change the ColorLevel value. Follow these steps:

1. Right-click a connection node and select Properties…. See Figure 3.

   

   Figure 3: RealVNC Viewer - change connection node properties

2. Select the Expert tab. See Figure 4.

3. Select the ColorLevel setting and change it to your preferred setting.

   

   Figure 4: RealVNC Viewer - change ColorLevel

Terminate a VNC connection to your host

For Method 1 and Method 2, once started, a VNC session remains active on your Clear Linux OS host even if you close your VNC viewer app. If you want to truly terminate an active VNC session, follow these steps:

1. SSH into your Clear Linux OS host.

2. Open a terminal window.

3. Find the active VNC session display ID with the command vncserver -list.

   vncserver -list
   

4. Terminate it with the vncserver -kill command followed by a colon and the display ID.

   vncserver -kill :[display ID]
   

5. For Method 3, only the system administrator can stop and disable the VNC service by using these commands:

   sudo systemctl stop xvnc.socket
   sudo systemctl disable xnvc.socket
   

Encrypt VNC traffic through an SSH tunnel

By default, VNC traffic is not encrypted. Figure 5 shows an example warning from RealVNC Viewer.

Figure 5: RealVNC Viewer - Connection not encrypted warning

To add security, VNC traffic can be routed through an SSH tunnel. This is accomplished by following these steps:

1. Configure the VNC server to only accept connection from localhost by adding the -localhost option.

2. Set up an SSH tunnel between your client system and your Clear Linux OS host. Your client system will forward traffic from the localhost (the client) destined for a specified fully-qualified VNC port number (on the client) to your Clear Linux OS host with the same port number.

3. The VNC viewer app on your client system will now connect to localhost, instead of the IP address of your Clear Linux OS host.

Configure VNC to only accept connection from localhost

For Method 1:

1. Edit the config file located in $HOME/.vnc and uncomment the # localhost line. It should look like this:

   ## Supported server options to pass to vncserver upon invocation can be listed
   ## in this file. See the following manpages for more: vncserver(1)
   Xvnc(1).
   ## Several common ones are shown below. Uncomment and modify to your liking.
   ##
   # securitytypes=vncauth,tlsvnc
   # desktop=sandbox
   # geometry=2000x1200
   localhost
   # alwaysshared
   

2. If an active session exists, kill it, and then restart it.

For Method 2:

1. Edit the systemd service script vncserver@:[X].service located in /etc/systemd/system and add -localhost to the ExecStart line. The example below uses vncserver@:5.service:

   [Unit]
   Description=VNC Remote Desktop Service for "vnc-user-b" with display ID "5"
   After=syslog.target network.target
   
   [Service]
   Type=simple
   User=vnc-user-b
   PAMName=login
   PIDFile=/home/%u/.vnc/%H%i.pid
   ExecStartPre=/bin/sh -c '/usr/bin/vncserver -kill %i > /dev/null 2>&1 || :'
   ExecStart=/usr/bin/vncserver %i -geometry 2000x1200 -localhost -alwaysshared -fg
   ExecStop=/usr/bin/vncserver -kill %i
   
   [Install]
   WantedBy=multi-user.target
   

2. Restart the service script:

   sudo systemctl daemon-reload
   sudo systemctl restart vncserver@:5.service
   

For Method 3:

1. No change is needed to the xvnc@service script.

   After you have restarted your VNC session, you can verify that it only accepts connections from localhost by using the netstat command like this:

   netstat -plant
   

   Note

   Add the Clear Linux OS network-basic bundle to get the netstat command.

Figure 6 shows two VNC sessions (5901 and 5905) accepting connections from any host as specified by the 0.0.0.0’s. This is before the -localhost option was used.

Figure 6: VNC sessions (5901 and 5905) accepting connections from any host

Figure 7 shows two VNC sessions (5901 and 5905) only accepting connections from localhost as specified by 127.0.0.1’s. This is after the -localhost option was used.

Figure 7: VNC sessions (5901 and 5905) only accepting connections from localhost

Set up an SSH tunnel from your client system to your Clear Linux OS host

On Linux distros and macOS:

1. Open terminal window and enter:

   ssh -L [client port number]:localhost:[fully-qualified VNC port number] \
   -N -f -l [username] [clear-linux-host-ip-address]
   

2. Enter your Clear Linux OS account password (not your VNC password).

   Note

   • -L specifies that [client port number] on the localhost (on the client side) is forwarded to [fully-qualified VNC port number] (on the server side).

   • Replace [client port number] with an available client port number (for example: 1234). For simplicity, you can make the [client port number] the same as the [fully-qualified VNC port number].

   • Replace [fully-qualified VNC port number] with 5900 (default VNC port) plus the display ID. For example, if the display ID is 2, the fully-qualified VNC port number is is 5902.

   • -N tells SSH to only forward ports and not execute a remote command.

   • -f tells SSH to go into the background before command execution.

   • -l specifies the username to log in as.

On Windows:

1. Launch Putty.

2. Specify the Clear Linux OS VNC host to connect to.

   1. Under the Category section, select Session. See Figure 1.

   2. Enter the IP address of your Clear Linux OS host in the Host Name (or IP address) field.

   3. Set the Connection type option to SSH.

3. Configure the SSH tunnel. See Figure 8 for an example.

   1. Under the Category section, go to Connection > SSH > Tunnels.

   2. In the Source port field, enter an available client port number (for example: 1234). For simplicity, you can make the Source port the same as the fully-qualified VNC port number.

   3. In the Destination field, enter localhost: plus the fully-qualified VNC port number.

   4. Click the Add button.

      

      Figure 8: Putty - configure SSH tunnel

4. Click the Open button.

5. Enter your Clear Linux OS account password (not your VNC password).

Connect to a VNC session through an SSH tunnel

After you have set up an SSH tunnel, follow these instructions to connect to your VNC session.

On Linux distros:

1. Open terminal window and enter:

   vncviewer localhost:[client port number]
   

On Windows and macOS using `RealVNC`:

1. Start the RealVNC viewer app.

2. Enter localhost and the fully-qualified VNC port number. See Figure 9 for an example.

   

   Figure 9: RealVNC viewer app connecting to localhost:1234

   Note

   RealVNC will still warn that the connection is not encrypted even though its traffic is going through the SSH tunnel. You can ignore this warning.