noVNC Documentation

File: README.md Copy Chapter

noVNC: HTML VNC client library and application Copy Chapter

Description Copy Section

noVNC is both a HTML VNC client JavaScript library and an application built on
top of that library. noVNC runs well in any modern browser including mobile
browsers (iOS and Android).

Many companies, projects and products have integrated noVNC including
OpenStack,
OpenNebula,
LibVNCServer, and
ThinLinc. See
the Projects and companies wiki page
for a more complete list with additional info and links.

Table of contents Copy Section

• News/help/contact
• Features
• Screenshots
• Browser requirements
• Server requirements
• Quick start
• Installation from snap package
• Integration and deployment
• Authors/Contributors

News/help/contact Copy Section

The project website is found at novnc.com.

If you are a noVNC developer/integrator/user (or want to be) please join the
noVNC discussion group.

Bugs and feature requests can be submitted via
github issues. If you have questions
about using noVNC then please first use the
discussion group.
We also have a wiki with lots of
helpful information.

If you are looking for a place to start contributing to noVNC, a good place to
start would be the issues that are marked as
"patchwelcome".
Please check our
contribution guide though.

If you want to show appreciation for noVNC you could donate to a great non-
profits such as:
Compassion International,
SIL,
Habitat for Humanity,
Electronic Frontier Foundation,
Against Malaria Foundation,
Nothing But Nets, etc.

Features Copy Section

• Supports all modern browsers including mobile (iOS, Android)
• Supported authentication methods: none, classical VNC, RealVNC's
  RSA-AES, Tight, VeNCrypt Plain, XVP, Apple's Diffie-Hellman,
  UltraVNC's MSLogonII
• Supported VNC encodings: raw, copyrect, rre, hextile, tight, tightPNG,
  ZRLE, JPEG, Zlib, H.264
• Supports scaling, clipping and resizing the desktop
• Supports back & forward mouse buttons
• Local cursor rendering
• Clipboard copy/paste with full Unicode support
• Translations
• Touch gestures for emulating common mouse actions
• Licensed mainly under the MPL 2.0, see
  the license document for details

Screenshots Copy Section

Running in Firefox before and after connecting:

See more screenshots
here.

Browser requirements Copy Section

noVNC uses many modern web technologies so a formal requirement list is
not available. However these are the minimum versions we are currently
aware of:

• Chrome 89, Firefox 89, Safari 15, Opera 75, Edge 89

Server requirements Copy Section

noVNC follows the standard VNC protocol, but unlike other VNC clients it does
require WebSockets support. Many servers include support (e.g.
x11vnc/libvncserver,
QEMU, and
MobileVNC), but for the others you need to
use a WebSockets to TCP socket proxy. noVNC has a sister project
websockify that provides a simple such
proxy.

Quick start Copy Section

• Use the novnc_proxy script to automatically download and start websockify, which
  includes a mini-webserver and the WebSockets proxy. The --vnc option is
  used to specify the location of a running VNC server:

  ./utils/novnc_proxy --vnc localhost:5901

• If you don't need to expose the web server to public internet, you can
  bind to localhost:

  ./utils/novnc_proxy --vnc localhost:5901 --listen localhost:6081

• Point your browser to the cut-and-paste URL that is output by the novnc_proxy
  script. Hit the Connect button, enter a password if the VNC server has one
  configured, and enjoy!

Installation from snap package Copy Section

Running the command below will install the latest release of noVNC from snap:

sudo snap install novnc

Running noVNC from snap directly

You can run the snap package installed novnc directly with, for example:

novnc --listen 6081 --vnc localhost:5901 # /snap/bin/novnc if /snap/bin is not in your PATH

If you want to use certificate files, due to standard snap confinement restrictions you need to have them in the /home//snap/novnc/current/ directory. If your username is jsmith an example command would be:

novnc --listen 8443 --cert ~jsmith/snap/novnc/current/self.crt --key ~jsmith/snap/novnc/current/self.key --vnc ubuntu.example.com:5901

Running noVNC from snap as a service (daemon)

The snap package also has the capability to run a 'novnc' service which can be
configured to listen on multiple ports connecting to multiple VNC servers
(effectively a service running multiple instances of novnc).
Instructions (with example values):

List current services (out-of-box this will be blank):

sudo snap get novnc services
Key             Value
services.n6080  {...}
services.n6081  {...}

Create a new service that listens on port 6082 and connects to the VNC server
running on port 5902 on localhost:

sudo snap set novnc services.n6082.listen=6082 services.n6082.vnc=localhost:5902

(Any services you define with 'snap set' will be automatically started)
Note that the name of the service, 'n6082' in this example, can be anything
as long as it doesn't start with a number or contain spaces/special characters.

View the configuration of the service just created:

sudo snap get novnc services.n6082
Key                    Value
services.n6082.listen  6082
services.n6082.vnc     localhost:5902

Disable a service (note that because of a limitation in snap it's currently not
possible to unset config variables, setting them to blank values is the way
to disable a service):

sudo snap set novnc services.n6082.listen='' services.n6082.vnc=''

(Any services you set to blank with 'snap set' like this will be automatically stopped)

Verify that the service is disabled (blank values):

sudo snap get novnc services.n6082
Key                    Value
services.n6082.listen  
services.n6082.vnc

Integration and deployment Copy Section

Please see our other documents for how to integrate noVNC in your own software,
or deploying the noVNC application in production environments:

• Embedding - For the noVNC application
• Library - For the noVNC JavaScript library

Authors/Contributors Copy Section

See AUTHORS for a (full-ish) list of authors. If you're not on
that list and you think you should be, feel free to send a PR to fix that.

• Core team:

  • Samuel Mannehed (Cendio)
  • Pierre Ossman (Cendio)

• Previous core contributors:

  • Joel Martin (Project founder)
  • Solly Ross (Red Hat / OpenStack)

• Notable contributions:

  • UI and icons : Pierre Ossman, Chris Gordon
  • Original logo : Michael Sersen
  • tight encoding : Michael Tinglof (Mercuri.ca)
  • RealVNC RSA AES authentication : USTC Vlab Team

• Included libraries:

  • base64 : Martijn Pieters (Digital Creations 2), Samuel Sieb (sieb.net)
  • DES : Dave Zimmerman (Widget Workshop), Jef Poskanzer (ACME Labs)
  • Pako : Vitaly Puzrin (https://github.com/nodeca/pako)

Do you want to be on this list? Check out our
contribution guide and
start hacking!

File: docs/API.md Copy Chapter

noVNC API

The interface of the noVNC client consists of a single RFB object that
is instantiated once per connection.

RFB Copy Chapter

The RFB object represents a single connection to a VNC server. It
communicates using a WebSocket that must provide a standard RFB
protocol stream.

Constructor Copy Section

RFB()

• Creates and returns a new RFB object.

Properties Copy Section

background

• Is a valid CSS background style value indicating which
  background style should be applied to the element containing the
  remote session screen. The default value is rgb(40, 40, 40) (solid
  gray color).

capabilities Read only

• Is an Object indicating which optional extensions are available
  on the server. Some methods may only be called if the corresponding
  capability is set. The following capabilities are defined:

  name	type	description
  power	boolean	Machine power control is available

clippingViewport Read only

• Is a boolean indicating if the remote session is currently being
  clipped to its container. Only relevant if clipViewport is
  enabled.

clipViewport

• Is a boolean indicating if the remote session should be clipped
  to its container. When disabled scrollbars will be shown to handle
  the resulting overflow. Disabled by default.

compressionLevel

• Is an int in range [0-9] controlling the desired compression
  level. Value 0 means no compression. Level 1 uses a minimum of CPU
  resources and achieves weak compression ratios, while level 9 offers
  best compression but is slow in terms of CPU consumption on the server
  side. Use high levels with very slow network connections.
  Default value is 2.

dragViewport

• Is a boolean indicating if mouse events should control the
  relative position of a clipped remote session. Only relevant if
  clipViewport is enabled. Disabled by default.

focusOnClick

• Is a boolean indicating if keyboard focus should automatically be
  moved to the remote session when a mousedown or touchstart
  event is received. Enabled by default.

qualityLevel

• Is an int in range [0-9] controlling the desired JPEG quality.
  Value 0 implies low quality and 9 implies high quality.
  Default value is 6.

resizeSession

• Is a boolean indicating if a request to resize the remote session
  should be sent whenever the container changes dimensions. Disabled
  by default.

scaleViewport

• Is a boolean indicating if the remote session should be scaled
  locally so it fits its container. When disabled it will be centered
  if the remote session is smaller than its container, or handled
  according to clipViewport if it is larger. Disabled by default.

viewOnly

• Is a boolean indicating if any events (e.g. key presses or mouse
  movement) should be prevented from being sent to the server.
  Disabled by default.

Events Copy Section

bell

• The bell event is fired when a audible bell request is received
  from the server.

capabilities

• The capabilities event is fired when RFB.capabilities is
  updated.

clipboard

• The clipboard event is fired when clipboard data is received from
  the server.

clippingviewport

• The clippingviewport event is fired when RFB.clippingViewport is
  updated.

connect

• The connect event is fired when the RFB object has completed
  the connection and handshaking with the server.

credentialsrequired

• The credentialsrequired event is fired when more credentials must
  be given to continue.

desktopname

• The desktopname event is fired when the remote desktop name
  changes.

disconnect

• The disconnect event is fired when the RFB object disconnects.

securityfailure

• The securityfailure event is fired when the security negotiation
  with the server fails.

serververification

• The serververification event is fired when the server identity
  must be confirmed by the user.

Methods Copy Section

RFB.approveServer()

• Proceed connecting to the server. Should be called after the
  serververification event has fired and the
  user has verified the identity of the server.

RFB.blur()

• Remove keyboard focus from the remote session.

RFB.clipboardPasteFrom()

• Send clipboard contents to server.

RFB.disconnect()

• Disconnect from the server.

RFB.focus()

• Move keyboard focus to the remote session.

RFB.getImageData()

• Return the current content of the screen as an ImageData array.

RFB.machineReboot()

• Request a reboot of the remote machine.

RFB.machineReset()

• Request a reset of the remote machine.

RFB.machineShutdown()

• Request a shutdown of the remote machine.

RFB.sendCredentials()

• Send credentials to server. Should be called after the
  credentialsrequired event has fired.

RFB.sendCtrlAltDel()

• Send Ctrl-Alt-Del key sequence.

RFB.sendKey()

• Send a key event.

RFB.toBlob()

• Return the current content of the screen as Blob encoded image file.

RFB.toDataURL()

• Return the current content of the screen as data-url encoded image file.

Details Copy Section

RFB()

The RFB() constructor returns a new RFB object and initiates a new
connection to a specified VNC server.

Syntax

new RFB(target, urlOrChannel);
new RFB(target, urlOrChannel, options);

Parameters

target

• A block HTMLElement that specifies where the RFB
  object should attach itself. The existing contents of the
  HTMLElement will be untouched, but new elements will be added
  during the lifetime of the RFB object.

urlOrChannel

• A DOMString specifying the VNC server to connect to. This must be
  a valid WebSocket URL. This can also be a WebSocket or RTCDataChannel.

options Optional

• An Object specifying extra details about how the connection
  should be made.

  Possible options:

  shared

  • A boolean indicating if the remote server should be shared or
    if any other connected clients should be disconnected. Enabled
    by default.

  credentials

  • An Object specifying the credentials to provide to the server
    when authenticating. The following credentials are possible:

    name	type	description
    "username"	DOMString	The user that authenticates
    "password"	DOMString	Password for the user
    "target"	DOMString	Target machine or session

  repeaterID

  • A DOMString specifying the ID to provide to any VNC repeater
    encountered.

  wsProtocols

  • An Array of DOMStrings specifying the sub-protocols to use
    in the WebSocket connection. Empty by default.

bell

The bell event is fired when the server has requested an audible
bell.

capabilities

The capabilities event is fired whenever an entry is added or removed
from RFB.capabilities. The detail property is an Object with the
property capabilities containing the new value of RFB.capabilities.

clippingviewport

The clippingviewport event is fired whenever RFB.clippingViewport
changes between true and false. The detail property is a boolean
with the new value of RFB.clippingViewport.

clipboard

The clipboard event is fired when the server has sent clipboard data.
The detail property is an Object containing the property text
which is a DOMString with the clipboard data.

credentialsrequired

The credentialsrequired event is fired when the server requests more
credentials than were specified to RFB(). The detail
property is an Object containing the property types which is an
Array of DOMString listing the credentials that are required.

connect

The connect event is fired after all the handshaking with the server
is completed and the connection is fully established. After this event
the RFB object is ready to recieve graphics updates and to send input.

desktopname

The desktopname event is fired when the name of the remote desktop
changes. The detail property is an Object with the property name
which is a DOMString specifying the new name.

disconnect

The disconnect event is fired when the connection has been
terminated. The detail property is an Object that contains the
property clean. clean is a boolean indicating if the termination
was clean or not. In the event of an unexpected termination or an error
clean will be set to false.

securityfailure

The securityfailure event is fired when the handshaking process with
the server fails during the security negotiation step. The detail
property is an Object containing the following properties:

The property status corresponds to the SecurityResult
status code in cases of failure. A status of zero will not be sent in
this event since that indicates a successful security handshaking
process. The optional property reason is provided by the server and
thus the language of the string is not known. However most servers will
probably send English strings. The server can choose to not send a
reason and in these cases the reason property will be omitted.

serververification

The serververification event is fired when the server provides
information that allows the user to verify that it is the correct server
and protect against a man-in-the-middle attack. The detail property is
an Object containing the property type which is a DOMString
specifying which type of information the server has provided. Other
properties are also available, depending on the value of type:

"RSA"

• The server identity is verified using just a RSA key. The property
  publickey is a Uint8Array containing the public key in a unsigned
  big endian representation.

RFB.approveServer()

The RFB.approveServer() method is used to signal that the user has
verified the server identity provided in a serververification event
and that the connection can continue.

Syntax

RFB.approveServer();

RFB.blur()

The RFB.blur() method remove keyboard focus on the remote session.
Keyboard events will no longer be sent to the remote server after this
point.

Syntax

RFB.blur();

RFB.clipboardPasteFrom()

The RFB.clipboardPasteFrom() method is used to send clipboard data
to the remote server.

Syntax

RFB.clipboardPasteFrom(text);

Parameters

text

• A DOMString specifying the clipboard data to send.

RFB.disconnect()

The RFB.disconnect() method is used to disconnect from the currently
connected server.

Syntax

RFB.disconnect();

RFB.focus()

The RFB.focus() method sets the keyboard focus on the remote session.
Keyboard events will be sent to the remote server after this point.

Syntax

RFB.focus();
RFB.focus(options);

Parameters

options Optional

• A object providing options to control how the focus will be
  performed. Please see HTMLElement.focus() for
  available options.

RFB.getImageData()

The RFB.getImageData() method is used to return the current content of
the screen encoded as ImageData.

Syntax

RFB.getImageData();

RFB.machineReboot()

The RFB.machineReboot() method is used to request a clean reboot of
the remote machine. The capability power must be set for this method
to have any effect.

Syntax

RFB.machineReboot();

RFB.machineReset()

The RFB.machineReset() method is used to request a forced reset of
the remote machine. The capability power must be set for this method
to have any effect.

Syntax

RFB.machineReset();

RFB.machineShutdown()

The RFB.machineShutdown() method is used to request to shut down the
remote machine. The capability power must be set for this method to
have any effect.

Syntax

RFB.machineShutdown();

RFB.sendCredentials()

The RFB.sendCredentials() method is used to provide the missing
credentials after a credentialsrequired event has been fired.

Syntax

RFB.sendCredentials(credentials);

Parameters

credentials

• An Object specifying the credentials to provide to the server
  when authenticating. See RFB() for details.

RFB.sendCtrlAltDel()

The RFB.sendCtrlAltDel() method is used to send the key sequence
left Control, left Alt, Delete. This is a convenience wrapper
around RFB.sendKey().

Syntax

RFB.sendCtrlAltDel();

RFB.sendKey()

The RFB.sendKey() method is used to send a key event to the server.

Syntax

RFB.sendKey(keysym, code);
RFB.sendKey(keysym, code, down);

Parameters

keysym

• A long specifying the RFB keysym to send. Can be 0 if a valid
  code is specified.

code

• A DOMString specifying the physical key to send. Valid values are
  those that can be specified to KeyboardEvent.code.
  If the physical key cannot be determined then null shall be
  specified.

down Optional

• A boolean specifying if a press or a release event should be
  sent. If omitted then both a press and release event are sent.

RFB.toBlob()

The RFB.toBlob() method is used to return the current content of the
screen encoded as Blob.

Syntax

RFB.toBlob(callback);
RFB.toBlob(callback, type);
RFB.toBlob(callback, type, quality);

Parameters

callback

• A callback function which will receive the resulting
  Blob as the single argument

type Optional

• A string indicating the requested MIME type of the image

quality Optional

• A number between 0 and 1 indicating the image quality.

RFB.toDataURL()

The RFB.toDataURL() method is used to return the current content of the
screen encoded as a data URL that could for example be put in the src attribute
of an img tag.

Syntax

RFB.toDataURL();
RFB.toDataURL(type);
RFB.toDataURL(type, encoderOptions);

Parameters

type Optional

• A string indicating the requested MIME type of the image

encoderOptions Optional

• A number between 0 and 1 indicating the image quality.

File: docs/API-internal.md Copy Chapter

1. Internal modules

The noVNC client is composed of several internal modules that handle
rendering, input, networking, etc. Each of the modules is designed to
be cross-browser and independent from each other.

Note however that the API of these modules is not guaranteed to be
stable, and this documentation is not maintained as well as the
official external API.

1.1 Module list Copy Chapter

• Keyboard (core/input/keyboard.js): Keyboard input event handler with
  non-US keyboard support. Translates keyDown and keyUp events to X11
  keysym values.

• Display (core/display.js): Efficient 2D rendering abstraction
  layered on the HTML5 canvas element.

• Clipboard (core/clipboard.js): Clipboard event handler.

• Websock (core/websock.js): Websock client from websockify
  with transparent binary data support.
  Websock API wiki page.

1.2 Callbacks Copy Chapter

For the Mouse, Keyboard, Display, and Clipboard objects, the callback
functions are assigned to configuration attributes, just as for the RFB
object. The WebSock module has a method named 'on' that takes two
parameters: the callback event name, and the callback function.

2. Modules Copy Chapter

2.1 Keyboard module Copy Chapter

2.1.1 Configuration attributes Copy Section

None

2.1.2 Methods Copy Section

2.1.3 Callbacks Copy Section

2.2 Display module Copy Chapter

2.2.1 Configuration attributes Copy Section

2.2.2 Methods Copy Section

2.3 Clipboard module Copy Chapter

2.3.1 Configuration attributes Copy Section

None

2.3.2 Methods Copy Section

2.3.3 Callbacks Copy Section

File: docs/EMBEDDING.md Copy Chapter

Embedding and deploying noVNC application

This document describes how to embed and deploy the noVNC application, which
includes settings and a full user interface. If you are looking for
documentation on how to use the core noVNC library in your own application,
then please see our library documentation.

Files Copy Chapter

The noVNC application consists of the following files and directories:

• vnc.html - The main page for the application and where users should go. It
  is possible to rename this file.

• app/ - Support files for the application. Contains code, images, styles and
  translations.

• core/ - The core noVNC library.

• vendor/ - Third party support libraries used by the application and the
  core library.

The most basic deployment consists of simply serving these files from a web
server and setting up a WebSocket proxy to the VNC server.

Parameters Copy Chapter

The noVNC application can be controlled via a number of settings. All of
them are available in the UI for the user to change, but they can also
be set via other means:

• Via the URL, either as a query parameter:

  text Copy

  https://www.example.com/vnc.html?reconnect=0&shared=1

  or as a fragment:

  text Copy

  https://www.example.com/vnc.html#reconnect=0&shared=1

  The latter might be preferred as it is not sent to the server.

• Via the files defaults.json and mandatory.json

Currently, the following options are available:

• autoconnect - Automatically connect as soon as the page has finished
  loading.

• reconnect - If noVNC should automatically reconnect if the connection is
  dropped.

• reconnect_delay - How long to wait in milliseconds before attempting to
  reconnect.

• host - The WebSocket host to connect to. This setting is deprecated
  in favor of specifying a URL in path.

• port - The WebSocket port to connect to. This setting is deprecated
  in favor of specifying a URL in path.

• encrypt - If TLS should be used for the WebSocket connection. This
  setting is deprecated in favor of specifying a URL in path.

• path - The WebSocket URL to use. It can be either an absolute URL,
  or a URL relative vnc.html. If host is specified, then path will
  be interpreted as the path component in the URL instead.

• password - The password sent to the server, if required.

• repeaterID - The repeater ID to use if a VNC repeater is detected.

• shared - If other VNC clients should be disconnected when noVNC connects.

• bell - If the keyboard bell should be enabled or not.

• view_only - If the remote session should be in non-interactive mode.

• view_clip - If the remote session should be clipped or use scrollbars if
  it cannot fit in the browser.

• resize - How to resize the remote session if it is not the same size as
  the browser window. Can be one of off, scale and remote.

• quality - The session JPEG quality level. Can be 0 to 9.

• compression - The session compression level. Can be 0 to 9.

• logging - The console log level. Can be one of error, warn, info or
  debug.

• keep_device_awake - Should we prevent the (local) display from going into
  sleep mode while a connection is active? Useful for view-only sessions where
  there unlikely to be any keyboard/mouse activity to keep the device active.

HTTP serving considerations Copy Chapter

Browser cache issue Copy Section

If you serve noVNC files using a web server that provides an ETag header, and
include any options in the query string, a nasty browser cache issue can bite
you on upgrade, resulting in a red error box. The issue is caused by a mismatch
between the new vnc.html (which is reloaded because the user has used it with
new query string after the upgrade) and the old javascript files (that the
browser reuses from its cache). To avoid this issue, the browser must be told
to always revalidate cached files using conditional requests. The correct
semantics are achieved via the (confusingly named) Cache-Control: no-cache
header that needs to be provided in the web server responses.

Example server configurations Copy Section

Apache:

# In the main configuration file
    # (Debian/Ubuntu users: use "a2enmod headers" instead)
    LoadModule headers_module modules/mod_headers.so

    # In the <Directory> or <Location> block related to noVNC
    Header set Cache-Control "no-cache"

Nginx:

# In the location block related to noVNC
    add_header Cache-Control no-cache;

File: docs/LIBRARY.md Copy Chapter

Using the noVNC JavaScript library

This document describes how to make use of the noVNC JavaScript library for
integration in your own VNC client application. If you wish to embed the more
complete noVNC application with its included user interface then please see
our embedding documentation.

API Copy Chapter

The API of noVNC consists of a single object called RFB. The formal
documentation for that object can be found in our API documentation.

Example Copy Chapter

noVNC includes a small example application called vnc_lite.html. This does
not make use of all the features of noVNC, but is a good start to see how to
do things.

Conversion of modules Copy Chapter

noVNC is written using ECMAScript 6 modules. This is not supported by older
versions of Node.js. To use noVNC with those older versions of Node.js the
library must first be converted.

Fortunately noVNC includes a script to handle this conversion. Please follow
the following steps:

1. Install Node.js
2. Run npm install in the noVNC directory

The result of the conversion is available in the lib/ directory.

File: utils/README.md Copy Chapter

WebSockets Proxy/Bridge Copy Chapter

Websockify has been forked out into its own project. novnc_proxy will
automatically download it here if it is not already present and not
installed as system-wide.

For more detailed description and usage information please refer to
the websockify README.

The other versions of websockify (C, Node.js) and the associated test
programs have been moved to
websockify. Websockify was
formerly named wsproxy.