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

This guide shows you how to:

  • Install the VNC server and misc. components on your Clear Linux OS host.
  • Configure a VNC-server-start method on your Clear Linux OS host.
  • Install a VNC viewer app and an SSH client on your client system.
  • Establish a VNC connection to your Clear Linux OS host.
  • Terminate a VNC connection to your Clear Linux OS host.
  • Encrypt VNC traffic through an SSH tunnel.

Install the VNC server and misc. components on your Clear Linux 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. Log into your Clear Linux OS host and get root privileges.

    $ sudo -s
    
  2. Install the Clear Linux OS bundles.

    # swupd bundle-add desktop-autostart vnc-server
    
  3. Reboot your Clear Linux OS host.

Configure a VNC-server-start method on your Clear Linux host

There are three methods you can use to configure and start the VNC server on your 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 adminstrator 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 adminstrator System adminstrator
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 sesssion? 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 emulator.

  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:

    $ vncserver
    
    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.

    Also, 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 and get root privileges.

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

    # cut -d: -f1 /etc/passwd
    
  3. Create the path /etc/systemd/system.

    # 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.

    # cat > /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.

    # systemctl daemon-reload
    # systemctl start vncserver@:[X].service
    # systemctl enable 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 and get root privileges.

    $ sudo -s
    
  2. Create the path /etc/systemd/system.

    # mkdir -p /etc/systemd/system
    
  3. Create a systemd socket file xvnc.socket and add the following:

    # cat > /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 and add the following:

    # cat > /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.

    # mkdir -p /etc/gdm
    
  6. Create a GDM custom.conf file and add the following:

    # cat > /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.

    # systemctl daemon-reload
    # systemctl start xvnc.socket
    # systemctl enable 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:

# swupd bundle-add desktop-autostart

On Ubuntu, Mint:

# apt-get install xtightvncviewer

On Fedora:

# dnf install tigervnc

On Windows:

On macOS:

Install an SSH client

  • On most Linux distros (Clear Linux, 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 Clear Linux 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 Clear Linux host and launch VNC

  1. SSH into your Clear Linux 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 host in the Host Name (or IP address) field.

      4. Set the Connection type option to SSH.

      5. Click the Open button.

        Putty - configure SSH session settings

        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:

    $ vncserver
    
    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 emulator 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 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.

    RealVNC Viewer

    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.

    RealVNC Viewer - change connection node properties

    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.

    RealVNC Viewer - change ColorLevel

    Figure 4: RealVNC Viewer - change ColorLevel

Terminate a VNC connection to your Clear Linux 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 host.

  2. Open a terminal emulator.

  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:

    # systemctl stop xvnc.socket
    # systemctl disable xnvc.socket
    

Encrypt VNC traffic through an SSH tunnel

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

RealVNC Viewer - Connection not encrypted warning

Figure 6: 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:

    # systemctl daemon-load
    # 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 7 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.

VNC session accepting connection from any host

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

Figure 8 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.

VNC session only accepting connection from localhost

Figure 8: 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 emulator 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 host in the Host Name (or IP address) field.
    3. Set the Connection type option to SSH.
  3. Configure the SSH tunnel. See Figure 9 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.

      Putty - configure SSH tunnel

      Figure 9: 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 emulator 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 10 for an example.

    RealVNC viewer app connecting to localhost:1234

    Figure 10: 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.