NAME
vncviewer - an X viewer client for VNC
SYNOPSIS
vncviewer [options] [host][:display]
vncviewer [options] [host][::port]
vncviewer [options] -listen [display]
vncviewer -help
DESCRIPTION
vncviewer 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 forwarding, 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 specified as known to the gateway
machine, e.g. "localhost" 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 connected 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
setting 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).
-user username
User name for Unix login authentication. Default is to use
current Unix user name. If this option was given, the viewer
will prefer Unix login authentication over the standard VNC
authentication.
-passwd passwd-file
File from which to get the password (as generated by the
vncpasswd(1) program). This option affects only the standard VNC
authentication.
-encodings encoding-list
TightVNC supports several different compression methods to
encode screen updates; this option specifies 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 hextile 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 colormap. 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 compression 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 compression 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
dramatically.
-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.
-autopass
Read a plain-text password from stdin. This option affects only
the standard VNC authentication.
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" representations, 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 rectangles 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 something 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 compressed to a single value and repeat
count. In VNC, this is implemented with a background color, and
then specifications of an arbitrary number of subrectangles 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 single-byte values to be used,
reducing packet size. This is in general more efficient, because
the savings 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-processes data to maximize
compression ratios, and to minimize CPU usage on compression.
Also, JPEG compression 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.
userLogin
Equivalent of -user 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-specific).
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 manager
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 whenever the mouse hits the edge of
the screen. The maximum speed of scrolling is bumpScrollPixels
pixels 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 customize 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 beginning with the "%"
character, and executes result as a command 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 present 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 ALSO
vncserver(1), Xvnc(1), vncpasswd(1), vncconnect(1), ssh(1)
AUTHORS
Original VNC was developed in AT&T Laboratories Cambridge. TightVNC
additions were implemented by Constantin Kaplinsky. Many other people
participated in development, testing 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@tightvnc.com>
August 2006 vncviewer(1)