README.md
1[](https://travis-ci.org/LibVNC/libvncserver)
2[](https://ci.appveyor.com/project/bk138/libvncserver/branch/master)
3[](https://liberapay.com/LibVNC/donate) [](https://gitter.im/LibVNC/libvncserver?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
4
5LibVNCServer: A library for easy implementation of a VNC server.
6Copyright (C) 2001-2003 Johannes E. Schindelin
7
8If you already used LibVNCServer, you probably want to read [NEWS](NEWS.md).
9
10What is it?
11===========
12
13[VNC](https://en.wikipedia.org/wiki/Virtual_Network_Computing) is a set of programs
14using the [RFB (Remote Frame Buffer)](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst)
15protocol. They are designed to "export" a frame buffer via net: you set up a server and can
16connect to it via VNC viewers. If the server supports WebSockets (which LibVNCServer does),
17you can also connect using an in-browser VNC viewer like [noVNC](https://novnc.com).
18
19It is already in wide use for administration, but it is not that easy to program a server yourself.
20
21This has been changed by LibVNCServer.
22
23Projects using it
24=================
25
26The [homepage has a tentative list](https://libvnc.github.io/#projects-using) of
27all the projects using either LibVNCServer or LibVNCClient or both.
28
29RFB Protocol Support Status
30===========================
31
32## [Security Types](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#712security)
33
34|Name |Number | LibVNCServer | LibVNCClient |
35|-------------------|------------|--------------|--------------|
36|None | 1 | ✔ | ✔ |
37|VNC Authentication | 2 | ✔ | ✔ |
38|SASL | 20 | | ✔ |
39|MSLogon | 0xfffffffa | | ✔ |
40|Apple ARD | 30 | | ✔ |
41|TLS | 18 | | ✔ |
42|VeNCrypt | 19 | | ✔ |
43
44## [Encodings](https://github.com/rfbproto/rfbproto/blob/master/rfbproto.rst#76encodings)
45
46| Name | Number | LibVNCServer | LibVNCClient |
47|----------|--------|--------------|--------------|
48| Raw | 1 | ✔ | ✔ |
49| CopyRect | 2 | ✔ | ✔ |
50| RRE | 3 | ✔ | ✔ |
51| CoRRE | 4 | ✔ | ✔ |
52| Hextile | 5 | ✔ | ✔ |
53| Zlib | 6 | ✔ | ✔ |
54| Tight | 7 | ✔ | ✔ |
55| Zlibhex | 8 | ✔ | |
56| Ultra | 9 | ✔ | ✔ |
57| TRLE | 15 | | ✔ |
58| ZRLE | 16 | ✔ | ✔ |
59| ZYWRLE | 17 | ✔ | ✔ |
60| TightPNG | -260 | ✔ | |
61
62
63How to build
64============
65
66LibVNCServer uses CMake, which you can download [here](https://cmake.org/download/)
67or, better yet, install using your platform's package manager (apt, yum, brew, macports,
68chocolatey, etc.).
69
70You can then build via:
71
72 mkdir build
73 cd build
74 cmake ..
75 cmake --build .
76
77Crypto support in LibVNCClient and LibVNCServer can use different backends:
78
79 * OpenSSL (`-DWITH_OPENSSL=ON -DWITH_GCRYPT=OFF`)
80 * Supports all authentication methods in LibVNCClient and LibVNCServer.
81 * Supports WebSockets in LibVNCServer.
82 * Libgcrypt (`-DWITH_OPENSSL=OFF -DWITH_GCRYPT=ON`)
83 * Supports all authentication methods in LibVNCClient and LibVNCServer.
84 * Supports WebSockets in LibVNCServer.
85 * Included (`-DWITH_OPENSSL=OFF -DWITH_GCRYPT=OFF`)
86 * Supports _only VNC authentication_ in LibVNCClient and LibVNCServer.
87 * Supports WebSockets in LibVNCServer.
88
89Transport Layer Security support in LibVNCClient and LibVNCServer can use:
90
91 * OpenSSL (`-DWITH_OPENSSL=ON -DWITH_GNUTLS=OFF`)
92 * GnuTLS (`-DWITH_OPENSSL=OFF -DWITH_GNUTLS=ON`)
93
94For some more comprehensive examples that include installation of dependencies, see
95the [Unix CI](.travis.yml) and [Windows CI](.appveyor.yml) build setups.
96
97Crosscompiling from Unix to Android
98-----------------------------------
99
100See https://developer.android.com/ndk/guides/cmake.html as a reference,
101but basically it boils down to:
102
103 mkdir build
104 cd build
105 cmake .. -DANDROID_NDK=<path> -DCMAKE_TOOLCHAIN_FILE=<path> -DANDROID_NATIVE_API_LEVEL=<API level you want>
106 cmake --build .
107
108Crosscompiling from Linux to Windows
109------------------------------------
110
111Tested with MinGW-w64 on Debian, which you should install via `sudo apt install mingw-w64`.
112You can make use of the [provided toolchainfile](cmake/Toolchain-cross-mingw32-linux.cmake).
113It sets CMake to expect (optional) win32 dependencies like libjpeg and friends
114in the `deps` directory. Note that you need (probably self-built) development packages for
115win32, the `-dev` packages coming with your distribution won't work.
116
117
118 mkdir build
119 cd build
120 cmake -DCMAKE_TOOLCHAIN_FILE=../cmake/Toolchain-cross-mingw32-linux.cmake ..
121 cmake --build .
122
123How to use
124==========
125
126See the [LibVNCServer API intro documentation](https://libvnc.github.io/doc/html/libvncserver_doc.html)
127for how to create a server instance, wire up input handlers and handle cursors.
128
129In case you prefer to learn LibVNCServer by example, have a look at the servers in the
130[examples](examples) directory.
131
132For LibVNCClient, examples can be found in [client_examples](client_examples).
133
134Using Websockets
135----------------
136
137You can try out the built-in websockets support by starting the example server
138from the [webclients](webclients) directory via `../examples/example`. It's
139important to _not_ start from within the `examples` directory as otherwise the
140server program won't find its HTTP index file. The server program will tell you
141a URL to point your web browser to. There, you can click on the noVNC-Button to
142connect using the noVNC viewer git submodule (installable via
143`git submodule update --init`).
144
145### Using Secure Websockets
146
147If you don't already have an SSL cert that's trusted by your browser, the most
148comfortable way to create one is using [minica](https://github.com/jsha/minica).
149On Debian-based distros, you can install it via `sudo apt install minica`, on
150MacOS via `brew install minica`.
151
152Go to the webclients directory and create host and CA certs via:
153
154 cd webclients
155 minica -org "LibVNC" $(hostname)
156
157Trust the cert in your browser by importing the created `cacert.crt`, e.g. for
158Firefox go to Options->Privacy & Security->View Certificates->Authorities and
159import the created `cacert.crt`, tick the checkbox to use it for trusting
160websites. For other browsers, the process is similar.
161
162Then, you can finally start the example server, giving it the created host
163key and cert:
164
165 ../examples/example -sslkeyfile $(hostname).key -sslcertfile $(hostname).crt
166
167The server program will tell you a URL to point your web browser to. There,
168you can click on the noVNC-encrypted-connection-button to connect using the
169bundled noVNC viewer using an encrypted Websockets connection.
170
171Commercial Use
172==============
173
174At the beginning of this project Dscho, the original author, would have
175liked to make it a BSD license. However, it is based on plenty of GPL'ed
176code, so it has to be a GPL.
177
178The people at AT&T worked really well to produce something as clean and lean
179as VNC. The managers decided that for their fame, they would release the
180program for free. But not only that! They realized that by releasing also
181the code for free, VNC would become an evolving little child, conquering
182new worlds, making its parents very proud. As well they can be! To protect
183this innovation, they decided to make it GPL, not BSD. The principal
184difference is: You can make closed source programs deriving from BSD, not
185from GPL. You have to give proper credit with both.
186
187Now, why not BSD? Well, imagine your child being some famous actor. Along
188comes a manager who exploits your child exclusively, that is: nobody else
189can profit from the child, it itself included. Got it?
190
191What reason do you have now to use this library commercially?
192
193Several: You don't have to give away your product. Then you have effectively
194circumvented the GPL, because you have the benefits of other's work and you
195don't give back anything. Not good.
196
197Better: Use a concept like MySQL. This is free software, however, they make
198money with it. If you want something implemented, you have the choice:
199Ask them to do it (and pay a fair price), or do it yourself, normally giving
200back your enhancements to the free world of computing.
201
202License
203-------
204
205This program is free software; you can redistribute it and/or
206modify it under the terms of the GNU General Public License
207as published by the Free Software Foundation; either version 2
208of the License, or (at your option) any later version.
209
210This program is distributed in the hope that it will be useful,
211but WITHOUT ANY WARRANTY; without even the implied warranty of
212MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
213GNU General Public License for more details.
214
215You should have received a copy of the GNU General Public License
216along with this program; if not, write to the Free Software
217Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
218
219Contact
220=======
221
222* To file an issue, go to https://github.com/LibVNC/libvncserver/issues
223* For non-public contact please see [SECURITY.md](SECURITY.md).
224
225
){kind=link}
){kind=link}
){kind=link}