138 lines
4.8 KiB
Markdown
138 lines
4.8 KiB
Markdown
# 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](LIBRARY.md).
|
||
|
||
## Files
|
||
|
||
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
|
||
|
||
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:
|
||
|
||
```
|
||
https://www.example.com/vnc.html?reconnect=0&shared=1
|
||
```
|
||
|
||
or as a fragment:
|
||
|
||
```
|
||
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`.
|
||
|
||
* `crop_rect` - This option specifies the remote framebuffer area that will be
|
||
shown in the noVNC client. The format is widthxheight+xoffset+yoffset, where
|
||
‘+’ signs can be replaced with ‘−’ signs to specify offsets from the right
|
||
and/or from the bottom of the screen. Offsets are optional, +0+0 is assumed
|
||
by default (top left corner). If the argument is empty, full screen is shown
|
||
to VNC clients (this is the default). See -Geometry parameter of TigerVNC.
|
||
|
||
* `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
|
||
### Browser cache issue
|
||
|
||
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
|
||
|
||
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;
|
||
```
|