Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
vncviewer(1)			   TightVNC			  vncviewer(1)

       vncviewer - an X	viewer client for VNC

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

       vncviewer  is  an Xt-based client application for the VNC (Virtual Net-
       work 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.

       -help  Prints a short usage notice to stderr.

	      Make  the	viewer listen on port 5500+display for reverse connec-
	      tions 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.

	      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.

	      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.

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

	      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.

	      By default, the viewer shows and raises  its  window  on	remote
	      beep   (bell)   event.   This  option  disables  such  behaviour

       -user username
	      User name	for Unix login authentication. Default is to use  cur-
	      rent  Unix  user name. If	this option was	given, the viewer will
	      prefer Unix login	authentication over the	standard VNC authenti-

       -passwd passwd-file
	      File  from  which	 to get	the password (as generated by the vnc-
	      passwd(1)	program). This option affects only  the	 standard  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.

	      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.

	      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 dif-
	      ferent depths, attempt to	use the	specified  one	(in  bits  per
	      pixel); if successful, this depth	will be	requested from the VNC

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

	      Disable  lossy JPEG compression in Tight encoding	(TightVNC-spe-
	      cific).  Disabling JPEG compression is not a good	idea in	 typi-
	      cal  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).

	      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

	      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.

	      Read a plain-text	password from stdin. This option affects  only
	      the standard VNC authentication.

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

	      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 iden-
	      tical  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 con-
	      stant 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.

	      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  com-
	      press  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  compres-
	      sion  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 net-
	      work environments	(e.g. slow modem connections).

       X  resources  that  vncviewer  knows  about,  aside  from the normal Xt
       resources, are as follows:

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

	      Equivalent of -viewonly option. Default false.

	      Equivalent of -fullscreen	option.	Default	false.

	      Grab keyboard in full-screen mode. This can help to solve	 prob-
	      lems with	losing keyboard	focus. Default false.

	      Equivalent  of -noraiseonbeep option, when set to	false. Default

	      Equivalent of -passwd option.

	      Equivalent of -user option.

	      Whether to use a dialog box to get the password (true) or	get it
	      from the tty (false). Irrelevant if passwordFile is set. Default

	      Equivalent of -encodings option.

	      Equivalent of -compresslevel option (TightVNC-specific).

	      Equivalent of -quality option (TightVNC-specific).

	      Equivalent of -nojpeg option, when set to	false. Default true.

	      Equivalent  of  -nocursorshape  option,  when   set   to	 false
	      (TightVNC-specific). Default true.

	      Equivalent of -bgr233 option. Default false.

	      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

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

	      Equivalent of -owncmap option. Default false.

	      Equivalent of -truecolour	option.	Default	false.

	      Equivalent of -depth option.

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

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

       When  started  with  the	 -via  option, vncviewer reads the VNC_VIA_CMD
       environment variable, expands patterns beginning	with the  "%"  charac-
       ter, and	executes result	as a command assuming that it would create TCP
       tunnel that should be used for VNC connection. If not set,  this	 envi-
       ronment 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  tem-

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

       vncserver(1), Xvnc(1), vncpasswd(1), vncconnect(1), ssh(1)

       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	<>,
       Terran Melconian	<>,
       Tim Waugh <>,
       Constantin Kaplinsky <>

				  August 2006			  vncviewer(1)


Want to link to this manual page? Use this URL:

home | help