Display on vnc client over a network

Name

display-vnc : Display on vnc client over a network

Synopsis

display-vnc: [-bind=<iface>] [-cert=<file>] [-ciphers=<list>]
             [-client=<host>] [-copyrect=no|always] [-corre=no]
             [-deskname=no] [-desksize=no] [-dh=<file>]
             [-display=<dpy>] [-gii=no] [-hextile=no] [-kold]
             [-passwd=<file>] [-physz=<sizex>,<sizey>[dpi]]
             [-privkey=<file>] [-rre=no] [-server[=<dpy>|stdio]]
             [-sslver=<method>] [-stdio] [-tight=enc|ext|no]
             [-title=<title>] [-trle=no] [-vencrypt]
             [-vrfydir=<dir>] [-vrfyfile=<file>] [-viewonly]
             [-viewpw=<file>] [-wmvi=no] [-zlib=<level>|no]
             [-zlibhex=<level>|no] [-zrle=<level>|no]

Description

Provides a linear framebuffer in main memory. A vnc client that connects gets to see a copy of this framebuffer. The protocol used is the remote framebuffer protocol, or the RFB protocol for short.

The supported RFB protocol versions are 3.3, 3.7 and 3.8.

Options

'-bind=<iface>'

Bind the server socket to the specific iface, e.g. 127.0.0.1 in case display-vnc should only accept connections from an ssh tunnel.

'-cert=<file>'

This option is only in effect if the -vencrypt option is also given. PEM-format file with the certificate chain to use. By giving this option you also switch from using anonymous TLS to using x509 certificates. In order to use the certificate chain, you may also have to load a private key, using the -privkey option.

'-ciphers=<list>'

This option is only in effect if the -vencrypt option is also given. Explicitely specify the allowed cipher suites (in the same format OpenSSL uses, see the openssl ciphers manpage). The default allowed ciphers are aNULL:!eNULL:@STRENGTH (all anonymous ciphers that provides encryption), unless the -cert option is also given in which case the default is instead ALL:!aNULL:@STRENGTH (all encrypting ciphers that are not anonymous).

'-client=<host>'

Make a connection to host, instead of waiting for clients to connect. A vnc viewer in listening mode is expected to be found on host.

'-copyrect=no|always'

Controls when the CopyRect encoding is used. Select no to disable it completely, and always to enable it when suitable even if there is support for some other encoding the client has preferred. The default is to only use the CopyRect encoding if it is the most preferred encoding available.

'-corre=no'

Disables the CoRRE encoding.

'-deskname=no'

Disables the DesktopName pseudo-encoding.

'-desksize=no'

Disables the DesktopSize pseudo-encoding.

'-dh=<file>'

This option is only in effect if the -vencrypt option is also given. Specify a PEM file with diffie-hellman parameters to use. If this option is not used, DH parameters will be generated on-the-fly which may be somewhat time consuming. See the openssl dhparam manpage for how to generate a DH PEM file.

'-display=<dpy>'

The display number clients should connect to. Display number 0 is equivalent to tcp port 5900.

If the -client option is also given, this is instead the display number this server connects to, and display number 0 is equivalent to tcp port 5500 in that case.

'-gii=no'

Disables the gii pseudo-encoding.

'-hextile=no'

Disables the hextile encoding.

'-kold'

Kill On Last Disconnect. This option ends the application when the last client disconnects. It can be useful in conjunction with the -client, -stdio and -server=stdio options so that the application does not linger without any user feedback.

'-passwd=<file>'

The vnc client has to successfully encrypt a random challenge with the password stated on the first line of file in order to connect. In the password, only the eight first characters and the seven least significant bits of every character are used in the authentication. If this password is given, the client is allowed to send input events such as keys and pointer movements to the application. However, this allowance may be overridden with the -viewonly option. See the options -viewonly and -viewpw for comparison.

'-physz=<sizex>,<sizey>[dpi]'

This option will provide a physical screen size for applications which wish to remain resolution independent. sizex,:p:sizey are the x,y size of the screen in millimeters, unless the optional 'dpi' string is affixed, in which case, they represent resolution in dots-per-inch.

'-privkey=<file>'

This option is only in effect if the -vencrypt option is also given. PEM-format file with the private key for the certificate chain given with the -cert option. The private key may (unfortunately) not be protected with a pass phrase, since there is no good way to pass the key to display-vnc.

'-rre=no'

Disables the RRE encoding.

'-server[=<dpy>|stdio]'

To run both a server and open a client at the same time, but with different display numbers, the server display number can be specified using -server=<dpy>. If no argument is given, the display number is collected for the -display option. Use -display=stdio to accept connections from the stdin file handle, which is suitable for serving a GGI application as an inetd(8) wait type service (see the example below). The -server=stdio option is incompatible with the -stdio option.

'-sslver=<method>'

This option is only in effect if the -vencrypt option is also given. The SSL method can be one of SSLv2, SSLv3, TLSv1 or SSLv23 (allows a mix). TLSv1 is the default, since SSLv2 has security issues.

'-stdio'

Talk the RFB protocol on stdin/stdout instead of waiting for clients to connect. Suitable for serving a GGI application as an inetd(8) nowait type service (see the example below). One requirement though, is that the served GGI application does not "chatter" on stdout and/or stderr. The -stdio option is incompatible with the -server=stdio option.

'-tight=enc|ext|no'

Control the Tight encoding and the Tight protocol extension. Using -tight=enc enables the Tight encoding, using -tight=ext enables the Tight protocol extension, and -tight=no disables them both. The default is to enable both the Tight encoding and the Tight protocol extension.

'-title=<title>'

The title clients should use on their windows. If this option is not specified, the default is "GGI on vnc".

'-trle=no'

Disables the TRLE encoding.

'-vencrypt'

Enable the VeNCrypt protocol extension and require that it is used. By default the VeNCrypt extension will use anonymous encryption (susceptible to man in the middle attacks). If the -cert option is given VeNCrypt will instead issue an x509 certificate for the client to verify. In addition to that, display-vnc will require the client to provide an x509 certificate if any or both of the -vrfyfile or -vrfydir options are given.

'-vrfydir=<dir>'

This option is only in effect if the -vencrypt and -cert options are also given. Directory with PEM-format certificate authorities. The CA are used when verifying the client certificate. If this option (or the -vrfydir option) is not given, the client is not required to provide a valid certificate.

'-vrfyfile=<file>'

This option is only in effect if the -vencrypt and -cert options are also given. PEM-format file with certificate authorities. The CA are used when verifying the client certificate. If this option (or the -vrfyfile option) is not given, the client is not required to provide a valid certificate.

'-viewonly'

If this option is given, no client is allowed to send input events such as keys and pointer movements to the application. If the -passwd option has also been given, the given password is effectively reduced to a -viewpw password. This option is intended for use together with e.g. the display-multi(7) target.

'-viewpw=<file>'

The vnc client has to successfully encrypt a random challenge with the password stated on the first line of file in order to connect. In the password, only the eight first characters and the seven least significant bits of every character are used in the authentication. If this password is given, the client is not allowed to send input events such as keys and pointer movements to the application. See the options -passwd and -viewonly for comparison.

'-wmvi=no'

Disables the WMVi pseudo-encoding.

'-zlib=<level>|no'

Specify the compression level to use for the Zlib encoding. 0 for no compression and 9 for maximum compression. Saying no here disables the Zlib encoding. If the option isn't specified, a default compromize between speed and compression is selected.

'-zlibhex=<level>|no'

Specify the compression level to use for the ZlibHex encoding. 0 for no compression and 9 for maximum compression. Saying no here disables the ZlibHex encoding. If the option isn't specified, a default compromize between speed and compression is selected.

'-zrle=<level>|no'

Specify the compression level to use for the ZRLE encoding. 0 for no compression and 9 for maximum compression. Saying no here disables the ZRLE encoding. If the option isn't specified, a default compromize between speed and compression is selected.

Features

  • Raw, CopyRect, RRE, CoRRE, Hextile, Tight, Zlib, ZlibHex, TRLE and ZRLE encodings. The CopyRect encoding is only used for panning.
  • DesktopName, DesktopSize, GII and WMVi pseudo-encodings.
  • Support for the Tight protocol extension from the TightVNC project.
  • Support for the VeNCrypt protocol extension from the VeNCrypt project. However, the VeNCrypt plain authentication is not supported.
  • Multiple simultaneous clients (shared session).
  • DirectBuffer always available, including tidy buffer mode (see ggiSetFlags(3)).
  • Multiple frames always available.
  • Panning always available.
  • Unaccelerated.

Examples

To launch a GGI application for each connection made to a TCP port, you may use inetd(8). Just add a line like this to '/etc/inetd.conf':

vnc stream tcp nowait nobody /path/to/app app -t vnc:-stdio:-kold

You also need to define what port the service 'vnc' should use in the file '/etc/services':

vnc            5900/tcp

After you make inetd(8) reread its configuration (e.g. send the -HUP signal to it), you should be able to run the application with a VNC viewer of your choice.

If you instead want to have all subsequent connections share one application instance, change the line in '/etc/inetd.conf' to:

vnc stream tcp wait nobody /path/to/app app -t vnc:-server=stdio:-kold
Note

This assumes that the application supports the '-t' option to set the display target, and that it does not output anything at all on stdout/stderr. The application will run as the user 'nobody'.

Credits

The Tight encoding uses the jpeg library from the Independent JPEG Group.

Bugs

  • If the application does not give control to libgii with regular intervals (i.e. giiEventRead(3), giiEventPoll(3) or some wrapper that in turn calls one of these functions) this display target will not work, or at least not work well.
  • For the Tight encoding there are a few tunables left. 1) The "weight" of the different subencodings needs to be tuned. E.g. the gradient filter subencoding is never used, even if it should be very good on "blocky" data. 2) The jpeg quality selection could probably also be better tuned. 3) The client should be able to select the zlib compression level.
  • Special keys (i.e. shift, escape, etc) needs to be converted.