- 1 Legal Information
- 2 Introduction
- 3 Getting Started
- 4 Additional Commands and Options
- 5 Uninstalling VNCpilot
- 6 Troubleshooting
- Appendix A
1 Legal Information
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 http://www.oracle.com/us/legal/terms/index.html.
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 http://www.gnu.org/licenses/.
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.
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
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:
- xorg-x11-apps (EL 7)
This may require around 228 MB of additional disk space with a minimal server installation.
|Note||Starting with RHEL 7, twm (Tab Window Manager) is no longer supported. Also xterm does not function properly depending on VNC viewer and OS platform.|
You can download the software package (RPM) matching your Linux release version from the following pages:
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 https://community.oracle.com/servlet/JiveServlet/downloadBody/1024832-102-9-193762/vncpilot-1.0.2-1.el7.x86_64.rpm |
|yum install https://community.oracle.com/servlet/JiveServlet/downloadBody/1033119-102-3-193661/vncpilot-1.1-1.el8.x86_64.rpm |
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: https://winscp.net/eng/download.php
3.3 Creating the VNC Service
|Tip||VNCpilot 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:
The create argument accepts additional options.
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.
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.
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.
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:https://www.tightvnc.com/download/2.8.3/tvnjviewer-2.8.3-bin-gnugpl.zip
1. Open tightvnc-jviewer.jar
2. Enter localhost and 5995 into the
Remote Host and Port field.
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
3.6 Deleting the VNC service
You can remove the VNC service at any time.
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.
You can display the built-in help screens to see what options are available.
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|
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 size||15" or less||16" - 19"||20" - 22"||23" or more||HDTV|
|vncpilot -c -size=1280x800|
You can reload the VNC service to disconnect corresponding VNC clients and to abort all related system processes.
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.
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.
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|
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.
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.
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:
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:
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.
PuTTY is a popular free and open-source SSH client for Microsoft Windows: