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 VNC server.

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 With Raw encoding, the server sends the raw pixel values from the remote 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. It should not be used on a remote connection except when absolutely necessary.

CopyRect
    When a region of pixels has been moved from one location to another on the remote desktop but has not otherwise changed, the CopyRect protocol sends only the new location of the region and relies on the VNC viewer to copy the actual pixels. This saves network bandwidth when, for instance, a window is moved around on the remote desktop.

Tight
    The Tight encoder attempts to encode each framebuffer update 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 rectangles into 16x16 tiles, which are sent in a predetermined order. Each tile is encoded using either Raw encoding or a variant of RRE. 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.

-ipv6
    When used with -listen, this causes vncviewer to accept connections from IPv6-enabled servers. If your system supports IPv4-mapped IPv6 addresses, then connections from IPv4 servers can also be accepted when this option is enabled.

-shared (default) / -noshared
    By default, TurboVNC requests a shared session. 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. 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 -noshared.

-viewonly / -fullcontrol (default)
    View-only disables the transfer of mouse and keyboard events from the client to the server.

-fullscreen / -nofullscreen (default)
    Start/don't start in full-screen mode.

-fsaltenter / -nofsaltenter (default)
    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. Passing -fsaltenter to vncviewer will additionally cause it to switch into and out of full-screen mode when Alt-Enter is pressed.

-grabkeyboard fs (default) | always | manual
    Normally, vncviewer will grab the keyboard when it switches to full-screen mode and ungrab it when it leaves full-screen mode (equivalent of -grabkeyboard fs). Grabbing the keyboard ensures that all special keystrokes, such as those used to switch windows, will be passed to the server rather than processed by the client's window manager. Passing an argument of -grabkeyboard always to vncviewer will cause it to grab the keyboard when the application starts, regardless of whether full-screen mode is active. Passing an argument of -grabkeyboard manual will prevent vncviewer from automatically grabbing the keyboard. The keyboard can always be manually grabbed and ungrabbed by pressing Ctrl-Alt-Shift-G or selecting "Grab Keyboard" from the F8 menu. NOTE: This option does nothing on Mac systems. Grabbing the keyboard does not work properly with Mac X servers, and it is also not as important a feature on that platform, since special keystrokes like Alt-Tab, etc. are not intercepted by the client's window manager.

-doublebuffer (default) / -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.

-raiseonbeep (default) / -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 -noraiseonbeep to vncviewer causes it to ignore remote bell events.

-8bit / -no8bit (default)
    Use/don't use the BGR233 format to encode pixel data. BGR233 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.

-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.

-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.

-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.

-jpeg (default) / -nojpeg
    Enable/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 -nojpeg 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.

-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.")

-samp 1X (default) | 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 YCbCr colorspace, a colorspace in which each pixel is represented as a brightness (Y, or "luminance") value and a pair of color (Cb & Cr, 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.

-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.) In v1.2 or later of the TurboVNC Server, compression levels 5-7 map to compression levels 0-2, but they also enable the interframe comparison engine in the server. Interframe comparison maintains a copy of the remote framebuffer for each connected viewer and compares each framebuffer update with the copy to ensure that redundant updates are not sent to the viewer. This prevents unnecessary network traffic if an ill-behaved application draws the same thing over and over again, but interframe comparison also causes the TurboVNC Server to use more CPU time and much more memory.

-lowqual
    Select the "Tight + Low Quality JPEG" encoding method. This is the equivalent of -jpeg -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 -jpeg -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 visible 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.

-highqual
    Select the "Tight + Perceptually Lossless JPEG" encoding method. This is the equivalent of -jpeg -samp 1X -quality 95. The Tight + Perceptually Lossless JPEG encoding method uses indexed color subencoding with zlib compression level 1 to encode subrectangles with low numbers of unique colors and perceptually lossless JPEG (quality level 95 with 1X subsampling) to encode all other subrectangles. Any compression artifacts generated by this encoding method should be imperceptible to human vision under normal viewing conditions. This encoding method uses about twice the network bandwidth of the Tight + Medium 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.

-cursorshape (default) / -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.

-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.)

-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.

-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.

-via [ssh_user@]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.

-tunnel
    Automatically create an encrypted TCP tunnel to machine host, then use that tunnel to connect to a VNC server running on that same machine. Specifying -tunnel [ssh_user@]host:display is the same as specifying -via [ssh_user@]host localhost:display. See the ENVIRONMENT section below for information on configuring the -tunnel option.

-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 Tvncviewer (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:

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

viewOnly
    Equivalent of the -viewonly/-fullcontrol options. Default false.

fullScreen
    Equivalent of the -fullscreen/-nofullscreen options. Default false.

fsAltEnter
    Equivalent of the -fsaltenter/-nofsaltenter options. Default false.

grabKeyboard
    Equivalent of the -grabkeyboard option. Default = fs.

doubleBuffer
    Equivalent of the -doublebuffer/-singlebuffer options. Default true.

sharedMemory
    Use the MIT shared memory extension if the viewer is running on the same machine as the X server. Default true.

raiseOnBeep
    Equivalent of the -raiseonbeep/-noraiseonbeep options. Default true.

8Bit
    Equivalent of the -8bit/-no8bit options. Default false.

nColors
    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).

sharedColors
    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 the -owncmap option. Default false.

forceTrueColor
    Equivalent of the -truecolor option. Default false.

requestedDepth
    Equivalent of the -depth option.

encodings
    Equivalent of the -encodings option.

JPEG
    Equivalent of the -jpeg/-nojpeg options. Default true.

quality
    Equivalent of the -quality option

subsampling
    Equivalent of the -samp option

compressLevel
    Equivalent of the -compresslevel option

cursorShape
    Equivalent of the -cursorshape/-nocursorshape options. Default true.

userLogin
    Equivalent of the -user option.

noUnixLogin
    Equivalent of the -nounixlogin option.

passwordFile
    Equivalent of the -passwd option.

autoPass
    Equivalent of the -autopass 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.

configFile
    Equivalent of the -config option.

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, then this command line defaults to "/usr/bin/ssh -f -L %L:%H:%R %G sleep 20". When started with the -tunnel option, vncviewer reads the VNC_TUNNEL_CMD environment variable, expands patterns beginning with the "%" character, and uses the resulting command line to establish the secure tunnel to the VNC server. If VNC_TUNNEL_CMD is not set, then this command line defaults to "/usr/bin/ssh -f -L %L:localhost:%R %H sleep 20". The following patterns are recognized in the VNC_VIA_CMD and VNC_TUNNEL_CMD environment variables (note that %H, %L and %R must be present in the command template, and %G must also be present if using the -via option):

%%  A literal "%"

%G  gateway machine name

%H  remote VNC machine name (if using the -via option, then this is specified 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>