README.md

   1 ## noVNC: HTML VNC Client Library and Application
   2
   3 [![Build Status](https://travis-ci.org/novnc/noVNC.svg?branch=master)](https://travis-ci.org/novnc/noVNC)
   4
   5 ### Description
   6
   7 noVNC is both a HTML VNC client JavaScript library and an application built on
   8 top of that library. noVNC runs well in any modern browser including mobile
   9 browsers (iOS and Android).
  10
  11 Many companies, projects and products have integrated noVNC including
  12 [OpenStack](http://www.openstack.org),
  13 [OpenNebula](http://opennebula.org/),
  14 [LibVNCServer](http://libvncserver.sourceforge.net), and
  15 [ThinLinc](https://cendio.com/thinlinc). See
  16 [the Projects and Companies wiki page](https://github.com/novnc/noVNC/wiki/Projects-and-companies-using-noVNC)
  17 for a more complete list with additional info and links.
  18
  19 ### Table of Contents
  20
  21 - [News/help/contact](#newshelpcontact)
  22 - [Features](#features)
  23 - [Screenshots](#screenshots)
  24 - [Browser Requirements](#browser-requirements)
  25 - [Server Requirements](#server-requirements)
  26 - [Quick Start](#quick-start)
  27 - [Installation from Snap Package](#installation-from-snap-package)
  28 - [Integration and Deployment](#integration-and-deployment)
  29 - [Authors/Contributors](#authorscontributors)
  30
  31 ### News/help/contact
  32
  33 The project website is found at [novnc.com](http://novnc.com).
  34 Notable commits, announcements and news are posted to
  35 [@noVNC](http://www.twitter.com/noVNC).
  36
  37 If you are a noVNC developer/integrator/user (or want to be) please join the
  38 [noVNC discussion group](https://groups.google.com/forum/?fromgroups#!forum/novnc).
  39
  40 Bugs and feature requests can be submitted via
  41 [github issues](https://github.com/novnc/noVNC/issues). If you have questions
  42 about using noVNC then please first use the
  43 [discussion group](https://groups.google.com/forum/?fromgroups#!forum/novnc).
  44 We also have a [wiki](https://github.com/novnc/noVNC/wiki/) with lots of
  45 helpful information.
  46
  47 If you are looking for a place to start contributing to noVNC, a good place to
  48 start would be the issues that are marked as
  49 ["patchwelcome"](https://github.com/novnc/noVNC/issues?labels=patchwelcome).
  50 Please check our
  51 [contribution guide](https://github.com/novnc/noVNC/wiki/Contributing) though.
  52
  53 If you want to show appreciation for noVNC you could donate to a great non-
  54 profits such as:
  55 [Compassion International](http://www.compassion.com/),
  56 [SIL](http://www.sil.org),
  57 [Habitat for Humanity](http://www.habitat.org),
  58 [Electronic Frontier Foundation](https://www.eff.org/),
  59 [Against Malaria Foundation](http://www.againstmalaria.com/),
  60 [Nothing But Nets](http://www.nothingbutnets.net/), etc.
  61 Please tweet [@noVNC](http://www.twitter.com/noVNC) if you do.
  62
  63
  64 ### Features
  65
  66 * Supports all modern browsers including mobile (iOS, Android)
  67 * Supported VNC encodings: raw, copyrect, rre, hextile, tight, tightPNG
  68 * Supports scaling, clipping and resizing the desktop
  69 * Local cursor rendering
  70 * Clipboard copy/paste
  71 * Translations
  72 * Licensed mainly under the [MPL 2.0](http://www.mozilla.org/MPL/2.0/), see
  73   [the license document](LICENSE.txt) for details
  74
  75 ### Screenshots
  76
  77 Running in Firefox before and after connecting:
  78
  79 <img src="http://novnc.com/img/noVNC-1-login.png" width=400>&nbsp;
  80 <img src="http://novnc.com/img/noVNC-3-connected.png" width=400>
  81
  82 See more screenshots
  83 [here](http://novnc.com/screenshots.html).
  84
  85
  86 ### Browser Requirements
  87
  88 noVNC uses many modern web technologies so a formal requirement list is
  89 not available. However these are the minimum versions we are currently
  90 aware of:
  91
  92 * Chrome 49, Firefox 44, Safari 11, Opera 36, IE 11, Edge 12
  93
  94
  95 ### Server Requirements
  96
  97 noVNC follows the standard VNC protocol, but unlike other VNC clients it does
  98 require WebSockets support. Many servers include support (e.g.
  99 [x11vnc/libvncserver](http://libvncserver.sourceforge.net/),
 100 [QEMU](http://www.qemu.org/), and
 101 [MobileVNC](http://www.smartlab.at/mobilevnc/)), but for the others you need to
 102 use a WebSockets to TCP socket proxy. noVNC has a sister project
 103 [websockify](https://github.com/novnc/websockify) that provides a simple such
 104 proxy.
 105
 106
 107 ### Quick Start
 108
 109 * Use the launch script to automatically download and start websockify, which
 110   includes a mini-webserver and the WebSockets proxy. The `--vnc` option is
 111   used to specify the location of a running VNC server:
 112
 113     `./utils/launch.sh --vnc localhost:5901`
 114
 115 * Point your browser to the cut-and-paste URL that is output by the launch
 116   script. Hit the Connect button, enter a password if the VNC server has one
 117   configured, and enjoy!
 118
 119 ### Installation from Snap Package
 120 Running the command below will install the latest release of noVNC from Snap:
 121
 122 `sudo snap install novnc`
 123
 124 #### Running noVNC
 125
 126 You can run the Snap-package installed novnc directly with, for example:
 127
 128 `novnc --listen 6081 --vnc localhost:5901 # /snap/bin/novnc if /snap/bin is not in your PATH`
 129
 130 #### Running as a Service (Daemon)
 131 The Snap package also has the capability to run a 'novnc' service which can be
 132 configured to listen on multiple ports connecting to multiple VNC servers
 133 (effectively a service runing multiple instances of novnc).
 134 Instructions (with example values):
 135
 136 List current services (out-of-box this will be blank):
 137
 138 ```
 139 sudo snap get novnc services
 140 Key             Value
 141 services.n6080  {...}
 142 services.n6081  {...}
 143 ```
 144
 145 Create a new service that listens on port 6082 and connects to the VNC server
 146 running on port 5902 on localhost:
 147
 148 `sudo snap set novnc services.n6082.listen=6082 services.n6082.vnc=localhost:5902`
 149
 150 (Any services you define with 'snap set' will be automatically started)
 151 Note that the name of the service, 'n6082' in this example, can be anything
 152 as long as it doesn't start with a number or contain spaces/special characters.
 153
 154 View the configuration of the service just created:
 155
 156 ```
 157 sudo snap get novnc services.n6082
 158 Key                    Value
 159 services.n6082.listen  6082
 160 services.n6082.vnc     localhost:5902
 161 ```
 162
 163 Disable a service (note that because of a limitation in  Snap it's currently not
 164 possible to unset config variables, setting them to blank values is the way
 165 to disable a service):
 166
 167 `sudo snap set novnc services.n6082.listen='' services.n6082.vnc=''`
 168
 169 (Any services you set to blank with 'snap set' like this will be automatically stopped)
 170
 171 Verify that the service is disabled (blank values):
 172
 173 ```
 174 sudo snap get novnc services.n6082
 175 Key                    Value
 176 services.n6082.listen
 177 services.n6082.vnc
 178 ```
 179
 180 ### Integration and Deployment
 181
 182 Please see our other documents for how to integrate noVNC in your own software,
 183 or deploying the noVNC application in production environments:
 184
 185 * [Embedding](docs/EMBEDDING.md) - For the noVNC application
 186 * [Library](docs/LIBRARY.md) - For the noVNC JavaScript library
 187
 188
 189 ### Authors/Contributors
 190
 191 See [AUTHORS](AUTHORS) for a (full-ish) list of authors.  If you're not on
 192 that list and you think you should be, feel free to send a PR to fix that.
 193
 194 * Core team:
 195     * [Joel Martin](https://github.com/kanaka)
 196     * [Samuel Mannehed](https://github.com/samhed) (Cendio)
 197     * [Solly Ross](https://github.com/DirectXMan12) (Red Hat / OpenStack)
 198     * [Pierre Ossman](https://github.com/CendioOssman) (Cendio)
 199
 200 * Notable contributions:
 201     * UI and Icons : Pierre Ossman, Chris Gordon
 202     * Original Logo : Michael Sersen
 203     * tight encoding : Michael Tinglof (Mercuri.ca)
 204
 205 * Included libraries:
 206     * base64 : Martijn Pieters (Digital Creations 2), Samuel Sieb (sieb.net)
 207     * DES : Dave Zimmerman (Widget Workshop), Jef Poskanzer (ACME Labs)
 208     * Pako : Vitaly Puzrin (https://github.com/nodeca/pako)
 209
 210 Do you want to be on this list? Check out our
 211 [contribution guide](https://github.com/novnc/noVNC/wiki/Contributing) and
 212 start hacking!