vncviewer(1) TightVNC vncviewer(1)NAMEvncviewer - an X viewer client for VNC
SYNOPSISvncviewer [options] [host][:display]
vncviewer [options] [host][::port]
vncviewer [options] -listen [display]
vncviewer-help
DESCRIPTIONvncviewer is an Xt-based client application for the VNC
(Virtual Network Computing) system. It can connect to any
VNC-compatible server such as Xvnc or WinVNC, allowing you
to control desktop environment of a different machine.
You can use F8 to display a pop-up utility menu. Press F8
twice to pass single F8 to the remote side.
OPTIONS-help Prints a short usage notice to stderr.
-listen
Make the viewer listen on port 5500+display for
reverse connections from a server. WinVNC supports
reverse connections using the "Add New Client" menu
option, or the -connect command line option. Xvnc
requires the use of the helper program vncconnect.
-via gateway
Automatically create encrypted TCP tunnel to the
gateway machine before connection, connect to the
host through that tunnel (TightVNC-specific). By
default, this option invokes SSH local port for-
warding, assuming that SSH client binary can be
accessed as /usr/bin/ssh. Note that when using the
-via option, the host machine name should be speci-
fied as known to the gateway machine, e.g. "local-
host" denotes the gateway, not the machine where
vncviewer was launched. See the ENVIRONMENT section
below for the information on configuring the -via
option.
-shared
When connecting, specify that a shared connection
is requested. In TightVNC, this is the default
mode, allowing you to share the desktop with other
clients already using it.
-noshared
When connecting, specify that the session may not
be shared. This would either disconnect other con-
nected clients or refuse your connection, depending
on the server configuration.
-viewonly
Disable transfer of mouse and keyboard events from
the client to the server.
-fullscreen
Start in full-screen mode. Please be aware that
operating in full-screen mode may confuse X window
managers. Typically, such conflicts cause incorrect
handling of input focus or make the viewer window
disappear mysteriously. See the grabKeyboard set-
ting in the RESOURCES section below for a method to
solve input focus problem.
-noraiseonbeep
By default, the viewer shows and raises its window
on remote beep (bell) event. This option disables
such behaviour (TightVNC-specific).
-passwd passwd-file
File from which to get the password (as generated
by the vncpasswd(1) program).
-encodings encoding-list
TightVNC supports several different compression
methods to encode screen updates; this option spec-
ifies a set of them to use in order of preference.
Encodings are specified separated with spaces, and
must thus be enclosed in quotes if more than one is
specified. Available encodings, in default order
for a remote connection, are "copyrect tight hex-
tile zlib corre rre raw". For a local connection
(to the same machine), the default order to try is
"raw copyrect tight hextile zlib corre rre". Raw
encoding is always assumed as a last option if no
other encoding can be used for some reason. For
more information on encodings, see the section
ENCODINGS below.
-bgr233
Always use the BGR233 format to encode pixel data.
This reduces network traffic, but colors may be
represented inaccurately. The bgr233 format is an
8-bit "true color" format, with 2 bits blue, 3 bits
green, and 3 bits red.
-owncmap
Try to use a PseudoColor visual and a private col-
ormap. This allows the VNC server to control the
colormap.
-truecolour, -truecolor
Try to use a TrueColor visual.
-depth depth
On an X server which supports multiple TrueColor
visuals of different depths, attempt to use the
specified one (in bits per pixel); if successful,
this depth will be requested from the VNC server.
-compresslevel level
Use specified compression level (0..9) for "tight"
and "zlib" encodings (TightVNC-specific). Level 1
uses minimum of CPU time and achieves weak compres-
sion ratios, while level 9 offers best compression
but is slow in terms of CPU time consumption on the
server side. Use high levels with very slow network
connections, and low levels when working over
high-speed LANs. It's not recommended to use com-
pression level 0, reasonable choices start from the
level 1.
-quality level
Use the specified JPEG quality level (0..9) for the
"tight" encoding (TightVNC-specific). Quality level
0 denotes bad image quality but very impressive
compression ratios, while level 9 offers very good
image quality at lower compression ratios. Note
that the "tight" encoder uses JPEG to encode only
those screen areas that look suitable for lossy
compression, so quality level 0 does not always
mean unacceptable image quality.
-nojpeg
Disable lossy JPEG compression in Tight encoding
(TightVNC-specific). Disabling JPEG compression is
not a good idea in typical cases, as that makes the
Tight encoder less efficient. You might want to use
this option if it's absolutely necessary to achieve
perfect image quality (see also the -quality
option).
-nocursorshape
Disable cursor shape updates, protocol extensions
used to handle remote cursor movements locally on
the client side (TightVNC-specific). Using cursor
shape updates decreases delays with remote cursor
movements, and can improve bandwidth usage dramati-
cally.
-x11cursor
Use a real X11 cursor with X-style cursor shape
updates, instead of drawing the remote cursor on
the framebuffer. This option also disables the dot
cursor, and disables cursor position updates in
non-fullscreen mode.
ENCODINGS
The server supplies information in whatever format is
desired by the client, in order to make the client as easy
as possible to implement. If the client represents itself
as able to use multiple formats, the server will choose
one.
Pixel format refers to the representation of an individual
pixel. The most common formats are 24 and 16 bit
"true-color" values, and 8-bit "color map" representa-
tions, where an arbitrary map converts the color number to
RGB values.
Encoding refers to how a rectangle of pixels are sent (all
pixel information in VNC is sent as rectangles). All rect-
angles come with a header giving the location and size of
the rectangle and an encoding type used by the data which
follows. These types are listed below.
Raw The raw encoding simply sends width*height pixel
values. All clients are required to support this
encoding type. Raw is also the fastest when the
server and viewer are on the same machine, as the
connection speed is essentially infinite and raw
encoding minimizes processing time.
CopyRect
The Copy Rectangle encoding is efficient when some-
thing is being moved; the only data sent is the
location of a rectangle from which data should be
copied to the current location. Copyrect could also
be used to efficiently transmit a repeated pattern.
RRE The Rise-and-Run-length-Encoding is basically a 2D
version of run-length encoding (RLE). In this
encoding, a sequence of identical pixels are com-
pressed to a single value and repeat count. In VNC,
this is implemented with a background color, and
then specifications of an arbitrary number of sub-
rectangles and color for each. This is an efficient
encoding for large blocks of constant color.
CoRRE This is a minor variation on RRE, using a maximum
of 255x255 pixel rectangles. This allows for sin-
gle-byte values to be used, reducing packet size.
This is in general more efficient, because the sav-
ings from sending 1-byte values generally outweighs
the losses from the (relatively rare) cases where
very large regions are painted the same color.
Hextile
Here, rectangles are split up in to 16x16 tiles,
which are sent in a predetermined order. The data
within the tiles is sent either raw or as a variant
on RRE. Hextile encoding is usually the best choice
for using in high-speed network environments (e.g.
Ethernet local-area networks).
Zlib Zlib is a very simple encoding that uses zlib
library to compress raw pixel data. This encoding
achieves good compression, but consumes a lot of
CPU time. Support for this encoding is provided for
compatibility with VNC servers that might not
understand Tight encoding which is more efficient
than Zlib in nearly all real-life situations.
Tight Like Zlib encoding, Tight encoding uses zlib
library to compress the pixel data, but it pre-pro-
cesses data to maximize compression ratios, and to
minimize CPU usage on compression. Also, JPEG com-
pression may be used to encode color-rich screen
areas (see the description of -quality and -nojpeg
options above). Tight encoding is usually the best
choice for low-bandwidth network environments (e.g.
slow modem connections).
RESOURCES
X resources that vncviewer knows about, aside from the
normal Xt resources, are as follows:
shareDesktop
Equivalent of -shared/-noshared options. Default
true.
viewOnly
Equivalent of -viewonly option. Default false.
fullScreen
Equivalent of -fullscreen option. Default false.
grabKeyboard
Grab keyboard in full-screen mode. This can help to
solve problems with losing keyboard focus. Default
false.
raiseOnBeep
Equivalent of -noraiseonbeep option, when set to
false. Default true.
passwordFile
Equivalent of -passwd option.
passwordDialog
Whether to use a dialog box to get the password
(true) or get it from the tty (false). Irrelevant
if passwordFile is set. Default false.
encodings
Equivalent of -encodings option.
compressLevel
Equivalent of -compresslevel option (TightVNC-spe-
cific).
qualityLevel
Equivalent of -quality option (TightVNC-specific).
enableJPEG
Equivalent of -nojpeg option, when set to false.
Default true.
useRemoteCursor
Equivalent of -nocursorshape option, when set to
false (TightVNC-specific). Default true.
useBGR233
Equivalent of -bgr233 option. Default false.
nColours
When using BGR233, try to allocate this many
"exact" colors from the BGR233 color cube. When
using a shared colormap, setting this resource
lower leaves more colors for other X clients.
Irrelevant when using truecolor. Default is 256
(i.e. all of them).
useSharedColours
If the number of "exact" BGR233 colors successfully
allocated is less than 256 then the rest are filled
in using the "nearest" colors available. This
resource says whether to only use the "exact"
BGR233 colors for this purpose, or whether to use
other clients' "shared" colors as well. Default
true (i.e. use other clients' colors).
forceOwnCmap
Equivalent of -owncmap option. Default false.
forceTrueColour
Equivalent of -truecolour option. Default false.
requestedDepth
Equivalent of -depth option.
useSharedMemory
Use MIT shared memory extension if on the same
machine as the X server. Default true.
wmDecorationWidth, wmDecorationHeight
The total width and height taken up by window man-
ager decorations. This is used to calculate the
maximum size of the VNC viewer window. Default is
width 4, height 24.
bumpScrollTime, bumpScrollPixels
When in full screen mode and the VNC desktop is
bigger than the X display, scrolling happens when-
ever the mouse hits the edge of the screen. The
maximum speed of scrolling is bumpScrollPixels pix-
els every bumpScrollTime milliseconds. The actual
speed of scrolling will be slower than this, of
course, depending on how fast your machine is.
Default 20 pixels every 25 milliseconds.
popupButtonCount
The number of buttons in the popup window. See the
README file for more information on how to cus-
tomize the buttons.
debug For debugging. Default false.
rawDelay, copyRectDelay
For debugging, see the README file for details.
Default 0 (off).
ENVIRONMENT
When started with the -via option, vncviewer reads the
VNC_VIA_CMD environment variable, expands patterns begin-
ning with the "%" character, and executes result as a com-
mand assuming that it would create TCP tunnel that should
be used for VNC connection. If not set, this environment
variable defaults to "/usr/bin/ssh -f -L %L:%H:%R %G sleep
20".
The following patterns are recognized in the VNC_VIA_CMD
(note that all the patterns %G, %H, %L and %R must be pre-
sent in the command template):
%% A literal "%";
%G gateway host name;
%H remote VNC host name, as known to the gateway;
%L local TCP port number;
%R remote TCP port number.
SEE ALSOvncserver(1), Xvnc(1), vncpasswd(1), vncconnect(1), ssh(1)AUTHORS
Original VNC was developed in AT&T Laboratories Cambridge.
TightVNC additions was implemented by Constantin Kaplin-
sky. Many other people participated in development, test-
ing and support.
Man page authors:
Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de>,
Terran Melconian <terran@consistent.org>,
Tim Waugh <twaugh@redhat.com>,
Constantin Kaplinsky <const@ce.cctpu.edu.ru>
January 2003 vncviewer(1)
