vncviewer(1)

vncviewer(1) — TightVNC 💅

Bestie, this is the manual page for vncviewer(1) from TightVNC. It's giving remote desktop, but make it X. 🦋

---

🎀 NAME 🎀

vncviewer — an X viewer client for VNC. That's the whole name, no cap. 👑

---

✨ SYNOPSIS ✨

vncviewer [options] [host][:display]
vncviewer [options] [host][::port]
vncviewer [options] -listen [display]
vncviewer -help

---

🌸 DESCRIPTION 🌸

Okay so 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 the desktop environment of a different machine. Iconic behaviour, honestly. 💖

You can use F8 to display a pop-up utility menu. Press F8 twice to pass single F8 to the remote side. Yes, twice. The double-tap is real. ✨

---

💅 OPTIONS 💅

• -help — Prints a short usage notice to stderr. Short and sweet, like a good text back. 💌
• -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. Reverse connection slay. 🔄
• -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. Tunnel vibes, but make it secure. 🔐
• -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. Sharing is caring, periodt. 🫶
• -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. Drama alert: someone's getting kicked or you're getting denied. 💀
• -viewonly — Disable transfer of mouse and keyboard events from the client to the server. Look, don't touch. Main character observer energy. 👀
• -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. Full screen, full chaos, sometimes. 😭
• -noraiseonbeep — By default, the viewer shows and raises its window on remote beep (bell) event. This option disables such behaviour (TightVNC-specific). No pop-up jumpscare when the remote machine beeps. 🔔
• -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. Password file, but make it VNC. 🔑
• -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. Encoding order is the real personality test. 🌈
• -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. Less traffic, slightly questionable colors. A trade-off. 🎨
• -owncmap — Try to use a PseudoColor visual and a private colormap. This allows the VNC server to control the colormap. Colormap control? Server said it's my turn. 🎛️
• -truecolour, -truecolor — Try to use a TrueColor visual. Both spellings, because inclusivity. ✅
• -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. Depth request, but polite. 🧊
• -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. Level 0 is not the vibe. Start at 1, bestie. 🔥
• -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. Quality 0 is giving potato, but sometimes potato is fine. 🥔
• -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). Only if you absolutely need perfect pixels. Otherwise, don't. 🚫
• -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. Cursor shape updates are lowkey the bandwidth saviour. 🖱️
• -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. Real cursor, real X11 energy. Dot cursor? Gone. ✨
• -autopass — Read a plain-text password from stdin. This option affects only the standard VNC authentication. Stdin password, no typing in the GUI. Convenient. ⌨️

---

🌈 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. Server chooses, client adapts. Flexible queen behaviour. 👑

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. Pixels, but with lore. 🎨

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. Rectangle gossip, incoming. 📦

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. Raw is the no-frills, same-machine speed demon. ⚡

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. Copy-paste, but make it VNC rectangles. 📋

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. Large blocks of one color? RRE ate. 🍽️

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. RRE's little sister, but more efficient. Family business. 👯

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). Ethernet LAN bestie. Hextile said I got you. 🌐

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. Good compression, hungry CPU. A classic trade-off. 🧮

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). Tight encoding is the main character of slow connections. 👑

✨ RESOURCES ✨

okay bestie so besides all the normal Xt resources, vncviewer has its own little stash of X resources it knows about 💖 here's the whole list, no skips, no cap:

• shareDesktop — literally the resource version of the -shared/-noshared options. Default is true. 👑
• viewOnly — the resource version of -viewonly. Default false.
• fullScreen — the resource version of -fullscreen. Default false.
• grabKeyboard — grabs the keyboard when you're in full-screen mode. this one is a lifesaver if your keyboard focus keeps ghosting you, ngl. Default false. 🫶
• raiseOnBeep — the resource version of -noraiseonbeep, but only when you set it to false. Default true.
• passwordFile — the resource version of -passwd.
• passwordDialog — whether to pop a dialog box for the password (true) or grab it from the tty (false). it does NOT matter at all if passwordFile is set, so don't stress. Default false.
• encodings — the resource version of -encodings.
• compressLevel — the resource version of -compresslevel (TightVNC-specific, iykyk).
• qualityLevel — the resource version of -quality (TightVNC-specific).
• enableJPEG — the resource version of -nojpeg, when set to false. Default true.
• useRemoteCursor — the resource version of -nocursorshape, when set to false (TightVNC-specific). Default true.
• useBGR233 — the resource version of -bgr233. Default false.
• nColours — when you're using BGR233, this is how many "exact" colors it tries to allocate from the BGR233 color cube. if you're on a shared colormap, setting this lower leaves more colors for the other X clients out there 🎀. totally irrelevant when you're using truecolor. Default is 256 (i.e. all of them).
• useSharedColours — if the number of "exact" BGR233 colors it successfully allocated is less than 256, the rest get filled in with the "nearest" colors that are available. this resource decides whether to use ONLY the "exact" BGR233 colors for that, or whether other clients' "shared" colors count too. Default true (i.e. use other clients' colors). 🌈
• forceOwnCmap — the resource version of -owncmap. Default false.
• forceTrueColour — the resource version of -truecolour. Default false.
• requestedDepth — the resource version of -depth.
• useSharedMemory — use the MIT shared memory extension if you're on the same machine as the X server. Default true. ✨
• wmDecorationWidth, wmDecorationHeight — the total width and height that window manager decorations eat up. this gets used to calculate the max size of the VNC viewer window. Default is width 4, height 24.
• bumpScrollTime, bumpScrollPixels — so when you're 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 max speed of that scrolling is bumpScrollPixels pixels every bumpScrollTime milliseconds. the actual speed will be slower than that, obviously, because it depends on how fast your machine is 💀. Default is 20 pixels every 25 milliseconds.
• popupButtonCount — how many buttons live in the popup window. check the README file for more info on how to customize the buttons, bestie.
• debug — for debugging. Default false.
• rawDelay, copyRectDelay — for debugging, and you can peep the README file for the details. Default 0 (off).

---

🌸 ENVIRONMENT 🌸

when you start it up with the -via option, vncviewer reads the VNC_VIA_CMD environment variable, expands the patterns that start with the % character, and then runs the result as a command — assuming it's gonna create the TCP tunnel that should be used for the VNC connection. 🦋

if it's not set, this environment variable defaults to:

/usr/bin/ssh -f -L %L:%H:%R %G sleep 20

here are the patterns it recognizes in the VNC_VIA_CMD 👇

heads up bestie: all the patterns %G, %H, %L and %R must be present in the command template. no skipping, fr fr.

• %% — 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. the TightVNC additions were implemented by Constantin Kaplinsky. and so many other people participated in development, testing and support — we love a collaborative slay 💅.

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>

---

okay that's the whole page bestie, you're officially a vncviewer scholar 🎓✨ this lil legend is dated August 2006 and it's vncviewer(1) — iconic, timeless, no notes. go forth and connect, you've got this 💖🦋🎀