vncviewer(1)

NAME
vncviewer - an X11 viewer/client for TurboVNC

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 server, allowing you to control the desktop environment of a different machine. Once connected, you can press F8 to display a pop-up configuration dialog. Press F8 twice to send an F8 keystroke to the remote system.

ENCODINGS
In order to simplify the implementation of the VNC viewer, the VNC protocol is designed such that the VNC server sends information in whatever format the viewer desires. If the viewer claims to support multiple formats, then the server will choose one. Pixel format refers to the mathematical representation of an individual pixel. The most common formats are "true color", in which each pixel is represented by separate red, green, and blue intensity values, and "pseudo color", in which each pixel is represented by an index into a table of red, green, and blue intensity values. Encoding refers to how an image is represented on the network. The VNC server normally sends only the areas of its display that have changed since the last framebuffer update. These areas are sent as separate rectangles of pixels, and each rectangle can be encoded using a different encoding type. All rectangles contain a header that specifies the location and size of the rectangle and how it was encoded. The encoding types supported by the TurboVNC Viewer are listed below.

Raw Raw encoding sends the raw pixel values from the VNC server's desktop, after first translating them into the viewer's preferred pixel format. Raw encoding is used by default whenever the server and viewer are running on the same machine. Otherwise, it is included only for compatibility with other VNC flavors and should not be used except when absolutely necessary.

CopyRect
    When an image rectangle has been moved from one location to another on the VNC server's desktop but has not otherwise changed, the CopyRect protocol sends only the new location of the rectangle and relies on the VNC viewer to copy the actual pixels. This saves network bandwidth when a window is moved around on the VNC server or when an application sends the same image over and over again.

Tight
    The Tight encoder attempts to encode each rectangle in the most efficient way possible by splitting it into subrectangles and encoding the subrectangles using different subencoding types. The process by which it does this is referred to as an encoding method. The Tight encoder first analyzes a rectangle to determine if any significant portion of it is solid, and if so, that portion is encoded as a bounding box and a fill color (Solid subencoding.) Of the remaining subrectangles, those with only two colors are encoded as a 1-bit-per-pixel bitmap with a 2-color palette (Mono subencoding), those with low numbers of unique colors are encoded as a color palette and an indexed bitmap containing 8 index bits per pixel (Indexed color subencoding), and subrectangles with high numbers of unique colors are encoded using either JPEG or arrays of RGB pixels (Raw subencoding), depending on the encoding method. Zlib can optionally be used to compress the indexed color, mono and raw subrectangles. TurboVNC uses a modified version of the TightVNC encoder that has been optimized for maximum performance with 3D and video workloads.

Hextile
    Hextile splits image rectangles into 16x16 tiles, which are sent in a predetermined order. Each tile is encoded using either Raw encoding or a variant of RRE (Rise-and-Run-length-Encoding, a 2D version of RLE.) Hextile is included only for compatibility with other VNC flavors. One can typically achieve the same compression with much less CPU time, or much better compression with the same CPU time, by using Tight encoding.

OPTIONS

-help
    Prints a brief list of command-line options.

-listen
    Start the viewer in "listen mode." The viewer will listen on port 5500+display for reverse connections from a VNC server. To connect to a listening viewer from the Unix/Linux TurboVNC Server, use the vncconnect(1) program.

-via gateway
    Automatically create an encrypted TCP tunnel to machine gateway, then use that tunnel to connect to a VNC server running on host. By default, this option invokes SSH local port forwarding and assumes that the SSH client binary is located at /usr/bin/ssh. Note that when using the -via option, the host machine name should be specified from the point of view of the gateway machine. For example, "localhost" denotes the gateway, not the machine on which vncviewer was launched. See the ENVIRONMENT section below for information on configuring the -via option.

-shared
    When connecting, request a shared session. In TurboVNC, this is the default. When the session is shared, other users can connect to the session (assuming they have the correct authentication credentials) and collaborate with the user who started the session.

-noshared
    When connecting, specify that the session may not be shared. If the TurboVNC Server is configured using default settings, then it will only allow you to connect in non-shared mode if no one else is already connected to the session. Otherwise, if others are already connected to the session, then the TurboVNC Server will deny your connection request if you specify this option.

-viewonly
    Disable transfer of mouse and keyboard events from the client to the server.

-fullscreen
    Start in full-screen mode.

-fsaltenter
    Normally, vncviewer will switch into and out of full-screen mode when Ctrl-Alt-Shift-F is pressed or "Full screen" is selected from the F8 menu. Specifying this option will additionally cause it to switch into and out of full-screen mode when Alt-Enter is pressed.

-noraiseonbeep
    By default, if an application running on the VNC server generates a "bell" event, it will cause the VNC viewer window to restore itself if it is minimized. Passing this option to the viewer causes it to ignore remote bell events.

-passwd passwd-file
    File from which to get the VNC password (as generated by the vncpasswd(1) program.) Irrelevant if Unix login authentication is used.

-user user-name
    Specify user name for Unix login authentication (Default: current user name.) This will force Unix login authentication to be used, if an authentication method that supports it is enabled in the VNC server.

-nounixlogin
    This will force standard VNC authentication to be used, if an authentication method that supports it is enabled in the VNC server. This is useful if the server is configured to prefer an authentication method that supports Unix login authentication and you want to override this preference for a particular connection (for instance, to use a one-time password.)

-encodings encoding-list
    This option specifies a list of encoding types that vncviewer is allowed to use. The default list is "tight copyrect" for remote connections and "raw copyrect" for local connections. You can specify "tight" as the encoding list in order to disable the use of CopyRect encoding (see the ENCODINGS section below for more information about CopyRect encoding.) This version of vncviewer also supports Hextile encoding, for compatibility with RealVNC. Specifying "hextile" at the head of the encoding list will force the use of this encoding type. Hextile will also be used automatically whenever you connect to any VNC server that doesn't support Tight encoding. Since Hextile uses a lot of CPU time to provide very little compression, you may wish to override this behavior and use Raw encoding instead if your network is sufficiently fast. For more information on encodings, see the ENCODINGS section below.

-bgr233
    Always use the BGR233 format to encode pixel data. This may reduce network bandwidth for certain types of workloads, but colors will be represented inaccurately. The bgr233 format is an 8-bit "true color" format, with 2 bits of blue, 3 bits of green, and 3 bits of red. If BGR233 is enabled along with Tight encoding, then JPEG subencoding is automatically disabled and cannot be re-enabled without restarting the viewer.

-owncmap
    Try to use a PseudoColor visual and a private colormap for the VNC viewer. This allows the VNC server to control the viewer's colormap.

-truecolour, -truecolor
    Try to use a TrueColor visual for the VNC viewer.

-depth depth
    If the VNC viewer is running on an X display that supports multiple TrueColor visuals of different depths, this option tells the viewer to use a visual with the specified depth (in bits per pixel.) If successful, the VNC server will send pixels using this color depth.

-compresslevel level
    When Tight encoding is used, the compression level specifies the amount of Zlib compression to apply to subrectangles encoded using the indexed color, mono, and raw subencoding types. If the JPEG subencoding type is enabled, then the compression level also defines the "palette threshold", or the minimum number of colors that a subrectangle must have before it is encoded using JPEG. Higher compression levels have higher palette thresholds and thus favor the use of indexed color subencoding, whereas lower compression levels favor the use of JPEG. Compression Level 1 is always the default whenever JPEG is enabled, because extensive experimentation has revealed no benefit to using higher compression levels with 3D and video workloads. However, v1.1 and later of the TurboVNC Server also supports Compression Level 2 when JPEG is enabled. Compression Level 2 can be shown to reduce the bandwidth of certain types of low-color 2D workloads by typically 20-40% (with a commensurate increase in CPU usage.)

-nojpeg
    Disable the JPEG subencoding type. Normally, when Tight encoding is used, TurboVNC will encode all subrectangles with high numbers of unique colors using JPEG and all other subrectangles using indexed color, mono, or solid subencoding. If this option is specified, then TurboVNC will use raw subencoding rather than JPEG to encode high-color subrectangles. The resulting "Lossless Tight" encoding method is mathematically lossless but will use significantly more network bandwidth than the Tight+JPEG encoding methods.

-samp 1X | 2X | 4X | gray
    Specifies the level of chrominance subsampling to use when compressing JPEG images with the Tight+JPEG encoding methods. When compressing an image using JPEG, the RGB pixels are first converted to the YUV colorspace, a colorspace in which each pixel is represented as a brightness (Y, or "luminance") value and a pair of color (U & V, or "chrominance") values. After this colorspace conversion, chrominance subsampling can be used to discard some of the chrominance components in order to save bandwidth. 1X subsampling (the default in TurboVNC) retains the chrominance components for all pixels, and thus it provides the best image quality but also uses the most network bandwidth and CPU time. 2X subsampling retains the chrominance components for every other pixel, and 4X subsampling retains the chrominance components for every fourth pixel (this is typically implemented as 2X subsampling in both X and Y directions.) Grayscale throws out all of the chrominance components, leaving only luminance. 2X and 4X subsampling will typically produce noticeable aliasing of lines and other sharp features, but with photographic or other "smooth" image content, it may be difficult to detect any difference between 1X, 2X, and 4X.

-quality level
    Specifies the JPEG quality (1..100) to use when compressing JPEG images with the Tight+JPEG encoding methods. Lower quality levels produce grainier JPEG images with more noticeable compression artifacts, but lower quality levels also use less network bandwidth and CPU time. The default quality level of 95, when used without chrominance subsampling, should produce compressed images whose compression artifacts are imperceptible to human vision ("perceptually lossless.")

-nocursorshape
    Normally, TurboVNC and compatible servers will send only changes to the remote mouse cursor's shape and position. This results in the best mouse responsiveness. Disabling cursor shape updates causes the server to instead draw the mouse cursor and send it to the viewer as an image every time the cursor moves. Thus, disabling cursor shape updates can increase network "chatter" between server and client significantly, which may cause performance problems on slow networks. However, disabling cursor shape updates can be advantageous with shared sessions, since it will allow you to see the cursor movements of other connected users.

-autopass
    Read a plain-text password from stdin and use this password when performing standard VNC or Unix login authentication. It is strongly recommended that this option be used only with a one-time password or other disposable token.

-singlebuffer
    The TurboVNC Viewer's default behavior is to wait until all rectangles in a framebuffer update have been received and decoded before it draws the framebuffer update to the screen. This is a form of double buffering, and it reduces tearing artifacts when 3D or video applications switch frames. Passing an argument of -singlebuffer to vncviewer will cause it to draw each rectangle in the framebuffer update as it is received. This may be desirable on very slow connections.

-lowqual
    Select the "Tight + Low Quality JPEG" encoding method. This is the equivalent of -samp 4X -quality 30. The Tight + Low Quality JPEG encoding method uses indexed color subencoding with Zlib compression level 1 to encode subrectangles with low numbers of unique colors and low-quality JPEG (quality level 30 with 4X subsampling) to encode all other subrectangles. This encoding method will produce very noticeable image compression artifacts on subrectangles with large numbers of unique colors, but it will perform optimally on low-bandwidth, high-latency connections such as broadband. You can use TurboVNC's "Lossless Refresh" feature if you need to occasionally send a frame without compression artifacts.

-medqual
    Select the "Tight + Medium Quality JPEG" encoding method. This is the equivalent of -samp 2X -quality 80. The Tight + Medium Quality JPEG encoding method uses indexed color subencoding with Zlib compression level 1 to encode subrectangles with low numbers of unique colors and medium-quality JPEG (quality level 80 with 2X subsampling) to encode all other subrectangles. This encoding method may produce some compression artifacts on subrectangles with large numbers of unique colors, but these artifacts are generally minor and not very noticeable. This encoding method uses about half the network bandwidth of the default encoding method (Tight + Perceptually Lossless JPEG) and about twice the network bandwidth of the Tight + Low Quality JPEG encoding method.

-lossless
    Select the "Lossless Tight" encoding method. This is the equivalent of -nojpeg -compresslevel 0. The Lossless Tight encoding method uses indexed color subencoding for subrectangles with low numbers of unique colors and raw subencoding for subrectangles with high numbers of unique colors. Zlib compression is never used, so this encoding method, on average, uses quite a bit less CPU time than Tight+JPEG. Although Lossless Tight uses significantly less bandwidth, on average, than Raw encoding, it uses much more bandwidth than the Tight+JPEG encoding methods and is thus only appropriate for use on gigabit and faster connections. One of the uses for Lossless Tight is to avoid decompression and recompression when running vncviewer inside of another remote display environment.

-losslesswan
    Select the "Lossless Tight + Zlib" encoding method. This is the equivalent of -nojpeg -compresslevel 1. The Lossless Tight + Zlib encoding method is the same as the Lossless Tight encoding method, except that it compresses all subrectangles with Zlib compression level 1 prior to transmission. For subrectangles with low numbers of unique colors, this encoding method will perform similarly to the Tight+JPEG methods. However, it will use significantly more bandwidth and CPU time than Tight+JPEG when sending subrectangles with high numbers of unique colors. The usefulness of this encoding method is debatable, but it is included for those who absolutely must use mathematically lossless compression in environments where performance is constrained more by the network than the server CPU. The Lossless Refresh feature in TurboVNC uses this encoding method.

-config config-file
    File from which to read connection information. This file can be generated by the Windows TurboVNC Viewer using the "Save connection info" feature.

RESOURCES
X resources for vncviewer can be set in a file called Vncviewer (case-sensitive), which can reside either in the user's home directory or in the system-wide resources directory (for instance, /usr/lib/X11/app-defaults). To set a resource in this file, use the following syntax: *resourceName: resourceValue For instance, *fullScreen: true X resources that vncviewer knows about, aside from the normal Xt resources, are as follows:

shareDesktop
    Equivalent of the -shared/-noshared options. Default true.

viewOnly
    Equivalent of the -viewonly option. Default false.

fullScreen
    Equivalent of the -fullscreen option. Default false.

grabKeyboard
    Grab keyboard in full-screen mode. This can help to solve problems with losing keyboard focus. Default true.

raiseOnBeep
    If set to false, this is the equivalent of the -noraiseonbeep option. Default true.

passwordFile
    Equivalent of the -passwd option.

passwordDialog
    If true, vncviewer will pop up a dialog box to get the password. Otherwise, it will get the password from the console. Irrelevant if passwordFile is set. Default false. If Unix login authentication is used, then the dialog will prompt for both the user name and the password.

userLogin
    Equivalent of the -user option.

noUnixLogin
    Equivalent of the -nounixlogin option.

encodings
    Equivalent of -encodings option.

compressLevel
    Equivalent of -compresslevel option

subsampling
    Equivalent of the -samp option

qualityLevel
    Equivalent of the -quality option

enableJPEG
    If set to false, this is the equivalent of the -nojpeg option. Default true.

doubleBuffer
    If set to false, this is the equivalent of the -singlebuffer option. Default true.

configFile
    Equivalent of the -config option.

useRemoteCursor
    If set to false, this is the equivalent of the -nocursorshape option. 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 the MIT shared memory extension if the viewer is running 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. The default width is 4, and the default height is 24.

bumpScrollTime, bumpScrollPixels
    When the viewer is in full-screen mode and the VNC desktop is bigger than the client's X display, scrolling will occur 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 is 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 uses the resulting command line to establish the secure tunnel to the VNC gateway. If VNC_VIA_CMD is not set, this command line defaults to "/usr/bin/ssh -f -L %L:%H:%R %G sleep 20". The following patterns are recognized in the VNC_VIA_CMD environment (note that all of the patterns %G, %H, %L and %R must be present in the command template):

%%  A literal "%";

%G  gateway machine name;

%H  remote VNC machine name, from the point of view of 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
VNC was originally developed at AT&T Laboratories Cambridge. TightVNC additions were implemented by Constantin Kaplinsky. TurboVNC, based on TightVNC, is provided by The VirtualGL Project. 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>
D. R. Commander <information@virtualgl.org>
Craig Ruff <cruff@ucar.edu>