1vncviewer(1)               Virtual Network Computing              vncviewer(1)
2
3
4

NAME

6       vncviewer - VNC viewer for X
7

SYNOPSIS

9       vncviewer [options] [host][:display#]
10       vncviewer [options] [host][::port]
11       vncviewer [options] [unix socket]
12       vncviewer [options] -listen [port]
13       vncviewer [options] [.tigervnc file]
14

DESCRIPTION

16       vncviewer  is  a  viewer  (client) for Virtual Network Computing.  This
17       manual page documents version 4 for the X window system.
18
19       If you run the viewer with no arguments it will prompt you  for  a  VNC
20       server  to connect to.  Alternatively, specify the VNC server as an ar‐
21       gument, e.g.:
22
23              vncviewer snoopy:2
24
25       where 'snoopy' is the name of the machine, and '2' is the display  num‐
26       ber of the VNC server on that machine.  Either the machine name or dis‐
27       play number can be omitted.  So for example ":1" means display number 1
28       on  the  same  machine, and "snoopy" means "snoopy:0" i.e. display 0 on
29       machine "snoopy".
30
31       As another quick way to start a connection to a VNC server,  specify  a
32       .tigervnc configuration file as an argument to the viewer, e.g.:
33
34              vncviewer ./some.tigervnc
35
36       where './some.tigervnc' is an existing and valid TigerVNC configuration
37       file.  The file name needs to include a path separator.  Additional op‐
38       tions may be given too, but the given configuration file will overwrite
39       any conflicting parameters.
40
41       If the VNC server is successfully contacted, you will be prompted for a
42       password  to  authenticate  you.  You  can  also add 'VNC_USERNAME' and
43       'VNC_PASSWORD' to environment variables. If the password is correct,  a
44       window will appear showing the desktop of the VNC server.
45
46

AUTOMATIC PROTOCOL SELECTION

48       The  viewer tests the speed of the connection to the server and chooses
49       the encoding and pixel format (color level) appropriately.  This  makes
50       it  much  easier  to  use  than previous versions where the user had to
51       specify arcane command line arguments.
52
53       The viewer normally starts out assuming the link is slow, using the en‐
54       coding  with  the  best  compression.  If it turns out that the link is
55       fast enough it switches to an encoding which  compresses  less  but  is
56       faster to generate, thus improving the interactive feel.
57
58       The  viewer  normally  starts  in full-color mode, but switches to low-
59       color mode if the bandwidth is insufficient. However, this only  occurs
60       when communicating with servers supporting protocol 3.8 or newer, since
61       many old servers does not support color mode changes safely.
62
63       Automatic selection can be turned off by setting the AutoSelect parame‐
64       ter to false, or from the options dialog.
65
66
68       The  viewer  has  a popup menu containing entries which perform various
69       actions.  It is usually brought up by pressing F8, but this can be con‐
70       figured  with  the MenuKey parameter.  Actions which the popup menu can
71       perform include:
72
73         * switching in and out of full-screen mode
74
75         * quitting the viewer
76
77         * generating key events, e.g. sending ctrl-alt-del
78
79         * accessing the options dialog and various other dialogs
80
81       By default, key presses in the popup menu get sent to  the  VNC  server
82       and  dismiss the popup.  So to get an F8 through to the VNC server sim‐
83       ply press it twice.
84
85

FULL SCREEN MODE

87       A full-screen mode is supported.  This is particularly useful when con‐
88       necting to a remote screen which is the same size as your local one. If
89       the remote screen is bigger,  you  can  scroll  by  bumping  the  mouse
90       against the edge of the screen.
91
92

OPTIONS (PARAMETERS)

94       You  can get a list of parameters by giving -h as a command-line option
95       to vncviewer.  Parameters can be turned on  with  -param  or  off  with
96       -param=0.   Parameters  which  take  a value can be specified as -param
97       value.  Other valid forms are param=value  -param=value  --param=value.
98       Parameter names are case-insensitive.
99
100       Many of the parameters can also be set graphically via the options dia‐
101       log box.  This can be accessed from the popup menu or from the "Connec‐
102       tion details" dialog box.
103
104
105       -display Xdisplay
106              Specifies  the  X  display on which the VNC viewer window should
107              appear.
108
109       -geometry geometry
110              Initial position of the main VNC viewer window.  The  format  is
111              widthxheight+xoffset+yoffset  ,  where `+' signs can be replaced
112              with `-' signs to specify offsets from the right and/or from the
113              bottom  of the screen.  Offsets are optional and the window will
114              be placed by the window manager by default.
115
116       -listen [port]
117              Causes vncviewer to listen on the given port (default 5500)  for
118              reverse  connections from a VNC server.  WinVNC supports reverse
119              connections initiated using the 'Add New Client' menu option  or
120              the  '-connect' command-line option.  Xvnc supports reverse con‐
121              nections with a helper program called vncconfig.
122
123       -SecurityTypes sec-types
124              Specify which security schemes to attempt to use when  authenti‐
125              cating with the server.  Valid values are a comma separated list
126              of None, VncAuth, Plain, TLSNone,  TLSVnc,  TLSPlain,  X509None,
127              X509Vnc  and  X509Plain.  Default  is to attempt every supported
128              scheme.
129
130       -passwd, -PasswordFile password-file
131              If you are on a filesystem which gives you access to  the  pass‐
132              word  file  used by the server, you can specify it here to avoid
133              typing it in.  It will usually be "~/.vnc/passwd".
134
135       -X509CA path
136              Path to CA certificate to use when authenticating remote servers
137              using  any  of  the  X509  security  schemes (X509None, X509Vnc,
138              etc.). Must be in PEM format. Default is $HOME/.vnc/x509_ca.pem.
139
140       -X509CRL path
141              Path to certificate revocation list to use in  conjunction  with
142              -X509CA.    Must   also   be   in   PEM   format.   Default   is
143              $HOME/.vnc/x509_crl.pem.
144
145       -Shared
146              When you make a connection to a VNC server, all  other  existing
147              connections are normally closed.  This option requests that they
148              be left open, allowing you to share the desktop with someone al‐
149              ready using it.
150
151       -ViewOnly
152              Specifies that no keyboard or mouse events should be sent to the
153              server.  Useful if you want to view a desktop without  interfer‐
154              ing; often needs to be combined with -Shared.
155
156       -AcceptClipboard
157              Accept clipboard changes from the server. Default is on.
158
159       -SetPrimary
160              Set  the  primary  selection as well as the clipboard selection.
161              Default is on.
162
163       -MaxCutText bytes
164              The maximum size of a clipboard update  that  will  be  accepted
165              from a server.  Default is 262144.
166
167       -SendClipboard
168              Send clipboard changes to the server. Default is on.
169
170       -SendPrimary
171              Send  the  primary  selection to the server as well as the clip‐
172              board selection. Default is on.
173
174       -Maximize
175              Maximize viewer window.
176
177       -FullScreen
178              Start in full-screen mode.
179
180       -FullScreenAllMonitors (DEPRECATED)
181              Use all local monitors and not just the current one when switch‐
182              ing to full-screen mode. Replaced by -FullScreenMode=all
183
184       -FullScreenMode mode
185              Specify  which monitors to use when in full screen. It should be
186              either "Current", "Selected" (specified by  -FullScreenSelected‐
187              Monitors) or "All".  The default is "Current".
188
189       -FullScreenSelectedMonitors monitors
190              This  option  specifies  the  monitors  to use with -FullScreen‐
191              Mode=selected.  Monitors are ordered  according  to  the  system
192              configuration  from  left  to  right, and in case of a conflict,
193              from top to bottom. So, for  example,  "1,2,3"  means  that  the
194              first, second and third monitor counting from the left should be
195              used.  The default is "1".
196
197       -FullscreenSystemKeys
198              Pass special keys (like Alt+Tab) directly to the server when  in
199              full-screen mode.
200
201       -DesktopSize widthxheight
202              Instead  of  keeping the existing remote screen size, the client
203              will attempt to switch to the specified since  when  connecting.
204              If  the  server does not support the SetDesktopSize message then
205              the screen will retain the original size.
206
207       -RemoteResize
208              Dynamically resize the remote desktop size as the  size  of  the
209              local  client  window  changes. Note that this may not work with
210              all VNC servers.
211
212       -AutoSelect
213              Use automatic selection of encoding and pixel format (default is
214              on).   Normally  the viewer tests the speed of the connection to
215              the server and chooses the encoding and pixel  format  appropri‐
216              ately.  Turn it off with -AutoSelect=0.
217
218       -FullColor, -FullColour
219              Tells  the VNC server to send full-color pixels in the best for‐
220              mat for this display.  This is default.
221
222       -LowColorLevel, -LowColourLevel level
223              Selects the reduced color level to use on slow links.  level can
224              range  from 0 to 2, 0 meaning 8 colors, 1 meaning 64 colors (the
225              default), 2 meaning 256 colors. Note that  decision  if  reduced
226              color  level  is used is made by vncviewer. If you would like to
227              force vncviewer to use reduced color level use -AutoSelect=0 pa‐
228              rameter.
229
230       -PreferredEncoding encoding
231              This  option specifies the preferred encoding to use from one of
232              "Tight", "ZRLE", "hextile" or "raw".
233
234       -NoJpeg
235              Disable lossy JPEG compression in  Tight  encoding.  Default  is
236              off.
237
238       -QualityLevel level
239              JPEG quality level. 0 = Low, 9 = High. May be adjusted automati‐
240              cally if -AutoSelect is turned on. Default is 8.
241
242       -CompressLevel level
243              Use specified lossless compression level. 0 = Low, 9 = High. De‐
244              fault is 2.
245
246       -CustomCompressLevel
247              Use custom compression level. Default if CompressLevel is speci‐
248              fied.
249
250       -DotWhenNoCursor
251              Show the dot cursor when the server sends an  invisible  cursor.
252              Default is off.
253
254       -PointerEventInterval time
255              Time  in  milliseconds  to rate-limit successive pointer events.
256              Default is 17 ms (60 Hz).
257
258       -EmulateMiddleButton
259              Emulate middle mouse button by pressing  left  and  right  mouse
260              buttons simultaneously. Default is off.
261
262       -Log logname:dest:level
263              Configures the debug log settings.  dest can currently be stderr
264              or stdout, and level is between 0 and 100, 100 meaning most ver‐
265              bose output.  logname is usually * meaning all, but you can tar‐
266              get a specific source file if you know the  name  of  its  "Log‐
267              Writer".  Default is *:stderr:30.
268
269       -MenuKey keysym-name
270              This  option  specifies  the key which brings up the popup menu.
271              The currently supported list is: F1, F2, F3, F4, F5, F6, F7, F8,
272              F9,  F10,  F11, F12, Pause, Scroll_Lock, Escape, Insert, Delete,
273              Home, Page_Up, Page_Down). Default is F8.
274
275       -via gateway
276              Automatically create encrypted TCP tunnel to the gateway machine
277              before  connection,  connect  to  the  host  through that tunnel
278              (TigerVNC-specific). By default, this option invokes  SSH  local
279              port forwarding, assuming that SSH client binary can be accessed
280              as /usr/bin/ssh. Note that when using the -via option, the  host
281              machine  name  should  be  specified as known to the gateway ma‐
282              chine, e.g.  "localhost" denotes the gateway,  not  the  machine
283              where   vncviewer   was   launched.   The  environment  variable
284              VNC_VIA_CMD  can  override  the  default   tunnel   command   of
285              /usr/bin/ssh -f -L "$L":"$H":"$R" "$G" sleep 20.    The   tunnel
286              command is executed with the environment variables L, H, R,  and
287              G  taken  the  values of the local port number, the remote host,
288              the port number on the remote host, and the gateway machine  re‐
289              spectively.
290
291       -AlertOnFatalError
292              Display a dialog with any fatal error before exiting. Default is
293              on.
294
295       -ReconnectOnError
296              Display a dialog with any error and  offer  the  possibility  to
297              retry establishing the connection. In case this is off no dialog
298              to re-connect will be offered. Default is on.
299
300

FILES

302       $HOME/.vnc/default.tigervnc
303              Default configuration options. This file  must  have  a  "magic"
304              first line of "TigerVNC Configuration file Version 1.0" (without
305              quotes), followed by  simple  <setting>=<value>  pairs  of  your
306              choosing.  The  available  settings  are those shown in this man
307              page.
308
309       $HOME/.vnc/x509_ca.pem
310              Default CA certificate for authenticating servers.
311
312       $HOME/.vnc/x509_crl.pem
313              Default certificate revocation list.
314
315

SEE ALSO

317       Xvnc(1), vncpasswd(1), vncconfig(1), vncsession(8)
318       https://www.tigervnc.org
319
320

AUTHOR

322       Tristan Richardson, RealVNC Ltd. and others.
323
324       VNC was originally developed by the RealVNC team while at Olivetti  Re‐
325       search  Ltd / AT&T Laboratories Cambridge.  TightVNC additions were im‐
326       plemented by Constantin Kaplinsky. Many other people have since partic‐
327       ipated  in development, testing and support. This manual is part of the
328       TigerVNC software suite.
329
330
331
332TigerVNC                                                          vncviewer(1)
Impressum