VNCpilot - Simple And Secure Remote Access

Version 21
Visibility: Open to anyone




    This document and VNCpilot are Copyright © 2018, 2019 Dude! @ Oracle Communities and are presented under the terms and conditions of using the Oracle Web sites according to

    VNCpilot is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3 as published by the Free Software Foundation. VNCpilot is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. Please see




    2     Introduction


    2.1     Why VNCpilot


    Modern Enterprise Linux server systems do not necessarily deploy a windowing system. Starting with Red Hat Enterprise Linux 6, a graphical user desktop is no longer installed when choosing a minimal or basic server installation. System administration is typically accomplished over the network using Secure Shell (SSH) command line. Several products, however, such as Oracle database installation and administration tools, for example, rely on a graphical user interface (GUI) and hence require a windowing system.


    Virtual Network Computing (VNC) is often the preferred remote access solution because viewer connections can be disconnect without disrupting the remote process in progress. VNCpilot provides a turnkey solution to create or delete a VNC service that meets modern networking and security standards, without the need to install X Window, or to have a keen understanding of the technical concepts involved. If you can use secure shell (SSH) to connect to your Linux system, you can also use VNCpilot and a VNC viewer to run remote GUI applications from your Microsoft Windows, Apple OS/X, or Linux desktop.




    X Window Remote Access Concepts.



    2.2     How it Works


    VNCpilot is a professional Linux shell script to configure a systemd service based on TigerVNC server. Besides creating the service ad hoc, it can also completely remove the service when no longer required. This can be done by simply running VNCPilot with the create or delete command line argument.


    TigerVNC provides a virtual desktop that can be displayed by a VNC viewer. In order to configure the service, VNCpilot creates a regular user account with a machine specific user name and system generated password. The user account created by VNCpilot runs the VNC service and can be used to establish the initial connection if necessary.


    The service created by VNCpilot requires that users are authenticated by the host operating system and enter a VNC password. VNC connections are only allowed when addressed to the computer itself (localhost). The service will not respond to connections made from other computers on the network. Remote VNC access however can be established using a secure shell (SSH) tunnel. All necessary information will be shown in the VNCpilot summary screen when creating the VNC service.


    VNCpilot does not compromise system privacy or security. It does not phone home, or transmit, or collect any information.



    2.3     Video Demo


    The following is a 4 minute video showing how to use VNCpliot to create and delete a VNC service, and how to establish the VNC session.




    3     Getting Started


    3.1     Requirements


    VNCpilot was developed and tested under Oracle Linux and should work with any Linux distribution based on Red Hat Enterprise Linux 7 and 8.


    Depending on your OS installation, yum will automatically install the following software dependencies:


    • tigervnc-server
    • gnome-terminal
    • metacity
    • dejavu-sans-mono-fonts
    • dejavu-fonts-common
    • dejavu-serif-fonts
    • dejavu-sans-fonts
    • xorg-x11-apps (EL 7)
    • xorg-x11-utils


    This may require around  228 MB of additional disk space with a minimal server installation.



    NoteStarting with RHEL 7, twm (Tab Window Manager) is no longer supported. Also xterm does not function properly depending on VNC viewer and OS platform.




    3.2     Installation


    You can download the software package (RPM) matching your Linux release version from the following pages:


    VNCpilot for OL/EL 7

    VNCpilot for OL/EL 8


    You need to login as root or use sudo to install the software. For example:


    [root@localhost ~]# yum install vncpilot-1.0.2-1.el7.x86_64.rpm


    [root@localhost ~]# sudo yum install vncpilot-1.1-1.el8.x86_64.rpm



    You can also use yum and the actual URL to install the software:


    yum install


    yum install


    If fetching the installation rpm using YUM fails, please verify that date and time of your Linux server are set correctly. This is necessary for the SSL certificate to work. If you are using a virtual machine, date and time may be set incorrectly.




    Starting with the April 2018 update of Microsoft Windows 10, the OpenSSH client is installed by default, which includes scp and sftp to transfer files between your PC and Linux server.


    If you use a previous version of Microsoft Windows, you can download some 3rd party software from the Internet. For example, WinSCP, which is a popular and free open-source tool available at:




    3.3     Creating the VNC Service


    TipVNCpilot works with the systemd init and service manager and requires root access. You can however create a special suoders group and allow other users to run VNCpilot as root.


    Please see chapter 6.1 for more info.


    Use the create argument to set up and configure a new secure VNC service. This will automatically create a regular user account with a machine specific user name and system generated password. The VNC service will only listen to local connections on TCP port 5995 (localhost) and also require a VNC display password.


    Login to the Linux server and run VNCpilot with the create argument:


    vncpilot -c



    The create argument accepts additional options.

    See chapter 4.2 and 4.3 for more information. For example:


    vncpilot --create -shared -size=1280x800


    The Service Summary displays all information required to establish the VNC connection:






    The password displayed in the Service Summary and can not be displayed or retrieved otherwise. The passwords for the VNC user account and VNC session screen are the same.


    If you need to reset the password, simply delete and recreate the service or reset the password as outlined in chapter 6.2  Reset Password.




    3.4     Establishing the SSH Tunnel


    The SSH tunnel will create a local network listening port (TCP 5901) on your desktop PC and establish a connection to the corresponding network listening port at the remote VNC server (TCP 5995). Open a terminal window or command prompt on your PC desktop and enter the ssh command as shown in the VNCpilot Service Summary screen.






    You can use the user account created by VNCpilot or any other account to create the SSH tunnel. The VNC session however will be established under the VNC user account.



    Apple Mac OS/X, Linux desktop systems and Microsoft Windows 10 (April 2018) ship with a SSH client and no additional installation is required. If you use an older version of Microsoft Windows please see Appendix A, which outlines the procedure using PuTTy.




    3.5     Establishing the VNC session


    You need to create the SSH tunnel as outlined in the previous chapter before you can start the VNC session.


    3.5.1     Mac OS/X


    Apple Mac OS/X ships a VNC viewer (Screen Sharing) and does not require any additional software installation.


    1. Select Go from the Finder Menu and 
        choose Connect to Server
        (or Press Command-k)

    2. Enter the following in the Server

        Address field: vnc://localhost:5901

    3. Click the Connect button.

    (click image to enlarge)

    4. Enter the VNC password as shown in

        the VNCpilot Summary Screen. The

        password for the VNC user account

        and VNC display are identical.


    5. You are now connected to a virtual 
        desktop of the Linux server. You can
        use the right mouse button or
        control-click to exchange copy and
        paste buffers between Mac OS/X and
        the remote Linux terminal.



    3.5.2     Microsoft Windows


    Microsoft Windows ships with Remote Desktop, which relies on Microsoft RDP and is not compatible with VNC. However, there are several open-source VNC viewers available that you can download from the Internet and use for free.



    Install a VNC viewer e.g.: TigerVNC viewer


    You only need to download the VNC viewer, e.g.: vncviewer64-1.8.0.exe

    (click to enlarge image)

    1. Open the VNC viewer.

    2. Enter the following in the VNC server field:


    3. Click the Connect button.

    (click to enlarge image)

    3. Enter the VNC password as shown in the

        VNCpilot Summary Screen. The password 
        for the VNC user account and VNC display
        are the same.

    4. You are now connected to a virtual desktop
        on the Linux server. Use the right mouse
        button to exchange copy and paste buffers
        between Microsoft Windows and Linux.



    3.5.3     Linux Desktop


    Linux Desktop distributions, such as Ubuntu, generally ship with a VNC viewer and no additional software installation should be required.


    1. In Ubuntu 18.04, select Activities
        and enter Rem in the search field.

    2. Open Remmina.

    (click image to enlarge)

    3. Select VNC and enter localhost:5901

    4. Enter the VNC password as shown in the
        VNCpilot Summary Screen. The password
        for the VNC user account and VNC display
        are the same.

    5. You are now connected to a virtual desktop
        on the Linux server. Use the right mouse
        button to exchange copy and paste buffers
        between the remote terminal and your Linux
        desktop computer.



    3.5.4     Java Cross Platform


    TightVNC java provides SSH and allows you to connect to a VNC server without the need to use a separate SSH client to create the necessary SSH tunnel.



    A Java application can be deployed as a standalone application or Java archive. To open a Java archive (JAR) file, you must have the Java Runtime Environment installed (Java JRE).



    Download the TightVNC viewer from:


    Look for the TightVNC Java Viewer:

    1. Open tightvnc-jviewer.jar

    2. Enter localhost and 5995 into the

        Remote Host and Port field.
        Enter the TCP/IP address or hostname
        into the SSH server field. Use 22 for the
        SSH Port (standard) and type the VNC

        username in the SSH user field.

    (click image to enlarge)

    3. Enter the VNC user account password
        according to the VNCpilot Summary

    4. Enter the VNC display password, which

        is the same as for the VNC user account.

    5. You are now connected to a virtual
        desktop on the Linux server.




    3.6     Deleting the VNC service


    You can remove the VNC service at any time.


    vncpilot -d



    All corresponding VNC connections and processes will be aborted. The VNC service, VNC user account and login directory will be erased. Other VNC services that may exist will not be affected.







    4     Additional Commands and Options


    VNCPilot offers a few more additional options, beside creating or deleting a VNC service.



    4.1     Help


    You can display the built-in help screens to see what options are available.


    vncpilot -h





    4.2     Shared


    By default, the VNC service configuration created by VNCpilot does not permit to share the VNC display among multiple VNC viewers. Any subsequent VNC client connection will seamlessly resume the existing VNC session and disconnect the previous client. To allow multiple VNC clients to share the same VNC session, add the shared parameter when creating the VNC service.


    vncpilot -c -shared



    4.3     Size


    The default VNC screen resolution is 1024x768, which is an old standard.


    You can specify the size parameter as shown in the table below to use a different screen resolution.


    Screen size15" or less16" - 19"20" - 22"23" or moreHDTV
    Classic (4:3)1024x7681280x10241600x1200


    For example:


    vncpilot -c -size=1280x800



    4.4     Reload


    You can reload the VNC service to disconnect corresponding VNC clients and to abort all related system processes.


    vncpilot -r



    All corresponding VNC connections and processes will be aborted. The VNC session will reset to default and display the terminal window. Other VNC services that may exist will not be affected.






    4.5     Status


    Use the status argument to show information about the VNC service. It will show VNC service attributes and whether or not the VNC service is ready to accept connections.


    vncpilot -s



    The status information will not show the VNC user and display password.







    5     Uninstalling VNCpilot


    You can use yum to uninstall VNCpilot:


    yum remove vncpilot



    6     Troubleshooting


    VNCpilot provides feedback when processing information and running into problems.


    This chapter describes the rather unusual errors.



    6.1     Insufficient Privileges


    If your user account does not have root access, you will see the following error:


    %vncpilot-E-102, insufficient privileges.


    Since VNCpilot configures a system service it must be run as root. Either login as root, or configure sudoers to let regular system users run VNCpilot as root. The following demonstrates how to create a special sudoers group named vncpilot. Any user who is a member of this group can run VNCpilot.


    For simplicity, you may add an appropriate variable named vncpilot to the user's login profile.


    groupadd vncpilot

    echo "%vncpilot ALL=/usr/local/bin/vncpilot" > /etc/sudoers.d/vncpilot

    usermod -a -G vncpilot oracle

    echo "vncpilot='sudo /usr/local/bin/vncpilot'" >> /home/oracle/.bashrc


    User oracle can now use $vncpilot at the next login. Note the $ sign, which refers to a variable.


    When prompted for password, the user must enter the own account login password.





    6.2     Reset Password


    The easiest way to reset the password of the VNC user account and VNC display is to simply create a new VNC service.


    vncpilot -d

    vncpilot -c


    You can set your own passwords if you do not wish to delete and abort the current VNC account or task in progress. The password will be effective immediately:


    su - root

    passwd [VNC user]

    su - [VNC user]






    6.3     Port in Use


    %vncpilot-E-179, TCP port 5995 already in use.


    TCP port 5995 is generally know to be free. It is therefore rather by error that any software other than a VNC service created by VNCpilot is using this port.


    You can use the following to find out more information:


    vncpilot -s

    fuser 5995/tcp

    ps [process id]




    6.4     No Such Command


    %vncpilot-E-118, pkill: no such command.


    VNCpilot relies on core system utilities that should be available in any RHEL 7 based installation. If you see this error, you are missing core system files and may need to reinstall the operating system.



    6.5     Self-integrity Check Failed


    %vncpilot-E-93, self-integrity check failed.


    VNCpilot automatically verifies its own script integrity. This error indicates that VNCpilot was inappropriately modified or the file is damaged and needs to be reinstalled.



    6.6     No VNC Terminal


    Your remote VNC session will show a blank desktop when you close the last terminal window.




    To reset your VNC session back to default, simply reload the service and reconnect:


    vncpilot -r



    6.7     Unkown Vncservice Template


    %vncpilot-W-169, unkown vncservice template.

    Do you wish to abort?

    Enter (Y)es or (N)o, or (A)bort: [y]


    This may happen if the /lib/systemd/system/vncserver@.service file has been modified or the system was upgraded. You may continue and see if the VNC service will work, but it is likely to fail. It is safe to respond with No or Abort and install a VNCpilot update.




    Appendix A


    PuTTY is a popular free and open-source SSH client for Microsoft Windows:



    1. Start PuTTY and select SSH, Tunnels.
    In the Source port field, type 5901.
        In the Destination field, type localhost:5995.

        Click the Add button.

    (click image to enlarge)

    3. Select Session and type the TCP/IP address or fully
        qualified host name of the remote system (VNC server)
        in the Host Name field.
        Type any name in the Saved Session field.
        Click the Save button.

    4. Select the Open button to connect.

    5. Enter username and password according to the VNCpilot
        Summary Screen.

    6. You can click on the PuTTY icon in the top left corner to

        display the event log and verify that local port 5901 has been
        forwarded to 5995.



    # End