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

NAME

6       Xvnc - the X VNC server
7

SYNOPSIS

9       Xvnc [options] :display#
10

DESCRIPTION

12       Xvnc is the X VNC (Virtual Network Computing) server.  It is based on a
13       standard X server, but it has a "virtual" screen rather than a physical
14       one.   X applications display themselves on it as if it were a normal X
15       display, but they  can  only  be  accessed  via  a  VNC  viewer  -  see
16       vncviewer(1).
17
18       So  Xvnc  is  really two servers in one. To the applications it is an X
19       server, and to the remote VNC users it is a VNC server.  By  convention
20       we have arranged that the VNC server display number will be the same as
21       the X server display number, which means you can use  eg.  snoopy:2  to
22       refer  to display 2 on machine "snoopy" in both the X world and the VNC
23       world.
24
25       The best way of starting Xvnc is via vncsession.  This sets up the  en‐
26       vironment  appropriately and starts a desktop environment. See the man‐
27       ual page for vncsession(8) for more information.
28
29

OPTIONS

31       Xvnc takes lots of options - running Xvnc -help gives a list.  Many  of
32       these  are  standard  X  server  options,  which  are  described in the
33       Xserver(1) manual page.  In addition to options which can only  be  set
34       via the command-line, there are also "parameters" which can be set both
35       via the command-line and through the vncconfig(1) program.
36
37
38       -geometry widthxheight
39              Specify the size of  the  desktop  to  be  created.  Default  is
40              1024x768.
41
42       -depth depth
43              Specify  the  pixel  depth in bits of the desktop to be created.
44              Default is 24, other possible values are  16  and  32.  Anything
45              else  is  likely  to cause strange behaviour by applications and
46              may prevent the server from starting at all.
47
48       -pixelformat format
49              Specify pixel format for server to use (BGRnnn or  RGBnnn).  The
50              default  for  depth  16  is  RGB565  and  for depth 24 and 32 is
51              RGB888.
52
53       -interface IP address
54              Listen on interface. By default Xvnc listens  on  all  available
55              interfaces.
56
57       -inetd This  significantly  changes  Xvnc's behaviour so that it can be
58              launched from inetd.  See the section below on usage with inetd.
59
60       -help  List all the options and parameters
61
62

PARAMETERS

64       VNC parameters can be set both via the  command-line  and  through  the
65       vncconfig(1)  program,  and  with a VNC-enabled Xorg server via Options
66       entries in the xorg.conf file.
67
68       Parameters can be turned on with -param or off with -param=0.   Parame‐
69       ters  which take a value can be specified as -param value.  Other valid
70       forms are param=value -param=value --param=value.  Parameter names  are
71       case-insensitive.
72
73
74       -desktop desktop-name
75              Each desktop has a name which may be displayed by the viewer. It
76              defaults to "<user>@<hostname>".
77
78       -rfbport port
79              Specifies the TCP port on which  Xvnc  listens  for  connections
80              from  viewers  (the protocol used in VNC is called RFB - "remote
81              framebuffer").  The default is 5900  plus  the  display  number.
82              Listening on TCP port can be disabled with -fbport=-1.
83
84       -UseIPv4
85              Use IPv4 for incoming and outgoing connections. Default is on.
86
87       -UseIPv6
88              Use IPv6 for incoming and outgoing connections. Default is on.
89
90       -rfbunixpath path
91              Specifies the path of a Unix domain socket on which Xvnc listens
92              for connections from viewers.
93
94       -rfbunixmode mode
95              Specifies the mode of the Unix domain socket.   The  default  is
96              0600.
97
98       -rfbauth passwd-file, -PasswordFile passwd-file
99              Password  file for VNC authentication.  There is no default, you
100              should specify the  password  file  explicitly.   Password  file
101              should  be  created  with the vncpasswd(1) utility.  The file is
102              accessed each time a connection comes in, so it can  be  changed
103              on the fly.
104
105       -AcceptCutText
106              Accept clipboard updates from clients. Default is on.
107
108       -MaxCutText bytes
109              The  maximum  size  of  a clipboard update that will be accepted
110              from a client.  Default is 262144.
111
112       -SendCutText
113              Send clipboard changes to clients. Default is on.
114
115       -SendPrimary
116              Send the primary selection and cut buffer to the server as  well
117              as the clipboard selection. Default is on.
118
119       -AcceptPointerEvents
120              Accept pointer press and release events from clients. Default is
121              on.
122
123       -AcceptKeyEvents
124              Accept key press and release events from clients. Default is on.
125
126       -AcceptSetDesktopSize
127              Accept requests to resize the size of the  desktop.  Default  is
128              on.
129
130       -DisconnectClients
131              Disconnect  existing  clients  if an incoming connection is non-
132              shared. Default is on. If DisconnectClients is false, then a new
133              non-shared  connection  will  be refused while there is a client
134              active.  When combined with  NeverShared  this  means  only  one
135              client is allowed at a time.
136
137       -NeverShared
138              Never  treat  incoming  connections as shared, regardless of the
139              client-specified setting. Default is off.
140
141       -AlwaysShared
142              Always treat incoming connections as shared, regardless  of  the
143              client-specified setting. Default is off.
144
145       -Protocol3.3
146              Always use protocol version 3.3 for backwards compatibility with
147              badly-behaved clients. Default is off.
148
149       -FrameRate fps
150              The maximum number of updates per second sent to each client. If
151              the  screen updates any faster then those changes will be aggre‐
152              gated and sent in a single update to the client. Note that  this
153              only controls the maximum rate and a client may get a lower rate
154              when resources are limited. Default is 60.
155
156       -CompareFB mode
157              Perform pixel comparison on framebuffer  to  reduce  unnecessary
158              updates.  Can be either 0 (off), 1 (always) or 2 (auto). Default
159              is 2.
160
161       -ZlibLevel level
162              Zlib compression level for ZRLE encoding  (it  does  not  affect
163              Tight  encoding).   Acceptable  values are between 0 and 9.  De‐
164              fault is to use the standard compression level provided  by  the
165              zlib(3) compression library.
166
167       -ImprovedHextile
168              Use  improved  compression  algorithm for Hextile encoding which
169              achieves better compression ratios by the cost of using slightly
170              more CPU time.  Default is on.
171
172       -SecurityTypes sec-types
173              Specify  which  security scheme to use for incoming connections.
174              Valid values are a comma separated list of None, VncAuth, Plain,
175              TLSNone,  TLSVnc, TLSPlain, X509None, X509Vnc and X509Plain. De‐
176              fault is VncAuth,TLSVnc.
177
178       -Password password
179              Obfuscated binary encoding of the password  which  clients  must
180              supply  to access the server.  Using this parameter is insecure,
181              use PasswordFile parameter instead.
182
183       -PlainUsers user-list
184              A comma separated list of user names that are allowed to authen‐
185              ticate  via  any of the "Plain" security types (Plain, TLSPlain,
186              etc.). Specify * to allow any user to  authenticate  using  this
187              security type. Default is to deny all users.
188
189       -pam_service name, -PAMService name
190              PAM  service  name to use when authentication users using any of
191              the "Plain" security types. Default is vnc.
192
193       -X509Cert path
194              Path to a X509 certificate in PEM format to be used for all X509
195              based security types (X509None, X509Vnc, etc.).
196
197       -X509Key path
198              Private  key  counter part to the certificate given in X509Cert.
199              Must also be in PEM format.
200
201       -GnuTLSPriority priority
202              GnuTLS priority string that controls the TLS session’s handshake
203              algorithms.   See  the  GnuTLS  manual  for possible values. For
204              GnuTLS < 3.6.3 the default value will be NORMAL to use  upstream
205              default.  For newer versions of GnuTLS system-wide crypto policy
206              will be used.
207
208       -UseBlacklist
209              Temporarily reject connections from  a  host  if  it  repeatedly
210              fails to authenticate. Default is on.
211
212       -BlacklistThreshold count
213              The  number  of unauthenticated connection attempts allowed from
214              any individual host before that host is  black-listed.   Default
215              is 5.
216
217       -BlacklistTimeout seconds
218              The  initial  timeout applied when a host is first black-listed.
219              The host cannot re-attempt a connection until  the  timeout  ex‐
220              pires.  Default is 10.
221
222       -IdleTimeout seconds
223              The number of seconds after which an idle VNC connection will be
224              dropped.  Default is 0, which means that idle  connections  will
225              never be dropped.
226
227       -MaxDisconnectionTime seconds
228              Terminate  when no client has been connected for N seconds.  De‐
229              fault is 0.
230
231       -MaxConnectionTime seconds
232              Terminate when a client has been connected for N  seconds.   De‐
233              fault is 0.
234
235       -MaxIdleTime seconds
236              Terminate after N seconds of user inactivity.  Default is 0.
237
238       -QueryConnect
239              Prompts  the  user of the desktop to explicitly accept or reject
240              incoming connections. Default is off.
241
242              The vncconfig(1) program must be running on the desktop in order
243              for QueryConnect to be supported.
244
245       -QueryConnectTimeout seconds
246              Number  of  seconds  to show the Accept Connection dialog before
247              rejecting the connection.  Default is 10.
248
249       -localhost
250              Only allow connections from the same machine. Useful if you  use
251              SSH and want to stop non-SSH connections from any other hosts.
252
253       -Log logname:dest:level
254              Configures  the  debug  log  settings.   dest  can  currently be
255              stderr, stdout or syslog, and level is between 0  and  100,  100
256              meaning  most verbose output.  logname is usually * meaning all,
257              but you can target a specific source file if you know  the  name
258              of its "LogWriter".  Default is *:stderr:30.
259
260       -RemapKeys mapping
261              Sets up a keyboard mapping.  mapping is a comma-separated string
262              of  character  mappings,  each  of  the  form   char->char,   or
263              char<>char,  where char is a hexadecimal keysym. For example, to
264              exchange the " and @ symbols you would specify the following:
265
266                 RemapKeys=0x22<>0x40
267
268       -AvoidShiftNumLock
269              Key affected by NumLock often require a fake  Shift  to  be  in‐
270              serted  in order for the correct symbol to be generated. Turning
271              on this option avoids these extra fake Shift events but may  re‐
272              sult  in a slightly different symbol (e.g. a Return instead of a
273              keypad Enter).
274
275       -RawKeyboard
276              Send keyboard events straight through and avoid mapping them  to
277              the current keyboard layout. This effectively makes the keyboard
278              behave according to the layout configured on the server  instead
279              of the layout configured on the client. Default is off.
280
281       -AllowOverride
282              Comma  separated  list  of parameters that can be modified using
283              VNC extension.  Parameters can be  modified  for  example  using
284              vncconfig(1) program from inside a running session.
285
286              Allowing  override of parameters such as PAMService or Password‐
287              File can negatively impact security if Xvnc runs under different
288              user than the programs allowed to override the parameters.
289
290              When NoClipboard parameter is set, allowing override of SendCut‐
291              Text and AcceptCutText has no effect.
292
293              Default  is   desktop,AcceptPointerEvents,SendCutText,AcceptCut‐
294              Text,SendPrimary,SetPrimary.
295
296

USAGE WITH INETD

298       By configuring the inetd(1) service appropriately, Xvnc can be launched
299       on demand when a connection comes in, rather than having to be  started
300       manually.   When  given the -inetd option, instead of listening for TCP
301       connections on a given port it uses its  standard  input  and  standard
302       output.  There are two modes controlled by the wait/nowait entry in the
303       inetd.conf file.
304
305       In the nowait mode, Xvnc uses its standard input and output directly as
306       the connection to a viewer.  It never has a listening socket, so cannot
307       accept further connections from viewers (it can however connect out  to
308       listening  viewers  by  use  of the vncconfig program).  Further viewer
309       connections to the same TCP port result in inetd  spawning  off  a  new
310       Xvnc  to  deal with each connection.  When the connection to the viewer
311       dies, the Xvnc and any associated X clients  die.   This  behaviour  is
312       most  useful when combined with the XDMCP options -query and -once.  An
313       typical example in inetd.conf might be (all on one line):
314
315       5950   stream   tcp  nowait  nobody   /usr/local/bin/Xvnc  Xvnc  -inetd
316       -query localhost -once securitytypes=none
317
318       In  this  example  a viewer connection to :50 will result in a new Xvnc
319       for that connection which should display the standard XDM login  screen
320       on  that  machine.  Because the user needs to login via XDM, it is usu‐
321       ally OK to accept connections without a VNC password in this case.
322
323       In the wait mode, when the first connection comes in, inetd  gives  the
324       listening  socket to Xvnc.  This means that for a given TCP port, there
325       is only ever one Xvnc at a time.  Further  viewer  connections  to  the
326       same  port  are accepted by the same Xvnc in the normal way.  Even when
327       the original connection is broken, the Xvnc will continue to  run.   If
328       this  is used with the XDMCP options -query and -once, the Xvnc and as‐
329       sociated X clients will die when the user logs out of the X session  in
330       the normal way.  It is important to use a VNC password in this case.  A
331       typical entry in inetd.conf might be:
332
333       5951   stream   tcp wait   james      /usr/local/bin/Xvnc  Xvnc  -inetd
334       -query localhost -once passwordFile=/home/james/.vnc/passwd
335
336       In  fact typically, you would have one entry for each user who uses VNC
337       regularly, each of whom has their own dedicated  TCP  port  which  they
338       use.  In this example, when user "james" connects to :51, he enters his
339       VNC password, then gets the XDM login screen where he logs  in  in  the
340       normal  way.   However, unlike the previous example, if he disconnects,
341       the session remains persistent, and when he reconnects he will get  the
342       same  session  back again.  When he logs out of the X session, the Xvnc
343       will die, but of course a new one will  be  created  automatically  the
344       next time he connects.
345
346

SEE ALSO

348       vncconfig(1),  vncpasswd(1),  vncviewer(1),  vncsession(8), Xserver(1),
349       inetd(1)
350       https://www.tigervnc.org
351
352

AUTHOR

354       Tristan Richardson, RealVNC Ltd. and others.
355
356       VNC was originally developed by the RealVNC team while at Olivetti  Re‐
357       search  Ltd / AT&T Laboratories Cambridge.  TightVNC additions were im‐
358       plemented by Constantin Kaplinsky. Many other people have since partic‐
359       ipated  in development, testing and support. This manual is part of the
360       TigerVNC software suite.
361
362
363
364TigerVNC                                                               Xvnc(1)
Impressum