1X11VNC(1) User Commands X11VNC(1)
2
6 x11vnc - allow VNC connections to real X11 displays
7 version: 0.9.8, lastmod: 2009-06-14
8
10 x11vnc [OPTION]...
11
13 Typical usage is:
14 Run this command in a shell on the remote machine "far-host"
16 with X session you wish to view:
17 x11vnc -display :0
19 Then run this in another window on the machine you are sitting
21 at:
22 vncviewer far-host:0
24 Once x11vnc establishes connections with the X11 server and starts lis‐
26 tening as a VNC server it will print out a string: PORT=XXXX where XXXX
27 is typically 5900 (the default VNC server port). One would next run
28 something like this on the local machine: "vncviewer hostname:N" where
29 "hostname" is the name of the machine running x11vnc and N is XXXX -
30 5900, i.e. usually "vncviewer hostname:0".
31 By default x11vnc will not allow the screen to be shared and it will
33 exit as soon as the client disconnects. See -shared and -forever below
34 to override these protections. See the FAQ for details how to tunnel
35 the VNC connection through an encrypted channel such as ssh(1). In
36 brief:
37 ssh -t -L 5900:localhost:5900 far-host 'x11vnc -localhost -dis‐
39 play :0'
40 % vncviewer -encodings 'copyrect tight zrle hextile' localhost:0
42 Also, use of a VNC password (-rfbauth or -passwdfile) is strongly rec‐
44 ommended.
45 For additional info see: http://www.karlrunge.com/x11vnc/ and
47 http://www.karlrunge.com/x11vnc/faq.html
48 Config file support: if the file $HOME/.x11vncrc exists then each line
50 in it is treated as a single command line option. Disable with -norc.
51 For each option name, the leading character "-" is not required. E.g.
52 a line that is either "forever" or "-forever" may be used and are
53 equivalent. Likewise "wait 100" or "-wait 100" are acceptable and
54 equivalent lines. The "#" character comments out to the end of the
55 line in the usual way (backslash it for a literal). Leading and trail‐
56 ing whitespace is trimmed off. Lines may be continued with a "\" as
57 the last character of a line (it becomes a space character).
58
60 -display disp
61 X11 server display to connect to, usually :0. The X server
63 process must be running on same machine and support MIT-SHM.
64 Equivalent to setting the DISPLAY environment variable to disp.
65 See the description below of the "-display WAIT:..." exten‐
67 sions, where alias "-find" will find the user's display automat‐
68 ically, and "-create" will create a Xvfb session if no session
69 is found.
70 -auth file
72 Set the X authority file to be file, equivalent to setting the
74 XAUTHORITY environment variable to file before startup. Same as
75 -xauth file. See Xsecurity(7) , xauth(1) man pages for more
76 info.
77 -N
79 If the X display is :N, try to set the VNC display to also be :N
81 This just sets the -rfbport option to 5900+N The program will
82 exit immediately if that port is not available. The -N option
83 only works with normal -display usage, e.g. :0 or :8, -N is
84 ignored in the -display WAIT:..., -create, -find, -svc, -redi‐
85 rect, etc modes.
86 -autoport n
88 Automatically probe for a free VNC port starting at n. The
90 default is to start probing at 5900. Use this to stay away from
91 other VNC servers near 5900.
92 -rfbport str
94 The VNC port to listen on (a libvncserver option), e.g. 5900,
96 5901, etc. If specified as "-rfbport PROMPT" then the x11vnc
97 -gui is used to prompt the user to enter the port number.
98 -reopen
100 If the X server connection is disconnected, try to reopen the X
102 display (up to one time.) This is of use for display managers
103 like GDM (KillInitClients option) that kill x11vnc just after
104 the user logs into the X session. Note: the reopened state may
105 be unstable. Set X11VNC_REOPEN_DISPLAY=n to reopen n times.
106 -reflect host:N
108 Instead of connecting to and polling an X display, connect to
110 the remote VNC server host:N and be a reflector/repeater for it.
111 This is useful for trying to manage the case of many simultane‐
112 ous VNC viewers (e.g. classroom broadcasting) where, e.g. you
113 put a repeater on each network switch, etc, to improve perfor‐
114 mance by distributing the load and network traffic. Implies
115 -shared (use -noshared as a later option to disable). See the
116 discussion below under -rawfb vnc:host:N for more details.
117 -id windowid
119 Show the X window corresponding to windowid not the entire dis‐
121 play. New windows like popup menus, transient toplevels, etc,
122 may not be seen or may be clipped. Disabling SaveUnders or
123 BackingStore in the X server may help show them. x11vnc may
124 crash if the window is initially partially obscured, changes
125 size, is iconified, etc. Some steps are taken to avoid this and
126 the -xrandr mechanism is used to track resizes. Use xwininfo(1)
127 to get the window id, or use "-id pick" to have x11vnc run xwin‐
128 info(1) for you and extract the id. The -id option is useful
129 for exporting very simple applications (e.g. the current view on
130 a webcam).
131 -sid windowid
133 As -id, but instead of using the window directly it shifts a
135 root view to it: this shows SaveUnders menus, etc, although they
136 will be clipped if they extend beyond the window.
137 -clip WxH+X+Y
139 Only show the sub-region of the full display that corresponds to
141 the rectangle geometry with size WxH and offset +X+Y. The VNC
142 display has size WxH (i.e. smaller than the full display). This
143 also works for -id/-sid mode where the offset is relative to the
144 upper left corner of the selected window. An example use of
145 this option would be to split a large (e.g. Xinerama) display
146 into two parts to be accessed via separate viewers by running a
147 separate x11vnc on each part.
148 Use '-clip xinerama0' to clip to the first xinerama sub-screen
150 (if xinerama is active). xinerama1 for the 2nd sub-screen, etc.
151 This way you don't need to figure out the WxH+X+Y of the desired
152 xinerama sub-screen. screens are sorted in increasing distance
153 from the (0,0) origin (I.e. not the Xserver's order).
154 -flashcmap
156 In 8bpp indexed color, let the installed colormap flash as the
158 pointer moves from window to window (slow). Also try the -8to24
159 option to avoid flash altogether.
160 -shiftcmap n
162 Rare problem, but some 8bpp displays use less than 256 color‐
164 cells (e.g. 16-color grayscale, perhaps the other bits are used
165 for double buffering) *and* also need to shift the pixels values
166 away from 0, .., ncells. n indicates the shift to be applied to
167 the pixel values. To see the pixel values set DEBUG_CMAP=1 to
168 print out a colormap histogram. Example: -shiftcmap 240
169 -notruecolor
171 For 8bpp displays, force indexed color (i.e. a colormap) even if
173 it looks like 8bpp TrueColor (rare problem).
174 -advertise_truecolor
176 If the X11 display is indexed color, lie to clients when they
178 first connect by telling them it is truecolor. To workaround
179 RealVNC: inPF has colourMap but not 8bpp Use '-advertise_true‐
180 color reset' to reset client fb too.
181 -visual n
183 This option probably does not do what you think. It simply
185 *forces* the visual used for the framebuffer; this may be a bad
186 thing... (e.g. messes up colors or cause a crash). It is useful
187 for testing and for some workarounds. n may be a decimal num‐
188 ber, or 0x hex. Run xdpyinfo(1) for the values. One may also
189 use "TrueColor", etc. see <X11/X.h> for a list. If the string
190 ends in ":m" then for better or for worse the visual depth is
191 forced to be m. You may want to use -noshm when using this
192 option (so XGetImage may automatically translate the pixel
193 data).
194 -overlay
196 Handle multiple depth visuals on one screen, e.g. 8+24 and 24+8
198 overlay visuals (the 32 bits per pixel are packed with 8 for
199 PseudoColor and 24 for TrueColor).
200 Currently -overlay only works on Solaris via XReadScreen(3X11)
202 and IRIX using XReadDisplay(3). On Solaris there is a problem
203 with image "bleeding" around transient popup menus (but not for
204 the menu itself): a workaround is to disable SaveUnders by pass‐
205 ing the "-su" argument to Xsun (in /etc/dt/config/Xservers).
206 Use -overlay as a workaround for situations like these: Some
208 legacy applications require the default visual to be 8bpp
209 (8+24), or they will use 8bpp PseudoColor even when the default
210 visual is depth 24 TrueColor (24+8). In these cases colors in
211 some windows will be incorrect in x11vnc unless -overlay is
212 used. Another use of -overlay is to enable showing the exact
213 mouse cursor shape (details below).
214 Under -overlay, performance will be somewhat slower due to the
216 extra image transformations required. For optimal performance
217 do not use -overlay, but rather configure the X server so that
218 the default visual is depth 24 TrueColor and try to have all
219 apps use that visual (e.g. some apps have -use24 or -visual
220 options).
221 -overlay_nocursor
223 Sets -overlay, but does not try to draw the exact mouse cursor
225 shape using the overlay mechanism.
226 -8to24 [opts]
228 Try this option if -overlay is not supported on your OS, and you
230 have a legacy 8bpp app that you want to view on a multi-depth
231 display with default depth 24 (and is 32 bpp) OR have a default
232 depth 8 display with depth 24 overlay windows for some apps.
233 This option may not work on all X servers and hardware (tested
234 on XFree86/Xorg mga driver and Xsun). The "opts" string is not
235 required and is described below.
236 This mode enables a hack where x11vnc monitors windows within 3
238 levels from the root window. If it finds any that are 8bpp it
239 extracts the indexed color pixel values using XGetImage() and
240 then applies a transformation using the colormap(s) to create
241 TrueColor RGB values that it in turn inserts into bits 1-24 of
242 the framebuffer. This creates a depth 24 "view" of the display
243 that is then exported via VNC.
244 Conversely, for default depth 8 displays, the depth 24 regions
246 are read by XGetImage() and everything is transformed and
247 inserted into a depth 24 TrueColor framebuffer.
248 Note that even if there are *no* depth 24 visuals or windows
250 (i.e. pure 8bpp), this mode is potentially an improvement over
251 -flashcmap because it avoids the flashing and shows each window
252 in the correct color.
253 This method appear to work, but may still have bugs and it does
255 hog resources. If there are multiple 8bpp windows using differ‐
256 ent colormaps, one may have to iconify all but one for the col‐
257 ors to be correct.
258 There may be painting errors for clipping and switching between
260 windows of depths 8 and 24. Heuristics are applied to try to
261 minimize the painting errors. One can also press 3 Alt_L's in a
262 row to refresh the screen if the error does not repair itself.
263 Also the option -fixscreen 8=3.0 or -fixscreen V=3.0 may be used
264 to periodically refresh the screen at the cost of bandwidth
265 (every 3 sec for this example).
266 The [opts] string can contain the following settings. Multiple
268 settings are separated by commas.
269 For for some X servers with default depth 24 a speedup may be
271 achieved via the option "nogetimage". This enables a scheme
272 were XGetImage() is not used to retrieve the 8bpp data.
273 Instead, it assumes that the 8bpp data is in bits 25-32 of the
274 32bit X pixels. There is no requirement that the X server
275 should put the data there for our poll requests, but some do and
276 so the extra steps to retrieve it can be skipped. Tested with
277 mga driver with XFree86/Xorg. For the default depth 8 case this
278 option is ignored.
279 To adjust how often XGetImage() is used to poll the non-default
281 visual regions for changes, use the option "poll=t" where "t" is
282 a floating point time. (default: 0.05)
283 Setting the option "level2" will limit the search for non-
285 default visual windows to two levels from the root window. Do
286 this on slow machines where you know the window manager only
287 imposes one extra window between the app window and the root
288 window.
289 Also for very slow machines use "cachewin=t" where t is a float‐
291 ing point amount of time to cache XGetWindowAttributes results.
292 E.g. cachewin=5.0. This may lead to the windows being unnoticed
293 for this amount of time when deiconifying, painting errors, etc.
294 While testing on a very old SS20 these options gave tolerable
296 response: -8to24 poll=0.2,cachewin=5.0. For this machine -over‐
297 lay is supported and gives better response.
298 Debugging for this mode can be enabled by setting "dbg=1",
300 "dbg=2", or "dbg=3".
301 -24to32
303 Very rare problem: if the framebuffer (X display or -rawfb) is
305 24bpp instead of the usual 32bpp, then dynamically transform the
306 pixels to 32bpp. This will be slower, but can be used to work
307 around problems where VNC viewers cannot handle 24bpp (e.g.
308 "main: setPF: not 8, 16 or 32 bpp?"). See the FAQ for more
309 info.
310 In the case of -rawfb mode, the pixels are directly modified by
312 inserting a 0 byte to pad them out to 32bpp. For X displays, a
313 kludge is done that is equivalent to "-noshm -visual True‐
314 Color:32". (If better performance is needed for the latter,
315 feel free to ask).
316 -scale fraction
318 Scale the framebuffer by factor fraction. Values less than 1
320 shrink the fb, larger ones expand it. Note: image may not be
321 sharp and response may be slower. If fraction contains a deci‐
322 mal point "." it is taken as a floating point number, alterna‐
323 tively the notation "m/n" may be used to denote fractions
324 exactly, e.g. -scale 2/3
325 To scale asymmetrically in the horizontal and vertical direc‐
327 tions, specify a WxH geometry to stretch to: e.g. '-scale
328 1024x768', or also '-scale 0.9x0.75'
329 Scaling Options: can be added after fraction via ":", to supply
331 multiple ":" options use commas. If you just want a quick,
332 rough scaling without blending, append ":nb" to fraction (e.g.
333 -scale 1/3:nb). No blending is the default for 8bpp indexed
334 color, to force blending for this case use ":fb".
335 To disable -scrollcopyrect and -wirecopyrect under -scale use
337 ":nocr". If you need to to enable them use ":cr" or specify
338 them explicitly on the command line. If a slow link is
339 detected, ":nocr" may be applied automatically. Default: :cr
340 More esoteric options: for compatibility with vncviewers the
342 scaled width is adjusted to be a multiple of 4: to disable this
343 use ":n4". ":in" use interpolation scheme even when shrinking,
344 ":pad" pad scaled width and height to be multiples of scaling
345 denominator (e.g. 3 for 2/3).
346 -geometry WxH
348 Same as -scale WxH
350 -scale_cursor frac
352 By default if -scale is supplied the cursor shape is scaled by
354 the same factor. Depending on your usage, you may want to scale
355 the cursor independently of the screen or not at all. If you
356 specify -scale_cursor the cursor will be scaled by that factor.
357 When using -scale mode to keep the cursor at its "natural" size
358 use "-scale_cursor 1". Most of the ":" scaling options apply
359 here as well.
360 -viewonly
362 All VNC clients can only watch (default off).
364 -shared
366 VNC display is shared, i.e. more than one viewer can connect at
368 the same time (default off).
369 -once
371 Exit after the first successfully connected viewer disconnects,
373 opposite of -forever. This is the Default.
374 -forever
376 Keep listening for more connections rather than exiting as soon
378 as the first client(s) disconnect. Same as -many
379 -loop
381 Create an outer loop restarting the x11vnc process whenever it
383 terminates. -bg and -inetd are ignored in this mode (however
384 see -loopbg below).
385 Useful for continuing even if the X server terminates and
387 restarts (at that moment the process will need permission to
388 reconnect to the new X server of course).
389 Use, e.g., -loop100 to sleep 100 millisecs between restarts,
391 etc. Default is 2000ms (i.e. 2 secs) Use, e.g. -loop300,5 to
392 sleep 300 ms and only loop 5 times.
393 If -loopbg (plus any numbers) is specified instead, the "-bg"
395 option is implied and the mode approximates inetd(8) usage to
396 some degree. In this case when it goes into the background any
397 listening sockets (i.e. ports 5900, 5800) are closed, so the
398 next one in the loop can use them. This mode will only be of
399 use if a VNC client (the only client for that process) is
400 already connected before the process goes into the background,
401 for example, usage of -display WAIT:.., -svc, and -connect can
402 make use of this "poor man's" inetd mode. The default wait time
403 is 500ms in this mode. This usage could use useful: -svc -bg
404 -loopbg
405 -timeout n
407 Exit unless a client connects within the first n seconds after
409 startup.
410 -sleepin n
412 At startup sleep n seconds before proceeding (e.g. to allow
414 redirs and listening clients to start up)
415 If a range is given: '-sleepin min-max', a random value between
417 min and max is slept. E.g. '-sleepin 0-20' and ´-sleepin 10-30'.
418 Floats are allowed too.
419 -inetd
421 Launched by inetd(8): stdio instead of listening socket. Note:
423 if you are not redirecting stderr to a log file (via shell 2> or
424 -o option) you MUST also specify the -q option, otherwise the
425 stderr goes to the viewer which will cause it to abort. Speci‐
426 fying both -inetd and -q and no -o will automatically close the
427 stderr.
428 -tightfilexfer
430 Enable the TightVNC file transfer extension. Note that that when
432 the -viewonly option is supplied all file transfers are dis‐
433 abled. Also clients that log in viewonly cannot transfer files.
434 However, if the remote control mechanism is used to change the
435 global or per-client viewonly state the filetransfer permissions
436 will NOT change.
437 IMPORTANT: please understand if -tightfilexfer is specified and
439 you run x11vnc as root for, say, inetd or display manager (gdm,
440 kdm, ...) access and you do not have it switch users via the
441 -users option, then VNC Viewers that connect are able to do
442 filetransfer reads and writes as *root*.
443 Also, tightfilexfer is disabled in -unixpw mode.
445 -ultrafilexfer
447 Note: to enable UltraVNC filetransfer and to get it to work you
449 probably need to supply these libvncserver options: "-rfbversion
450 3.6 -permitfiletransfer" "-ultrafilexfer" is an alias for this
451 combination.
452 IMPORTANT: please understand if -ultrafilexfer is specified and
454 you run x11vnc as root for, say, inetd or display manager (gdm,
455 kdm, ...) access and you do not have it switch users via the
456 -users option, then VNC Viewers that connect are able to do
457 filetransfer reads and writes as *root*.
458 Note that sadly you cannot do both -tightfilexfer and -ultra‐
460 filexfer at the same time because the latter requires setting
461 the version to 3.6 and tightvnc will not do filetransfer when it
462 sees that version number.
463 -http
465 Instead of using -httpdir (see below) to specify where the Java
467 vncviewer applet is, have x11vnc try to *guess* where the direc‐
468 tory is by looking relative to the program location and in stan‐
469 dard locations (/usr/local/share/x11vnc/classes, etc). Under
470 -ssl or -stunnel the ssl classes subdirectory is sought.
471 -http_ssl
473 As -http, but force lookup for ssl classes subdir.
475 -avahi
477 Use the Avahi/mDNS ZeroConf protocol to advertise this VNC
479 server to the local network. (Related terms: Rendezvous, Bon‐
480 jour). Depending on your setup, you may need to start avahi-
481 daemon and open udp port 5353 in your firewall.
482 If the avahi API cannot be found at build time, a helper program
484 like avahi- publish(1) or dns- sd(1) will be tried
485 -mdns
487 Same as -avahi.
489 -zeroconf
491 Same as -avahi.
493 -connect string
495 For use with "vncviewer -listen" reverse connections. If string
497 has the form "host" or "host:port" the connection is made once
498 at startup.
499 Use commas for a list of host's and host:port's. E.g. -connect
501 host1,host2 or host1:0,host2:5678. Note that to reverse connect
502 to multiple hosts at the same time you will likely need to also
503 supply: -shared
504 Note that unlike most vnc servers, x11vnc will require a pass‐
506 word for reverse as well as for forward connections. (provided
507 password auth has been enabled, -rfbauth, etc) If you do not
508 want to require a password for reverse connections set
509 X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in your environment before
510 starting x11vnc.
511 If string contains "/" it is instead interpreted as a file to
513 periodically check for new hosts. The first line is read and
514 then the file is truncated. Be careful about the location of
515 this file if x11vnc is running as root (e.g. via gdm(1) , etc).
516 Repeater mode: Some services provide an intermediate "vnc
518 repeater": http://www.uvnc.com/addons/repeater.html (and also
519 http://koti.mbnet.fi/jtko/ for linux port) that acts as a proxy
520 / gateway. Modes like these require an initial string to be
521 sent for the reverse connection before the VNC protocol is
522 started. Here are the ways to do this:
523 -connect pre=some_string+host:port -connect
525 pre128=some_string+host:port -connect repeater=ID:1234+host:port
526 -connect repeater=23.45.67.89::5501+host:port
527 SSVNC notation is also supported:
529 -connect repeater://host:port+ID:1234
531 As with normal -connect usage, if the repeater port is not sup‐
533 plied 5500 is assumed.
534 The basic idea is between the special tag, e.g. "pre=" and "+"
536 is the pre-string to be sent. Note that in this case host:port
537 is the repeater server, NOT the vnc viewer. Somehow the pre-
538 string tells the repeater server how to find the vnc viewer and
539 connect you to it.
540 In the case pre=some_string+host:port, "some_string" is simply
542 sent. In the case preNNN=some_string+host:port "some_string" is
543 sent in a null padded buffer of length NNN. repeater= is the
544 same as pre250=, this is the ultravnc repeater buffer size.
545 Strings like "\n" and "\r", etc. are expanded to newline and
547 carriage return. "\c" is expanded to "," since the connect
548 string is comma separated.
549 See also the -proxy option below for additional ways to plumb
551 reverse connections.
552 -connect_or_exit str
554 As with -connect, except if none of the reverse connections suc‐
556 ceed, then x11vnc shuts down immediately
557 By the way, if you do not want x11vnc to listen on ANY interface
559 use -rfbport 0 which is handy for the -connect_or_exit mode.
560 -proxy string
562 Use proxy in string (e.g. host:port) as a proxy for making
564 reverse connections (-connect or -connect_or_exit options).
565 Web proxies are supported, but note by default most of them only
567 support destination connections to ports 443 or 563, so this
568 might not be very useful (the viewer would need to listen on
569 that port or the router would have to do a port redirection).
570 A web proxy may be specified by either "host:port" or
572 "http://host:port" (the port is required even if it is the com‐
573 mon choices 80 or 8080)
574 SOCKS4, SOCKS4a, and SOCKS5 are also supported. SOCKS proxies
576 normally do not have restrictions on the destination port num‐
577 ber.
578 Use a format like this: socks://host:port or socks5://host:port.
580 Note that ssh -D does not support SOCKS4a, so use socks5://.
581 For socks:// SOCKS4 is used on a numerical IP and "localhost",
582 otherwise SOCKS4a is used (and so the proxy tries to do the DNS
583 lookup).
584 An experimental mode is "-proxy http://host:port/..." Note the
586 "/" after the port that distinguishes it from a normal web
587 proxy. The port must be supplied even if it is the default 80.
588 For this mode a GET is done to the supplied URL with the string
589 host=H&port=P appended. H and P will be the -connect reverse
590 connect host and port. Use the string "__END__" to disable the
591 appending. The basic idea here is that maybe some cgi script
592 provides the actual viewer hookup and tunnelling. How to actu‐
593 ally achieve this within cgi, php, etc. is not clear... A cus‐
594 tom web server or apache module would be straight-forward.
595 Another experimental mode is "-proxy ssh://user@host" in which
597 case a SSH tunnel is used for the proxying. "user@" is not
598 needed unless your unix username is different on "host". For a
599 non-standard SSH port use ssh://user@host:port. If proxies are
600 chained (see next paragraph) then the ssh one must be the first
601 one. If ssh-agent is not active, then the ssh password needs to
602 be entered in the terminal where x11vnc is running. Examples:
603 -connect localhost:0 -proxy ssh://me@friends-pc:2222
605 -connect snoopy:0 -proxy ssh://ssh.company.com
607 Multiple proxies may be chained together in case one needs to
609 ricochet off of a number of hosts to finally reach the VNC
610 viewer. Up to 3 may be chained, separate them by commas in the
611 order they are to be connected to. E.g.:
612 http://host1:port1,socks5://host2:port2 or three like:
613 first,second,third
614 -vncconnect, -novncconnect
616 Monitor the VNC_CONNECT X property set by the standard VNC pro‐
618 gram vncconnect(1). When the property is set to "host" or
619 "host:port" establish a reverse connection. Using xprop(1)
620 instead of vncconnect may work (see the FAQ). The -remote con‐
621 trol mechanism uses X11VNC_REMOTE channel, and this option dis‐
622 ables/enables it as well. Default: -vncconnect
623 -allow host1[,host2..]
625 Only allow client connections from hosts matching the comma sep‐
627 arated list of hostnames or IP addresses. Can also be a numeri‐
628 cal IP prefix, e.g. "192.168.100." to match a simple subnet,
629 for more control build libvncserver with libwrap support (See
630 the FAQ). If the list contains a "/" it instead is a inter‐
631 preted as a file containing addresses or prefixes that is re-
632 read each time a new client connects. Lines can be commented
633 out with the "#" character in the usual way.
634 -allow applies in -ssl mode, but not in -stunnel mode.
636 -localhost
638 Basically the same as "-allow 127.0.0.1".
640 Note: if you want to restrict which network interface x11vnc
642 listens on, see the -listen option below. E.g. "-listen local‐
643 host" or "-listen 192.168.3.21". As a special case, the option
644 "-localhost" implies "-listen localhost".
645 A rare case, but for non-localhost -listen usage, if you use the
647 remote control mechanism (-R) to change the -listen interface
648 you may need to manually adjust the -allow list (and vice versa)
649 to avoid situations where no connections (or too many) are
650 allowed.
651 If you do not want x11vnc to listen on ANY interface (evidently
653 you are using -connect or -connect_or_exit, or plan to use
654 remote control: -R connect:host), use -rfbport 0
655 -nolookup
657 Do not use gethostbyname() or gethostbyaddr() to look up host
659 names or IP numbers. Use this if name resolution is incorrectly
660 set up and leads to long pauses as name lookups time out, etc.
661 -input string
663 Fine tuning of allowed user input. If string does not contain a
665 comma "," the tuning applies only to normal clients. Otherwise
666 the part before "," is for normal clients and the part after for
667 view-only clients. "K" is for Keystroke input, "M" for Mouse-
668 motion input, "B" for Button-click input, "C" is for Clipboard
669 input, and "F" is for File transfer (ultravnc only). Their
670 presence in the string enables that type of input. E.g. "-input
671 M" means normal users can only move the mouse and "-input
672 KMBCF,M" lets normal users do anything and enables view-only
673 users to move the mouse. This option is ignored when a global
674 -viewonly is in effect (all input is discarded in that case).
675 -grabkbd
677 When VNC viewers are connected, attempt to the grab the keyboard
679 so a (non-malicious) user sitting at the physical display is not
680 able to enter keystrokes. This method uses XGrabKeyboard(3X11)
681 and so it is not secure and does not rule out the person at the
682 physical display injecting keystrokes by flooding the server
683 with them, grabbing the keyboard himself, etc. Some degree of
684 cooperation from the person at the display is assumed. This is
685 intended for remote help-desk or educational usage modes.
686 -grabptr
688 As -grabkbd, but for the mouse pointer using XGrabPointer(3X11).
690 Unfortunately due to the way the X server works, the mouse can
691 still be moved around by the user at the physical display, but
692 he will not be able to change window focus with it. Also some
693 window managers that call XGrabServer(3X11) for resizes, etc,
694 will act on the local user's input. Again, some degree of coop‐
695 eration from the person at the display is assumed.
696 -grabalways
698 Apply both -grabkbd and -grabptr even when no VNC viewers are
700 connected. If you only want one of them, use the -R remote con‐
701 trol to turn the other back on, e.g. -R nograbptr.
702 -viewpasswd string
704 Supply a 2nd password for view-only logins. The -passwd (full-
706 access) password must also be supplied.
707 -passwdfile filename
709 Specify the libvncserver password via the first line of the file
711 filename (instead of via -passwd on the command line where oth‐
712 ers might see it via ps(1) ).
713 See the descriptions below for how to supply multiple passwords,
715 view-only passwords, to specify external programs for the
716 authentication, and other features.
717 If the filename is prefixed with "rm:" it will be removed after
719 being read. Perhaps this is useful in limiting the readability
720 of the file. In general, the password file should not be read‐
721 able by untrusted users (BTW: neither should the VNC -rfbauth
722 file: it is NOT encrypted, only obscured with a fixed key).
723 If the filename is prefixed with "read:" it will periodically be
725 checked for changes and reread. It is guaranteed to be reread
726 just when a new client connects so that the latest passwords
727 will be used.
728 If filename is prefixed with "cmd:" then the string after the
730 ":" is run as an external command: the output of the command
731 will be interpreted as if it were read from a password file (see
732 below). If the command does not exit with 0, then x11vnc termi‐
733 nates immediately. To specify more than 1000 passwords this way
734 set X11VNC_MAX_PASSWDS before starting x11vnc. The environment
735 variables are set as in -accept.
736 Note that due to the VNC protocol only the first 8 characters of
738 a password are used (DES key).
739 If filename is prefixed with "custom:" then a custom password
741 checker is supplied as an external command following the ":".
742 The command will be run when a client authenticates. If the
743 command exits with 0 the client is accepted, otherwise it is
744 rejected. The environment variables are set as in -accept.
745 The standard input to the custom command will be a decimal digit
747 "len" followed by a newline. "len" specifies the challenge size
748 and is usually 16 (the VNC spec). Then follows len bytes which
749 is the random challenge string that was sent to the client. This
750 is then followed by len more bytes holding the client's response
751 (i.e. the challenge string encrypted via DES with the user pass‐
752 word in the standard situation).
753 The "custom:" scheme can be useful to implement dynamic pass‐
755 words or to implement methods where longer passwords and/or dif‐
756 ferent encryption algorithms are used. The latter will require
757 customizing the VNC client as well. One could create an MD5SUM
758 based scheme for example.
759 File format for -passwdfile:
761 If multiple non-blank lines exist in the file they are all taken
763 as valid passwords. Blank lines are ignored. Password lines
764 may be "commented out" (ignored) if they begin with the charac‐
765 ter "#" or the line contains the string "__SKIP__". Lines may
766 be annotated by use of the "__COMM__" string: from it to the end
767 of the line is ignored. An empty password may be specified via
768 the "__EMPTY__" string on a line by itself (note your viewer
769 might not accept empty passwords).
770 If the string "__BEGIN_VIEWONLY__" appears on a line by itself,
772 the remaining passwords are used for viewonly access. For com‐
773 patibility, as a special case if the file contains only two
774 password lines the 2nd one is automatically taken as the
775 viewonly password. Otherwise the "__BEGIN_VIEWONLY__" token
776 must be used to have viewonly passwords. (tip: make the 3rd and
777 last line be "__BEGIN_VIEWONLY__" to have 2 full-access pass‐
778 words)
779 -unixpw [list]
781 Use Unix username and password authentication. x11vnc uses the
783 su(1) program to verify the user's password. [list] is an
784 optional comma separated list of allowed Unix usernames. If the
785 [list] string begins with the character "!" then the entire list
786 is taken as an exclude list. See below for per-user options
787 that can be applied.
788 A familiar "login:" and "Password:" dialog is presented to the
790 user on a black screen inside the vncviewer. The connection is
791 dropped if the user fails to supply the correct password in 3
792 tries or does not send one before a 25 second timeout. Existing
793 clients are view-only during this period.
794 If the first character received is "Escape" then the unix user‐
796 name will not be displayed after "login:" as it is typed. This
797 could be of use for VNC viewers that automatically type the
798 username and password.
799 Since the detailed behavior of su(1) can vary from OS to OS and
801 for local configurations, test the mode carefully. x11vnc will
802 attempt to be conservative and reject a login if anything abnor‐
803 mal occurs.
804 One case to note: FreeBSD and the other BSD's by default it is
806 impossible for the user running x11vnc to validate his *own*
807 password via su(1) (commenting out the pam_self.so entry in
808 /etc/pam.d/su eliminates this behavior). So the x11vnc login
809 will always *FAIL* for this case (even when the correct password
810 is supplied).
811 A possible workaround for this on *BSD would be to start x11vnc
813 as root with the "-users +nobody" option to immediately switch
814 to user nobody where the su'ing will proceed normally.
815 Another source of potential problems are PAM modules that prompt
817 for extra info, e.g. password aging modules. These logins will
818 fail as well even when the correct password is supplied.
819 **IMPORTANT**: to prevent the Unix password being sent in *clear
821 text* over the network, one of two schemes will be enforced: 1)
822 the -ssl builtin SSL mode, or 2) require both -localhost and
823 -stunnel be enabled.
824 Method 1) ensures the traffic is encrypted between viewer and
826 server. A PEM file will be required, see the discussion under
827 -ssl below (under some circumstances a temporary one can be
828 automatically generated).
829 Method 2) requires the viewer connection to appear to come from
831 the same machine x11vnc is running on (e.g. from a ssh -L port
832 redirection). And that the -stunnel SSL mode be used for
833 encryption over the network.(see the description of -stunnel
834 below).
835 Note: as a convenience, if you ssh(1) in and start x11vnc it
837 will check if the environment variable SSH_CONNECTION is set and
838 appears reasonable. If it does, then the -ssl or -stunnel
839 requirement will be dropped since it is assumed you are using
840 ssh for the encrypted tunnelling. -localhost is still enforced.
841 Use -ssl or -stunnel to force SSL usage even if SSH_CONNECTION
842 is set.
843 To override the above restrictions you can set environment vari‐
845 ables before starting x11vnc:
846 Set UNIXPW_DISABLE_SSL=1 to disable requiring either -ssl or
848 -stunnel. Evidently you will be using a different method to
849 encrypt the data between the vncviewer and x11vnc: perhaps
850 ssh(1) or an IPSEC VPN.
851 Note that use of -localhost with ssh(1) is roughly the same as
853 requiring a Unix user login (since a Unix password or the user's
854 public key authentication is used by sshd on the machine where
855 x11vnc runs and only local connections from that machine are
856 accepted).
857 Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost
859 requirement in Method 2). One should never do this (i.e. allow
860 the Unix passwords to be sniffed on the network).
861 Regarding reverse connections (e.g. -R connect:host and -connect
863 host), when the -localhost constraint is in effect then reverse
864 connections can only be used to connect to the same machine
865 x11vnc is running on (default port 5500). Please use a ssh or
866 stunnel port redirection to the viewer machine to tunnel the
867 reverse connection over an encrypted channel.
868 In -inetd mode the Method 1) will be enforced (not Method 2).
870 With -ssl in effect reverse connections are disabled. If you
871 override this via env. var, be sure to also use encryption from
872 the viewer to inetd. Tip: you can also have your own stunnel
873 spawn x11vnc in -inetd mode (thereby bypassing inetd). See the
874 FAQ for details.
875 The user names in the comma separated [list] can have per-user
877 options after a ":", e.g. "fred:opts" where "opts" is a "+" sep‐
878 arated list of "viewonly", "fullaccess", "input=XXXX", or
879 "deny", e.g. "karl,wally:viewonly,boss:input=M". For "input="
880 it is the K,M,B,C described under -input.
881 If an item in the list is "*" that means those options apply to
883 all users. It also means all users are allowed to log in after
884 supplying a valid password. Use "deny" to explicitly deny some
885 users if you use "*" to set a global option. If [list] begins
886 with the "!" character then "*" is ignored for checking if the
887 user is allowed, but the any value of options associated with it
888 does apply as normal.
889 There are also some utilities for testing password if [list]
891 starts with the "%" character. See the quick_pw() function in
892 the source for details.
893 Use -nounixpw to disable unixpw mode if it was enabled earlier
895 in the cmd line (e.g. -svc mode)
896 -unixpw_nis [list]
898 As -unixpw above, however do not use su(1) but rather use the
900 traditional getpwnam(3) + crypt(3) method to verify passwords.
901 All of the above -unixpw options and constraints apply.
902 This mode requires that the encrypted passwords be readable.
904 Encrypted passwords stored in /etc/shadow will be inaccessible
905 unless x11vnc is run as root.
906 This is called "NIS" mode simply because in most NIS setups user
908 encrypted passwords are accessible (e.g. "ypcat passwd") by an
909 ordinary user and so that user can authenticate ANY user.
910 NIS is not required for this mode to work (only that getpwnam(3)
912 return the encrypted password is required), but it is unlikely
913 it will work for any most modern environments unless x11vnc is
914 run as root to be able to access /etc/shadow (note running as
915 root is often done when running x11vnc from inetd and
916 xdm/gdm/kdm).
917 Looked at another way, if you do not want to use the su(1)
919 method provided by -unixpw, you can run x11vnc as root and use
920 -unixpw_nis. Any users with passwords in /etc/shadow can then
921 be authenticated. You may want to use -users unixpw= to switch
922 the process user after the user logs in.
923 -unixpw_cmd cmd
925 As -unixpw above, however do not use su(1) but rather run the
927 externally supplied command cmd. The first line of its stdin
928 will the username and the second line the received password. If
929 the command exits with status 0 (success) the VNC client will be
930 accepted. It will be rejected for any other return status.
931 Dynamic passwords and non-unix passwords can be implemented this
933 way by providing your own custom helper program. Note that
934 under unixpw mode the remote viewer is given 3 tries to enter
935 the correct password.
936 If a list of allowed users is needed use -unixpw [list] in addi‐
938 tion to this option.
939 -find
941 Find the user's display using FINDDISPLAY. This is an alias for
943 "-display WAIT:cmd=FINDDISPLAY".
944 For this and the next few options see -display WAIT:... below
946 for all of the details.
947 -finddpy
949 Run the FINDDISPLAY program, print out the found display (if
951 any) and exit. Output is like: DISPLAY=:0.0 DIS‐
952 PLAY=:0.0,XPID=12345 or DISPLAY=:0.0,VT=7. XPID is the process
953 ID of the found X server. VT is the Linux virtual terminal of
954 the X server.
955 -listdpy
957 Have the FINDDISPLAY program list all of your displays (i.e. all
959 the X displays on the local machine that you have access rights
960 to).
961 -create
963 First try to find the user's display using FINDDISPLAY, if that
965 doesn't succeed create an X session via the FINDCREATEDISPLAY
966 method. This is an alias for "-display WAIT:cmd=FINDCREATEDIS‐
967 PLAY-Xvfb".
968 SSH NOTE: for both -find and -create you can (should!) add the
970 "-localhost" option to force SSH tunnel access.
971 -xdummy
973 As in -create, except Xdummy instead of Xvfb.
975 -xvnc
977 As in -create, except Xvnc instead of Xvfb.
979 -xvnc_redirect
981 As in -create, except Xvnc.redirect instead of Xvfb.
983 -svc
985 Terminal services mode based on SSL access. Alias for -display
987 WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users unixpw= -ssl SAVE
988 Also "-service".
989 -svc_xdummy
991 As -svc except Xdummy instead of Xvfb.
993 -svc_xvnc
995 As -svc except Xvnc instead of Xvfb.
997 -xdmsvc
999 Display manager Terminal services mode based on SSL. Alias for
1001 -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -unixpw -users
1002 unixpw= -ssl SAVE Also "-xdm_service".
1003 To create a session a user will have to first log in to the
1005 -unixpw dialog and then log in again to the XDM/GDM/KDM prompt.
1006 Subsequent re-connections will only require the -unixpw pass‐
1007 word. See the discussion under -display WAIT:... for more
1008 details about XDM, etc configuration.
1009 -sshxdmsvc
1011 Display manager Terminal services mode based on SSH. Alias for
1013 -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -localhost.
1014 The -localhost option constrains connections to come in via a
1016 SSH tunnel (which will require a login). To create a session a
1017 user will also have to log into the XDM GDM KDM prompt. Subse‐
1018 quent re-connections will only only require the SSH login. See
1019 the discussion under -display WAIT:... for more details about
1020 XDM, etc configuration.
1021 -redirect port
1023 As in FINDCREATEDISPLAY-Xvnc.redirect mode except redirect imme‐
1025 diately (i.e. without X session finding or creation) to a VNC
1026 server listening on port. You can also supply host:port to redi‐
1027 rect to a different machine.
1028 If 0 <= port < 200 it is taken as a VNC display (5900 is added
1030 to get the actual port), if port < 0 then -port is used.
1031 Probably the only reason to use the -redirect option is in con‐
1033 junction with SSL support, e.g. -ssl SAVE. This provides an
1034 easy way to add SSL encryption to a VNC server that does not
1035 support SSL (e.g. Xvnc or vnc.so) In fact, the protocol does not
1036 even need to be VNC, and so "-rfbport port1 -ssl SAVE -redirect
1037 host:port2" can act as a replacement for stunnel(1).
1038 This mode only allows one redirected connection. The -forever
1040 option does not apply. Use -inetd or -loop for persistant ser‐
1041 vice.
1042 -display WAIT:...
1044 A special usage mode for the normal -display option. Useful
1046 with -unixpw, but can be used independently of it. If the dis‐
1047 play string begins with WAIT: then x11vnc waits until a VNC
1048 client connects before opening the X display (or -rawfb device).
1049 This could be useful for delaying opening the display for cer‐
1051 tain usage modes (say if x11vnc is started at boot time and no X
1052 server is running or users logged in yet).
1053 If the string is, e.g. WAIT:0.0 or WAIT:1, i.e. "WAIT" in front
1055 of a normal X display, then that indicated display is used.
1056 One can also insert a geometry between colons, e.g.
1058 WAIT:1280x1024:... to set the size of the display the VNC client
1059 first attaches to since some VNC viewers will not automatically
1060 adjust to a new framebuffer size.
1061 A more interesting case is like this:
1063 WAIT:cmd=/usr/local/bin/find_display
1065 in which case the command after "cmd=" is run to dynamically
1067 work out the DISPLAY and optionally the XAUTHORITY data. The
1068 first line of the command output must be of the form DIS‐
1069 PLAY=<xdisplay>. On Linux if the virtual terminal is known
1070 append ",VT=n" to this string and the chvt(1) program will also
1071 be run. Any remaining output is taken as XAUTHORITY data. It
1072 can be either of the form XAUTHORITY=<file> or raw xauthority
1073 data for the display. For example;
1074 xauth extract - $DISPLAY"
1076 In the case of -unixpw (but not -unixpw_nis), then the cmd= com‐
1078 mand is run as the user who just authenticated via the login and
1079 password prompt.
1080 Also in the case of -unixpw, the user logging in can place a
1082 colon at the end of her username and supply a few options:
1083 scale=, scale_cursor= (or sc=), solid (or so), id=, clear_mods
1084 (or cm), clear_keys (or ck), repeat, speeds= (or sp=), readtime‐
1085 out= (or rd=), rotate= (or ro=), or noncache (or nc), all sepa‐
1086 rated by commas if there is more than one. After the user logs
1087 in successfully, these options will be applied to the VNC
1088 screen. For example,
1089 login: fred:scale=3/4,sc=1,repeat Password: ...
1091 login: runge:sp=modem,rd=120,solid
1093 for convenience m/n implies scale= e.g. fred:3/4 If you type
1095 and enter your password incorrectly, to retrieve your long
1096 "login:" line press the Up arrow once (before typing anything
1097 else).
1098 Another option is "geom=WxH" or "geom=WxHxD" (or ge=). This only
1100 has an effect in FINDCREATEDISPLAY mode when a virtual X server
1101 such as Xvfb is going to be created. It sets the width and
1102 height of the new display, and optionally the color depth as
1103 well. You can also supply "gnome", "kde", "twm", "fvwm", "mwm",
1104 "dtwm", "wmaker", "xfce", "enlightenment", "Xsession", or "fail‐
1105 safe" (same as "xterm") to have the created display use that
1106 mode for the user session.
1107 To disable the option setting set the environment variable
1109 X11VNC_NO_UNIXPW_OPTS=1 before starting x11vnc. To set any
1110 other options, the user can use the gui (x11vnc -gui connect) or
1111 the remote control method (x11vnc -R opt:val) during his VNC
1112 session.
1113 The combination of -display WAIT:cmd=... and -unixpw allows
1115 automatic pairing of an unix authenticated VNC user with his
1116 desktop. This could be very useful on SunRays and also any sys‐
1117 tem where multiple users share a given machine. The user does
1118 not need to remember special ports or passwords set up for his
1119 desktop and VNC.
1120 A nice way to use WAIT:cmd=... is out of inetd(8) (it automati‐
1122 cally forks a new x11vnc for each user). You can have the
1123 x11vnc inetd spawned process run as, say, root or nobody. When
1124 run as root (for either inetd or display manager), you can also
1125 supply the option "-users unixpw=" to have the x11vnc process
1126 switch to the user as well. Note: there will be a 2nd SSL
1127 helper process that will not switch, but it is only encoding and
1128 decoding the encrypted stream at that point.
1129 Automatic Finding of User X Sessions:
1131 As a special case, WAIT:cmd=FINDDISPLAY will run a script that
1133 works on most Unixes to determine a user's DISPLAY variable and
1134 xauthority data (see who(1) ).
1135 The option "-find" is an alias for this mode.
1137 To have this default script printed to stdout (e.g. for cus‐
1139 tomization) run with WAIT:cmd=FINDDISPLAY-print To have the
1140 script run to print what display it would find use "-finddpy" or
1141 WAIT:cmd=FINDDISPLAY-run
1142 The standard script runs xdpyinfo(1) run on potential displays.
1144 If your X server(s) have a login greeter that exclusively grabs
1145 the Xserver, then xdpyinfo blocks forever and this mode will not
1146 work. See www.karlrunge.com/x11vnc/faq.html#faq-display-manager
1147 for how to disable this for dtgreet on Solaris and possibly for
1148 other greeters.
1149 As another special case, WAIT:cmd=HTTPONCE will allow x11vnc to
1151 service one http request and then exit. This is usually done in
1152 -inetd mode to run on, say, port 5800 and allow the Java
1153 vncviewer to be downloaded by client web browsers. For example:
1154 5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc \ -inetd
1156 -q -http_ssl -prog /.../x11vnc \ -display WAIT:cmd=HTTPONCE
1157 Where /.../x11vnc is the full path to x11vnc. It is used in the
1159 Apache SSL-portal example (see FAQ).
1160 In this mode you can set X11VNC_SKIP_DISPLAY to a comma sepa‐
1162 rated list of displays (e.g. ":0,:1") to ignore in the finding
1163 process. The ":" is optional. Ranges n-m e.g. 0-20 can also be
1164 supplied. This string can also be set by the connecting user via
1165 "nd=" using "+" instead of ","
1166 Automatic Creation of User X Sessions:
1168 An interesting option is WAIT:cmd=FINDCREATEDISPLAY that is like
1170 FINDDISPLAY in that is uses the same method to find an existing
1171 display. However, if it does not find one it will try to
1172 *start* up an X server session for the user. This is the only
1173 time x11vnc tries to actually start up an X server.
1174 The option "-create" is an alias for this mode.
1176 It will start looking for an open display number at :20 Override
1178 via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n
1179 By default FINDCREATEDISPLAY will try Xdummy and then Xvfb:
1181 The Xdummy wrapper is part of the x11vnc source code
1183 (x11vnc/misc/Xdummy) It should be available in PATH and have
1184 run "Xdummy -install" once to create the shared library. Xdummy
1185 requires root permission and only works on Linux. (Note: spec‐
1186 ify FD_XDUMMY_NOROOT=1 to skip a check for the root id; evi‐
1187 dently your sudo(1) will take care of everything. The -xdummy
1188 and -svc_xdummy options imply FD_XDUMMY_NOROOT=1).
1189 Xvfb is available on most platforms and does not require root.
1191 When x11vnc exits (i.e. user disconnects) the X server session
1193 stays running in the background. The FINDDISPLAY will find it
1194 directly next time. The user must exit the X session in the
1195 usual way for it to terminate (or kill the X server process if
1196 all else fails).
1197 So this is a somewhat odd mode for x11vnc in that it will start
1199 up and poll virtual X servers! This can be used from, say,
1200 inetd(8) to provide a means of definitely getting a desktop
1201 (either real or virtual) on the machine. E.g. a desktop ser‐
1202 vice:
1203 5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc -inetd -q
1205 -http -ssl SAVE -unixpw -users unixpw=\ -passwd secret -prog
1206 /.../x11vnc \ -display WAIT:cmd=FINDCREATEDISPLAY
1207 Where /.../x11vnc is the full path to x11vnc.
1209 See the -svc/-service option alias above.
1211 If for some reason you do not want x11vnc to ever try to find an
1213 existing display set the env. var X11VNC_FINDDIS‐
1214 PLAY_ALWAYS_FAILS=1 (also -env ...)
1215 Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the script
1217 that is used for this.
1218 You can specify the preferred X server order via e.g.,
1220 WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb,X and/or leave out ones
1221 you do not want. The the case "X" means try to start up a real,
1222 hardware X server using xinit(1) or startx(1). If there is
1223 already an X server running the X case may only work on Linux
1224 (see startx(1) ).
1225 "Xvnc" will start up a VNC X server (real- or tight-vnc, e.g.
1227 use if Xvfb is not available). "Xsrv" will start up the server
1228 program in the variable "FD_XSRV" if it is non-empty. You can
1229 make this be a wrapper script if you like (it must handle :N,
1230 -geometry, and -depth and other X server options).
1231 You can set the environment variable FD_GEOM (or X11VNC_CRE‐
1233 ATE_GEOM) to WxH or WxHxD to set the width and height and
1234 optionally the color depth of the created display. You can also
1235 set FD_SESS to be the session (short name of the windowmanager:
1236 kde, gnome, twm, failsafe, etc.). FD_OPTS contains extra options
1237 to pass to the X server. You can also set FD_PROG to be the full
1238 path to the session/windowmanager program.
1239 More FD tricks: FD_CUPS=port or FD_CUPS=host:port will set the
1241 cups printing environment. Similarly for FD_ESD=port or
1242 FD_ESD=host:port for esddsp sound redirection. FD_XDUMMY_NOROOT
1243 means the Xdummy server does not need to be started as root
1244 (e.g. it will sudo automatically). Set FD_EXTRA to a command to
1245 be run a few seconds after the X server starts up.
1246 If you want the FINDCREATEDISPLAY session to contact an XDMCP
1248 login manager (xdm/gdm/kdm) on the same machine, then use
1249 "Xvfb.xdmcp" instead of "Xvfb", etc. The user will have to sup‐
1250 ply his username and password one more time (but he gets to
1251 select his desktop type so that can be useful). For this to
1252 work, you will need to enable localhost XDMCP (udp port 177) for
1253 the display manager. This seems to be:
1254 for gdm in gdm.conf: Enable=true in section [xdmcp] for kdm in
1256 kdmrc: Enable=true in section [Xdmcp] for xdm in xdm-con‐
1257 fig: DisplayManager.requestPort: 177
1258 See the shorthand options above "-svc", "-xdmsvc" and
1260 "-sshxdmsvc" that specify the above options for some useful
1261 cases.
1262 If you set the env. var WAITBG=1 x11vnc will go into the back‐
1264 ground once listening in wait mode.
1265 Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, (or
1267 FINDDISPLAY-Xvnc.redirect). In this case it will start up Xvnc
1268 as above if needed, but instead of polling it in its normal way,
1269 it simply does a socket redirection of the connected VNC viewer
1270 to the Xvnc.
1271 So in Xvnc.redirect x11vnc does no VNC but merely transfers the
1273 data back and forth. This should be faster then x11vnc's
1274 polling method, but not as fast as connecting directly to the
1275 Xvnc with the VNC Viewer. The idea here is to take advantage of
1276 x11vnc's display finding/creating scheme, SSL, and perhaps a few
1277 others. Most of x11vnc's options do not apply in this mode.
1278 Xvnc.redirect should also work for the vnc.so X server module
1280 for the h/w display however it will work only for finding the
1281 display and the user must already be logged into the X console.
1282 -vencrypt mode
1284 The VeNCrypt extension to the VNC protocol allows encrypted
1286 SSL/TLS connections. If the -ssl mode is enabled, then VeNCrypt
1287 is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel,
1288 only the protocol handshake is a little different.)
1289 To control when and how VeNCrypt is used, specify the mode
1291 string. If mode is "never", then VeNCrypt is not used. If mode
1292 is "support" (the default) then VeNCrypt is supported. If mode
1293 is "only", then the similar and older ANONTLS protocol is not
1294 simultaneously supported. x11vnc's normal SSL mode (vncs://)
1295 will be supported under -ssl unless you set mode to "force".
1296 If mode is prefixed with "nodh:", then Diffie Hellman anonymous
1298 key exchange is disabled. If mode is prefixed with "nox509:",
1299 then X509 key exchange is disabled.
1300 To disable all Anonymous Diffie-Hellman access (susceptible to
1302 Man-In-The-Middle attack) you will need to supply "-vencrypt
1303 nodh:support -anontls never" or "-vencrypt nodh:only"
1304 If mode is prefixed with "newdh:", then new Diffie Hellman
1306 parameters are generated for each connection (this can be time
1307 consuming: 1-60 secs; see -dhparams below for a faster way)
1308 rather than using the fixed values in the program. Using fixed,
1309 publicly known values is not known to be a security problem.
1310 This setting applies to ANONTLS as well.
1311 Long example: -vencrypt newdh:nox509:support
1313 Also, if mode is prefixed with "plain:", then if -unixpw mode is
1315 active the VeNCrypt "*Plain" username+passwd method is enabled
1316 for Unix logins. Otherwise in -unixpw mode the normal login
1317 panel is provided.
1318 You *MUST* supply the -ssl option for VeNCrypt to be active.
1320 This option only fine-tunes its operation.
1321 -anontls mode
1323 The ANONTLS extension to the VNC protocol allows encrypted
1325 SSL/TLS connections. If the -ssl mode is enabled, then ANONTLS
1326 is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel,
1327 only the protocol handshake is a little different.)
1328 ANONTLS is an older SSL/TLS mode introduced by vino.
1330 It is referred to as 'TLS' for its registered VNC security-type
1332 name, but we use the more descriptive ´ANONTLS' here because it
1333 provides only Anonymous Diffie-Hellman encrypted connections,
1334 and hence no possibility for certificate authentication.
1335 To control when and how ANONTLS is used, specify the mode
1337 string. If mode is "never", then ANONTLS is not used. If mode
1338 is "support" (the default) then ANONTLS is supported. If mode
1339 is "only", then the similar VeNCrypt protocol is not simultane‐
1340 ously supported. x11vnc's normal SSL mode (vncs://) will be
1341 supported under -ssl unless you set mode to "force".
1342 If mode is prefixed with "newdh:", then new Diffie Hellman
1344 parameters are generated for each connection (this can be time
1345 consuming: 1-60 secs; see -dhparams below for a faster way)
1346 rather than using the fixed values in the program. Using fixed,
1347 publicly known values is not known to be a security problem.
1348 This setting applies to VeNCrypt as well. See the description
1349 of "plain:" under -vencrypt.
1350 Long example: -anontls newdh:plain:support
1352 You *MUST* supply the -ssl option for ANONTLS to be active.
1354 This option only fine-tunes its operation.
1355 -sslonly
1357 Same as: "-vencrypt never -anontls never" i.e. it disables the
1359 VeNCrypt and ANONTLS encryption methods and only allows standard
1360 SSL tunneling. You must also supply the -ssl ... option (see
1361 below.)
1362 -dhparams file
1364 For some operations a set of Diffie Hellman parameters (prime
1366 and generator) is needed. If so, use the parameters in file. In
1367 particular, the VeNCrypt and ANONTLS anonymous DH mode need
1368 them. By default a fixed set is used. If you do not want to do
1369 that you can specify "newdh:" to the -vencrypt and -anontls
1370 options to generate a new set each session. If that is too slow
1371 for you, use -dhparams file to a set you created manually via
1372 "openssl dhparam -out file 1024"
1373 -nossl
1375 Disable the -ssl option (see below). Since -ssl is off by
1377 default -nossl would only be used on the commandline to unset
1378 any *earlier* -ssl option (or -svc...)
1379 -ssl [pem]
1381 Use the openssl library (www.openssl.org) to provide a built-in
1383 encrypted SSL/TLS tunnel between VNC viewers and x11vnc. This
1384 requires libssl support to be compiled into x11vnc at build
1385 time. If x11vnc is not built with libssl support it will exit
1386 immediately when -ssl is prescribed.
1387 The VNC Viewer-side needs to support SSL/TLS as well. See this
1389 URL and also the discussion below for ideas on how to enable SSL
1390 support for the viewer: http://www.karl‐
1391 runge.com/x11vnc/faq.html#faq-ssl-tun nel-viewers x11vnc pro‐
1392 vides an SSL enabled Java viewer applet in the classes/ssl
1393 directory (-http or -httpdir options.) The SSVNC viewer package
1394 supports SSL tunnels too.
1395 If the VNC Viewer supports VeNCrypt or ANONTLS (vino's encryp‐
1397 tion mode) they are also supported by the -ssl mode (see the
1398 -vencrypt and -anontls options for more info; use -sslonly to
1399 disable both of them.)
1400 Use "-ssl /path/to/mycert.pem" to specify an SSL certificate
1402 file in PEM format to use to identify and provide a key for this
1403 server. See openssl(1) for more info about PEMs and the
1404 -sslGenCert and "-ssl SAVE" options below for how to create
1405 them.
1406 The connecting VNC viewer SSL tunnel can (at its option) authen‐
1408 ticate this server if it has the public key part of the certifi‐
1409 cate (or a common certificate authority, CA, is a more sophisti‐
1410 cated way to verify this server's cert, see -sslGenCA below).
1411 This authentication is done to prevent Man-In-The-Middle
1412 attacks. Otherwise, if the VNC viewer simply accepts this
1413 server's key WITHOUT verification, the traffic is protected from
1414 passive sniffing on the network, but *NOT* from Man-In-The-Mid‐
1415 dle attacks. There are hacker tools like dsniff/webmitm and cain
1416 that implement SSL Man-In-The-Middle attacks.
1417 If [pem] is empty or the string "SAVE" then the openssl(1) com‐
1419 mand must be available to generate the certificate the first
1420 time. A self-signed certificate is generated (see -sslGenCA and
1421 -sslGenCert for use of a Certificate Authority.) It will be
1422 saved to the file ~/.vnc/certs/server.pem. On subsequent calls
1423 if that file already exists it will be used directly.
1424 Use "SAVE_NOPROMPT" to avoid being prompted to protect the gen‐
1426 erated key with a passphrase. However in -inetd and -bg modes
1427 there will be no prompting for a passphrase in either case.
1428 If [pem] is "SAVE_PROMPT" the server.pem certificate will be
1430 created based on your answers to its prompts for all info such
1431 as OrganizationalName, CommonName, etc.
1432 Use "SAVE-<string>" and "SAVE_PROMPT-<string>" to refer to the
1434 file ~/.vnc/certs/server-<string>.pem instead (it will be gener‐
1435 ated if it does not already exist). E.g. "SAVE-charlie" will
1436 store to the file ~/.vnc/certs/server-charlie.pem
1437 Examples: x11vnc -ssl SAVE -display :0 ... x11vnc -ssl SAVE-
1439 someother -display :0 ...
1440 If [pem] is "TMP" and the openssl(1) utility command exists in
1442 PATH, then a temporary, self-signed certificate will be gener‐
1443 ated for this session. If openssl(1) cannot be used to generate
1444 a temporary certificate x11vnc exits immediately. The temporary
1445 cert will be discarded when x11vnc exits.
1446 If successful in using openssl(1) to generate a temporary cer‐
1448 tificate in "SAVE" or "TMP" creation modes, the public part of
1449 it will be displayed to stderr (e.g. one could copy it to the
1450 client-side to provide authentication of the server to VNC view‐
1451 ers.)
1452 NOTE: In "TMP" mode, unless you safely copy the public part of
1454 the temporary Cert to the viewer for authenticate *every time*
1455 (unlikely...), then only passive sniffing attacks are prevented
1456 and you are still open to Man-In-The-Middle attacks. This is
1457 why the default "SAVE" mode is preferred (and more sophisticated
1458 CA mode too). Only with saved keys AND the VNC viewer authenti‐
1459 cating them (via the public certificate), are Man-In-The-Middle
1460 attacks prevented.
1461 If [pem] is "ANON" then the Diffie-Hellman anonymous key
1463 exchange method is used. In this mode there are *no* SSL cer‐
1464 tificates and so it is not possible to authenticate either the
1465 VNC server or VNC client. Thus only passive network sniffing
1466 attacks are avoided: the "ANON" method is susceptible to Man-In-
1467 The-Middle attacks. "ANON" is not recommended; instead use a
1468 SSL PEM you created or the defaut "SAVE" method.
1469 See -ssldir below to use a directory besides the default
1471 ~/.vnc/certs
1472 Misc Info: In temporary cert creation mode "TMP", set the env.
1474 var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc print out the entire
1475 certificate, including the PRIVATE KEY part, to stderr. There
1476 are better ways to get/save this info. See "SAVE" above and
1477 "-sslGenCert" below.
1478 -ssltimeout n
1480 Set SSL read timeout to n seconds. In some situations (i.e. an
1482 iconified viewer in Windows) the viewer stops talking and the
1483 connection is dropped after the default timeout (25s for about
1484 the first minute, 43200s later). Set to zero to poll forever.
1485 Set to a negative value to use the builtin setting.
1486 Note that this value does not apply to the *initial* ssl init
1488 connection. The default timeout for that is 20sec. Use -env
1489 SSL_INIT_TIMEOUT=n to modify it.
1490 -sslnofail
1492 Exit at the first SSL connection failure. Useful when scripting
1494 SSL connections (e.g. x11vnc is started via ssh) and you do not
1495 want x11vnc waiting around for more connections, tying up ports,
1496 etc.
1497 -ssldir [dir]
1499 Use [dir] as an alternate ssl certificate and key management
1501 toplevel directory. The default is ~/.vnc/certs
1502 This directory is used to store server and other certificates
1504 and keys and also other materials. E.g. in the simplest case,
1505 "-ssl SAVE" will store the x11vnc server cert in
1506 [dir]/server.pem
1507 Use of alternate directories via -ssldir allows you to manage
1509 multiple VNC Certificate Authority (CA) keys. Another use is if
1510 ~/.vnc/cert is on an NFS share you might want your certificates
1511 and keys to be on a local filesystem to prevent network snooping
1512 (for example -ssldir /var/lib/x11vnc-certs).
1513 -ssldir affects nearly all of the other -ssl* options, e.g. -ssl
1515 SAVE, -sslGenCert, etc..
1516 -sslverify [path]
1518 For either of the -ssl or -stunnel modes, use [path] to provide
1520 certificates to authenticate incoming VNC *Client* connections
1521 (normally only the server is authenticated in SSL.) This can be
1522 used as a method to replace standard password authentication of
1523 clients.
1524 If [path] is a directory it contains the client (or CA) certifi‐
1526 cates in separate files. If [path] is a file, it contains one
1527 or more certificates. See special tokens below. These corre‐
1528 spond to the "CApath = dir" and "CAfile = file" stunnel options.
1529 See the stunnel(8) manpage for details.
1530 Examples: x11vnc -ssl -sslverify ~/my.crt x11vnc -ssl -sslverify
1532 ~/my_pem_dir/
1533 Note that if [path] is a directory, it must contain the certs in
1535 separate files named like <HASH>.0, where the value of <HASH> is
1536 found by running the command "openssl x509 -hash -noout -in
1537 file.crt". Evidently one uses <HASH>.1 if there is a colli‐
1538 sion...
1539 The the key-management utility "-sslCertInfo HASHON" and
1541 "-sslCertInfo HASHOFF" will create/delete these hashes for you
1542 automatically (via symlink) in the HASH subdirs it manages.
1543 Then you can point -sslverify to the HASH subdir.
1544 Special tokens: in -ssl mode, if [path] is not a file or a
1546 directory, it is taken as a comma separated list of tokens that
1547 are interpreted as follows:
1548 If a token is "CA" that means load the CA/cacert.pem file from
1550 the ssl directory. If a token is "clients" then all the files
1551 clients/*.crt in the ssl directory are loaded. Otherwise the
1552 file clients/token.crt is attempted to be loaded. As a kludge,
1553 use a token like ../server-foo to load a server cert if you find
1554 that necessary.
1555 Use -ssldir to use a directory different from the ~/.vnc/certs
1557 default.
1558 Note that if the "CA" cert is loaded you do not need to load any
1560 of the certs that have been signed by it. You will need to load
1561 any additional self-signed certs however.
1562 Examples: x11vnc -ssl -sslverify CA x11vnc -ssl -sslverify
1564 self:fred,self:jim x11vnc -ssl -sslverify CA,clients
1565 Usually "-sslverify CA" is the most effective. See the
1567 -sslGenCA and -sslGenCert options below for how to set up and
1568 manage the CA framework.
1569 NOTE: the following utilities, -sslGenCA, -sslGenCert,
1571 -sslEncKey, and -sslCertInfo are provided for completeness, but
1572 for casual usage they are overkill.
1573 They provide VNC Certificate Authority (CA) key creation and
1575 server / client key generation and signing. So they provide a
1576 basic Public Key management framework for VNC-ing with x11vnc.
1577 (note that they require openssl(1) be installed on the system)
1578 However, the simplest usage mode, "-ssl TMP" (where x11vnc auto‐
1580 matically generates its own, self-signed, temporary key and the
1581 VNC viewers always accept it, e.g. accepting via a dialog box)
1582 is probably safe enough for most scenarios. CA management is
1583 not needed.
1584 To protect against Man-In-The-Middle attacks the "TMP" mode can
1586 be improved by using "-ssl SAVE" (same as "-ssl", i.e. the
1587 default) to have x11vnc create a longer term self-signed cer‐
1588 tificate, and then (safely) copy the corresponding public key
1589 cert to the desired client machines (care must be taken the pri‐
1590 vate key part is not stolen; you will be prompted for a
1591 passphrase).
1592 So keep in mind no CA key creation or management (-sslGenCA and
1594 -sslGenCert) is needed for either of the above two common usage
1595 modes.
1596 One might want to use -sslGenCA and -sslGenCert if you had a
1598 large number of VNC client and server workstations. That way
1599 the administrator could generate a single CA key with -sslGenCA
1600 and distribute its certificate part to all of the workstations.
1601 Next, he could create signed VNC server keys (-sslGenCert server
1603 ...) for each workstation or user that then x11vnc would use to
1604 authenticate itself to any VNC client that has the CA cert.
1605 Optionally, the admin could also make it so the VNC clients
1607 themselves are authenticated to x11vnc (-sslGenCert client ...)
1608 For this -sslverify would be pointed to the CA cert (and/or
1609 self-signed certs).
1610 x11vnc will be able to use all of these cert and key files. On
1612 the VNC client side, they will need to be "imported" somehow.
1613 Web browsers have "Manage Certificates" actions as does the Java
1614 applet plugin Control Panel. stunnel can also use these files
1615 (see the ss_vncviewer example script in the FAQ and SSVNC.)
1616 -sslCRL path
1618 Set the Certificate Revocation Lists (CRL) to path.
1620 If path is a file, the file contains one more more CRLs in PEM
1622 format. If path is a directory, it contains hash named files of
1623 CRLs in the usual OpenSSL manner. See the OpenSSL and stun‐
1624 nel(8) documentation for more info.
1625 This option only applies if -sslverify has been supplied: it
1627 checks for revocation along the certificate chain used to verify
1628 the VNC client. The -sslCRL setting will be ignored when
1629 -sslverify is not specified.
1630 Only rarely will one's x11vnc -ssl infrastructure be so large
1632 that this option would be useful (since normally maintaining the
1633 contents of the -sslverify file or directory should be enough.)
1634 However, when using x11vnc with a Certificate Authority (see
1635 -sslGenCA) to authenticate Clients via SSL/TLS, the -sslCRL
1636 option can be useful to revoke users' certs whose private SSL
1637 keys were lost or stolen (e.g. laptop.) This way a new CA
1638 cert+key does not need to be created and new signed client keys
1639 generated and distributed to all users.
1640 To create a CRL file with revoked certificates the commands
1642 'openssl ca -revoke ...' and 'openssl ca -gencrl ...' are use‐
1643 ful. (Run them in ~/.vnc/certs)
1644 -sslGenCA [dir]
1646 Generate your own Certificate Authority private key, certifi‐
1648 cate, and other files in directory [dir].
1649 If [dir] is not supplied, a -ssldir setting is used, or other‐
1651 wise ~/.vnc/certs is used.
1652 This command also creates directories where server and client
1654 certs and keys will be stored. The openssl(1) program must be
1655 installed on the system and available in PATH.
1656 After the CA files and directories are created the command
1658 exits; the VNC server is not run.
1659 You will be prompted for information to put into the CA certifi‐
1661 cate. The info does not have to be accurate just as long as
1662 clients accept the cert for VNC connections. You will also need
1663 to supply a passphrase of at least 4 characters for the CA pri‐
1664 vate key.
1665 Once you have generated the CA you can distribute its certifi‐
1667 cate part, [dir]/CA/cacert.pem, to other workstations where VNC
1668 viewers will be run. One will need to "import" this certificate
1669 in the applications, e.g. Web browser, Java applet plugin, stun‐
1670 nel, etc. Next, you can create and sign keys using the CA with
1671 the -sslGenCert option below.
1672 Examples: x11vnc -sslGenCA x11vnc -sslGenCA ~/myCAdir x11vnc
1674 -ssldir ~/myCAdir -sslGenCA
1675 (the last two lines are equivalent)
1677 -sslGenCert type name
1679 Generate a VNC server or client certificate and private key pair
1681 signed by the CA created previously with -sslGenCA. The
1682 openssl(1) program must be installed on the system and available
1683 in PATH.
1684 After the Certificate is generated the command exits; the VNC
1686 server is not run.
1687 The type of key to be generated is the string type. It is
1689 either "server" (i.e. for use by x11vnc) or "client" (for a VNC
1690 viewer). Note that typically only "server" is used: the VNC
1691 clients authenticate themselves by a non-public-key method (e.g.
1692 VNC or unix password). type is required.
1693 An arbitrary default name you want to associate with the key is
1695 supplied by the name string. You can change it at the various
1696 prompts when creating the key. name is optional.
1697 If name is left blank for clients keys then "nobody" is used.
1699 If left blank for server keys, then the primary server key:
1700 "server.pem" is created (this is the saved one referenced by
1701 "-ssl SAVE" when the server is started)
1702 If name begins with the string "self:" then a self-signed cer‐
1704 tificate is created instead of one signed by your CA key.
1705 If name begins with the string "req:" then only a key (.key) and
1707 a certificate signing *request* (.req) are generated. You can
1708 then send the .req file to an external CA (even a professional
1709 one, e.g. Thawte) and then combine the .key and the received
1710 cert into the .pem file with the same basename.
1711 The distinction between "server" and "client" is simply the
1713 choice of output filenames and sub-directory. This makes it so
1714 the -ssl SAVE-name option can easily pick up the x11vnc PEM file
1715 this option generates. And similarly makes it easy for the
1716 -sslverify option to pick up your client certs.
1717 There is nothing special about the filename or directory loca‐
1719 tion of either the "server" and "client" certs. You can rename
1720 the files or move them to wherever you like.
1721 Precede this option with -ssldir [dir] to use a directory other
1723 than the default ~/.vnc/certs You will need to run -sslGenCA on
1724 that directory first before doing any -sslGenCert key creation.
1725 Note you cannot recreate a cert with exactly the same distigu‐
1727 ished name (DN) as an existing one. To do so, you will need to
1728 edit the [dir]/CA/index.txt file to delete the line.
1729 Similar to -sslGenCA, you will be prompted to fill in some
1731 information that will be recorded in the certificate when it is
1732 created. Tip: if you know the fully-qualified hostname other
1733 people will be connecting to you can use that as the CommonName
1734 "CN" to avoid some applications (e.g. web browsers and java
1735 plugin) complaining it does not match the hostname.
1736 You will also need to supply the CA private key passphrase to
1738 unlock the private key created from -sslGenCA. This private key
1739 is used to sign the server or client certificate.
1740 The "server" certs can be used by x11vnc directly by pointing to
1742 them via the -ssl [pem] option. The default file will be
1743 ~/.vnc/certs/server.pem. This one would be used by simply typ‐
1744 ing -ssl SAVE. The pem file contains both the certificate and
1745 the private key. server.crt file contains the cert only.
1746 The "client" cert + private key file will need to be copied and
1748 imported into the VNC viewer side applications (Web browser,
1749 Java plugin, stunnel, etc.) Once that is done you can delete
1750 the "client" private key file on this machine since it is only
1751 needed on the VNC viewer side. The, e.g.
1752 ~/.vnc/certs/clients/<name>.pem contains both the cert and pri‐
1753 vate key. The <name>.crt contains the certificate only.
1754 NOTE: It is very important to know one should always generate
1756 new keys with a passphrase. Otherwise if an untrusted user
1757 steals the key file he could use it to masquerade as the x11vnc
1758 server (or VNC viewer client). You will be prompted whether to
1759 encrypt the key with a passphrase or not. It is recommended
1760 that you do. One inconvenience to a passphrase is that it must
1761 be suppled every time x11vnc or the client app is started up.
1762 Examples:
1764 x11vnc -sslGenCert server x11vnc -ssl SAVE -display :0 ...
1766 and then on viewer using ss_vncviewer stunnel wrapper (see the
1768 FAQ): ss_vncviewer -verify ./cacert.crt hostname:0
1769 (this assumes the cacert.crt cert from -sslGenCA was safely
1771 copied to the VNC viewer machine where ss_vncviewer is run)
1772 Example using a name:
1774 x11vnc -sslGenCert server charlie x11vnc -ssl SAVE-charlie -dis‐
1776 play :0 ...
1777 Example for a client certificate (rarely used):
1779 x11vnc -sslGenCert client roger scp
1781 ~/.vnc/certs/clients/roger.pem somehost:. rm
1782 ~/.vnc/certs/clients/roger.pem
1783 x11vnc is then started with the the option -sslverify
1785 ~/.vnc/certs/clients/roger.crt (or simply -sslverify roger), and
1786 on the viewer user on somehost could do for example:
1787 ss_vncviewer -mycert ./roger.pem hostname:0
1789 If you set the env. var REQ_ARGS='...' it will be passed to
1791 openssl req(1). A common use would be REQ_ARGS='-days 1095' to
1792 bump up the expiration date (3 years in this case).
1793 -sslEncKey [pem]
1795 Utility to encrypt an existing PEM file with a passphrase you
1797 supply when prompted. For that key to be used (e.g. by x11vnc)
1798 the passphrase must be supplied each time.
1799 The "SAVE" notation described under -ssl applies as well. (pre‐
1801 cede this option with -ssldir [dir] to refer a directory besides
1802 the default ~/.vnc/certs)
1803 The openssl(1) program must be installed on the system and
1805 available in PATH. After the Key file is encrypted the command
1806 exits; the VNC server is not run.
1807 Examples: x11vnc -sslEncKey /path/to/foo.pem x11vnc -sslEncKey
1809 SAVE x11vnc -sslEncKey SAVE-charlie
1810 -sslCertInfo [pem]
1812 Prints out information about an existing PEM file. In addition
1814 the public certificate is also printed. The openssl(1) program
1815 must be in PATH. Basically the command "openssl x509 -text" is
1816 run on the pem.
1817 The "SAVE" notation described under -ssl applies as well.
1819 Using "LIST" will give a list of all certs being managed (in
1821 the ~/.vnc/certs dir, use -ssldir to refer to another dir).
1822 "ALL" will print out the info for every managed key (this can be
1823 very long). Giving a client or server cert shortname will also
1824 try a lookup (e.g. -sslCertInfo charlie). Use "LISTL" or "LL"
1825 for a long (ls -l style) listing.
1826 Using "HASHON" will create subdirs [dir]/HASH and [dir]/HASH
1828 with OpenSSL hash filenames (e.g. 0d5fbbf1.0) symlinks pointing
1829 up to the corresponding *.crt file. ([dir] is ~/.vnc/certs or
1830 one given by -ssldir.) This is a useful way for other OpenSSL
1831 applications (e.g. stunnel) to access all of the certs without
1832 having to concatenate them. x11vnc will not use them unless you
1833 specifically reference them. "HASHOFF" removes these HASH sub‐
1834 dirs.
1835 The LIST, LISTL, LL, ALL, HASHON, HASHOFF words can also be low‐
1837 ercase, e.g. "list".
1838 -sslDelCert [pem]
1840 Prompts you to delete all .crt .pem .key .req files associated
1842 with [pem]. "SAVE" and lookups as in -sslCertInfo apply as
1843 well.
1844 -stunnel [pem]
1846 Use the stunnel(8) (www.stunnel.org) to provide an encrypted SSL
1848 tunnel between viewers and x11vnc.
1849 This external tunnel method was implemented prior to the inte‐
1851 grated -ssl encryption described above. It still works well.
1852 This requires stunnel to be installed on the system and avail‐
1853 able via PATH (n.b. stunnel is often installed in sbin directo‐
1854 ries). Version 4.x of stunnel is assumed (but see -stunnel3
1855 below.)
1856 [pem] is optional, use "-stunnel /path/to/stunnel.pem" to spec‐
1858 ify a PEM certificate file to pass to stunnel. Whether one is
1859 needed or not depends on your stunnel configuration. stunnel
1860 often generates one at install time. See the stunnel documenta‐
1861 tion for details.
1862 stunnel is started up as a child process of x11vnc and any SSL
1864 connections stunnel receives are decrypted and sent to x11vnc
1865 over a local socket. The strings "The SSL VNC desktop is ..."
1866 and "SSLPORT=..." are printed out at startup to indicate this.
1867 The -localhost option is enforced by default to avoid people
1869 routing around the SSL channel. Set STUNNEL_DISABLE_LOCALHOST=1
1870 before starting x11vnc to disable the requirement.
1871 Your VNC viewer will also need to be able to connect via SSL.
1873 Unfortunately not too many do this. UltraVNC has an encryption
1874 plugin but it does not seem to be SSL.
1875 Also, in the x11vnc distribution, a patched TightVNC Java applet
1877 is provided in classes/ssl that does SSL connections (only).
1878 It is also not too difficult to set up an stunnel or other SSL
1880 tunnel on the viewer side. A simple example on Unix using stun‐
1881 nel 3.x is:
1882 % stunnel -c -d localhost:5901 -r remotehost:5900 % vncviewer
1884 localhost:1
1885 For Windows, stunnel has been ported to it and there are proba‐
1887 bly other such tools available. See the FAQ and SSVNC for more
1888 examples.
1889 -stunnel3 [pem]
1891 Use version 3.x stunnel command line syntax instead of version
1893 4.x
1894 -enc cipher:keyfile
1896 Use symmetric encryption with cipher "cipher" and secret key
1898 data in "keyfile". If keyfile is pw=<string> then "string" is
1899 used as the key data.
1900 NOTE: It is recommended that you use SSL via the -ssl option
1902 instead of this option because SSL is well understood and takes
1903 great care to establish unique session keys and is more compati‐
1904 ble with other software. Use this option if you do not want to
1905 deal with SSL certificates for authentication and do not want to
1906 use SSH but want some encryption for your VNC session. Or if
1907 you must interface with a symmetric key tunnel that you do not
1908 have control over.
1909 Note that this mode will NOT work with the UltraVNC DSM plugins
1911 because they alter the RFB protocol in addition to tunnelling
1912 with the symmetric cipher (an unfortunate choice of implementa‐
1913 tion).
1914 cipher can be one of: arc4, aesv2, aes-cfb, blowfish, aes256,
1916 or 3des. See the OpenSSL documentation for more info. The key‐
1917 size is 128 bits (except for aes256). Here is one way to make a
1918 keyfile with that many bits:
1919 dd if=/dev/random of=./my.key bs=16 count=1
1921 you will need to securely share this key with the other side of
1923 the VNC connection (See SSVNC for examples).
1924 Example: -enc blowfish:./my.key Example: -enc blow‐
1926 fish:pw=swordfish
1927 By default 16 bytes of random salt followed by 16 bytes of ran‐
1929 dom initialization vector are sent at the very beginning of the
1930 stream. The other side must read these and initialize their
1931 cipher with them. These values make the session key unique
1932 (without them the security is minimal). Similarly, the other
1933 side must send us its random salt and IV with those same
1934 lengths.
1935 The salt and key data are combined to create a session key using
1937 an md5 hash as described in EVP_BytesToKey(3).
1938 The exact call is: EVP_BytesToKey(Cipher, EVP_md5(), salt, key‐
1940 data, len, 1, keystr, NULL); where salt is the random data as
1941 described above, and keydata is the shared secret key data.
1942 keystr is the resulting session key. The cipher is then seeded
1943 with keystr and uses the random initialization vector as its
1944 first block.
1945 To modify the amount of random salt and initialization vector
1947 use cipher@n,m where n is the salt length and m the initializa‐
1948 tion vector length. E.g.
1949 -enc aes-cfb@8,16:./my.key
1951 It is not a good idea to set either one to zero, although you
1953 may be forced to if the other side of the tunnel is not under
1954 your control.
1955 To skip the salt and EVP_BytesToKey MD5 entirely (no hashing is
1957 done: the keydata is directly inserted into the cipher) specify
1958 "-1" for the salt, e.g.
1959 -enc blowfish@-1,16:./my.key
1961 The message digest can also be changed to something besides the
1963 default MD5. Use cipher@md+n,m where "md" can be one of sha,
1964 sha1, md5, or ripe. For example:
1965 -enc arc4@sha+8,16:./my.key
1967 The SSVNC vnc viewer project supplies a symmetric encryption
1969 tool named "ultravnc_dsm_helper" that can be used on the viewer
1970 side. For example:
1971 ssvncviewer exec='ultravnc_dsm_helper arc4 my.key 0 h:p'
1973 where h:p is the hostname and port of the x11vnc server. ultra‐
1975 vnc_dsm_helper may also be used standalone to provide a symmet‐
1976 ric encryption tunnel for any viewer or server (VNC or other‐
1977 wise.) The cipher (1st arg) is basically the same syntax as we
1978 use above.
1979 Also see the 'Non-Ultra DSM' SSVNC option for the ´UltraVNC DSM
1981 Encryption Plugin' advanced option.
1982 For both ways of using the viewer, you can specify the salt,ivec
1984 sizes (in GUI or, e.g. arc4@8,16).
1985 -https [port]
1987 Use a special, separate HTTPS port (-ssl mode only) for HTTPS
1989 Java viewer applet downloading. I.e. not 5900 and not 5800 (the
1990 defaults.)
1991 BACKGROUND: In -ssl mode, it turns out you can use the single
1993 VNC port (e.g. 5900) for both VNC and HTTPS connections. (HTTPS
1994 is used to retrieve a SSL-aware VncViewer.jar applet that is
1995 provided with x11vnc). Since both use SSL the implementation
1996 was extended to detect if HTTP traffic (i.e. GET) is taking
1997 place and handle it accordingly. The URL would be, e.g.:
1998 https://mymachine.org:5900/
2000 This is convenient for firewalls, etc, because only one port
2002 needs to be allowed in. However, this heuristic adds a few sec‐
2003 onds delay to each connection and can be unreliable (especially
2004 if the user takes much time to ponder the Certificate dialogs in
2005 his browser, Java VM, or VNC Viewer applet. That's right 3 sep‐
2006 arate "Are you sure you want to connect?" dialogs!)
2007 USAGE: So use the -https option to provide a separate, more
2009 reliable HTTPS port that x11vnc will listen on. If [port] is
2010 not provided (or is 0), one is autoselected. The URL to use is
2011 printed out at startup.
2012 The SSL Java applet directory is specified via the -httpdir
2014 option. If not supplied, -https will try to guess the directory
2015 as though the -http option was supplied.
2016 -httpsredir [port]
2018 In -ssl mode with the Java applet retrieved via HTTPS, when the
2020 HTML file containing applet parameters ('index.vnc' or
2021 'proxy.vnc') is sent do NOT set the applet PORT parameter to the
2022 actual VNC port but set it to "port" instead. If "port" is not
2023 supplied, then the port number is guessed from the Host: HTTP
2024 header.
2025 This is useful when an incoming TCP connection redirection is
2027 performed by a router/gateway/firewall from one port to an
2028 internal machine where x11vnc is listening on a different port.
2029 The Java applet needs to connect to the firewall/router port,
2030 not the VNC port on the internal workstation. For example, one
2031 could redir from mygateway.com:443 to workstation:5900.
2032 This spares the user from having to type in https://mygate‐
2034 way.com/?PORT=443 into their web browser. Note that port 443 is
2035 the default https port; other ports must be explicitly indi‐
2036 cated, for example: https://mygateway.com:8000/?PORT=8000. To
2037 avoid having to include the PORT= in the browser URL, simply
2038 supply "-httpsredir" to x11vnc.
2039 -http_oneport
2041 For un-encrypted connections mode (i.e. no -ssl, -stunnel, or
2043 -enc options), allow the Java VNC Viewer applet to be downloaded
2044 thru the VNC port via HTTP.
2045 That is to say, you can use a single port for Java applet viewer
2047 connections by using a URL in your web browser like this, for
2048 example:
2049 http://hostname:5900
2051 The regular, two-port mode, URL http://hostname:5800 will con‐
2053 tinue to work as well.
2054 As mentioned above, this mode will NOT work with the -ssl,
2056 -stunnel, or -enc encryption options. Note that is it equiva‐
2057 lent to '-enc none' (i.e. it uses the same detection mechanism
2058 as for HTTPS, but with no encryption.)
2059 HTTPS single-port is on by default in -ssl encrypted mode (and
2061 -enc too), so you only need -http_oneport when doing non-SSL
2062 encrypted connections.
2063 This mode could also be useful for SSH tunnels since it means
2065 only one port needs to be redirected.
2066 The -httpsredir option may also be useful for this mode when
2068 using an SSH tunnel as well as for router port redirections.
2069 -ssh user@host:disp
2071 Create a remote listening port on machine "host" via a SSH tun‐
2073 nel using the -R rport:localhost:lport method. lport will be the
2074 local x11vnc listening port, so a connection to rport
2075 (5900+disp) on "host" will reach x11vnc. E.g. fred@snoopy.com:0
2076 This could be useful if a firewall/router prevents incoming con‐
2078 nections to the x11vnc machine, but the ssh machine "host" can
2079 be reached by the VNC viewer. "user@" is not needed unless the
2080 remote unix username differs from the current one.
2081 By default the remote sshd is usually configured to only listen
2083 on localhost for rport, so the viewer may need to ssh -L redir
2084 to "host" as well (See SSVNC to automate this). The sshd set‐
2085 ting GatewayPorts enables listening on all interfaces for rport;
2086 viewers can reach it more easily.
2087 "disp" is the VNC display for the remote SSH side, e.g. 0 corre‐
2089 sponds to port 5900, etc. If disp is greater than 200 the value
2090 is used as the port. Use a negative value to force a low port,
2091 e.g. host:-80 will use port 80.
2092 If ssh-agent is not active, then the ssh password needs to be
2094 entered in the terminal where x11vnc is running.
2095 By default the remote ssh will issue a 'sleep 300' to wait for
2097 the incoming connection for 5 mins. To modify this use
2098 user@host:disp+secs.
2099 If the remote SSH server is on a non-standard port (i.e. not 22)
2101 use user@host:port:disp+secs.
2102 Note that the ssh process MAY NOT be killed when x11vnc exits.
2104 It tries by looking at ps(1) output.
2105 -usepw
2107 If no other password method was supplied on the command line,
2109 first look for ~/.vnc/passwd and if found use it with -rfbauth;
2110 next, look for ~/.vnc/passwdfile and use it with -passwdfile;
2111 otherwise, prompt the user for a password to create
2112 ~/.vnc/passwd and use it with the -rfbauth option. If none of
2113 these succeed x11vnc exits immediately.
2114 -storepasswd pass file
2116 Store password pass as the VNC password in the file file. Once
2118 the password is stored the program exits. Use the password via
2119 "-rfbauth file"
2120 If called with no arguments, "x11vnc -storepasswd", the user is
2122 prompted for a password and it is stored in the file
2123 ~/.vnc/passwd. Called with one argument, that will be the file
2124 to store the prompted password in.
2125 -nopw
2127 Disable the big warning message when you use x11vnc without some
2129 sort of password.
2130 -accept string
2132 Run a command (possibly to prompt the user at the X11 display)
2134 to decide whether an incoming client should be allowed to con‐
2135 nect or not. string is an external command run via system(3) or
2136 some special cases described below. Be sure to quote string if
2137 it contains spaces, shell characters, etc. If the external com‐
2138 mand returns 0 the client is accepted, otherwise the client is
2139 rejected. See below for an extension to accept a client view-
2140 only.
2141 If x11vnc is running as root (say from inetd(8) or from display
2143 managers xdm(1) , gdm(1) , etc), think about the security impli‐
2144 cations carefully before supplying this option (likewise for the
2145 -gone option).
2146 Environment: The RFB_CLIENT_IP environment variable will be set
2148 to the incoming client IP number and the port in RFB_CLIENT_PORT
2149 (or -1 if unavailable). Similarly, RFB_SERVER_IP and
2150 RFB_SERVER_PORT (the x11vnc side of the connection), are set to
2151 allow identification of the tcp virtual circuit. The x11vnc
2152 process id will be in RFB_X11VNC_PID, a client id number in
2153 RFB_CLIENT_ID, and the number of other connected clients in
2154 RFB_CLIENT_COUNT. RFB_MODE will be "accept". RFB_STATE will be
2155 PROTOCOL_VERSION, SECURITY_TYPE, AUTHENTICATION, INITIALISATION,
2156 NORMAL, or UNKNOWN indicating up to which state the client has
2157 achieved. RFB_LOGIN_VIEWONLY will be 0, 1, or -1 (unknown).
2158 RFB_USERNAME, RFB_LOGIN_TIME, and RFB_CURRENT_TIME may also be
2159 set.
2160 If string is "popup" then a builtin popup window is used. The
2162 popup will time out after 120 seconds, use "popup:N" to modify
2163 the timeout to N seconds (use 0 for no timeout).
2164 In the case of "popup" and when the -unixpw option is specified,
2166 then a *second* window will be popped up after the user success‐
2167 fully logs in via his UNIX password. This time the user will be
2168 identified as UNIX:username@hostname, the "UNIX:" prefix indi‐
2169 cates which user the viewer logged as via -unixpw. The first
2170 popup is only for whether to allow him to even *try* to login
2171 via unix password.
2172 If string is "xmessage" then an xmessage(1) invocation is used
2174 for the command. xmessage must be installed on the machine for
2175 this to work.
2176 Both "popup" and "xmessage" will present an option for accepting
2178 the client "View-Only" (the client can only watch). This option
2179 will not be presented if -viewonly has been specified, in which
2180 case the entire display is view only.
2181 If the user supplied command is prefixed with something like
2183 "yes:0,no:*,view:3 mycommand ..." then this associates the
2184 numerical command return code with the actions: accept, reject,
2185 and accept-view-only, respectively. Use "*" instead of a number
2186 to indicate the default action (in case the command returns an
2187 unexpected value). E.g. "no:*" is a good choice.
2188 Note that x11vnc blocks while the external command or popup is
2190 running (other clients may see no updates during this period).
2191 So a person sitting a the physical display is needed to respond
2192 to an popup prompt. (use a 2nd x11vnc if you lock yourself out).
2193 More -accept tricks: use "popupmouse" to only allow mouse clicks
2195 in the builtin popup to be recognized. Similarly use "popupkey"
2196 to only recognize keystroke responses. These are to help avoid
2197 the user accidentally accepting a client by typing or clicking.
2198 All 3 of the popup keywords can be followed by +N+M to supply a
2199 position for the popup window. The default is to center the
2200 popup window.
2201 -afteraccept string
2203 As -accept, except to run a user supplied command after a client
2205 has been accepted and authenticated. RFB_MODE will be set to
2206 "afteraccept" and the other RFB_* variables are as in -accept.
2207 Unlike -accept, the command return code is not interpreted by
2208 x11vnc. Example: -afteraccept 'killall xlock &'
2209 -gone string
2211 As -accept, except to run a user supplied command when a client
2213 goes away (disconnects). RFB_MODE will be set to "gone" and the
2214 other RFB_* variables are as in -accept. The "popup" actions
2215 apply as well. Unlike -accept, the command return code is not
2216 interpreted by x11vnc. Example: -gone 'xlock &'
2217 -users list
2219 If x11vnc is started as root (say from inetd(8) or from display
2221 managers xdm(1) , gdm(1) , etc), then as soon as possible after
2222 connections to the X display are established try to switch to
2223 one of the users in the comma separated list. If x11vnc is not
2224 running as root this option is ignored.
2225 Why use this option? In general it is not needed since x11vnc
2227 is already connected to the X display and can perform its pri‐
2228 mary functions. The option was added to make some of the
2229 *external* utility commands x11vnc occasionally runs work prop‐
2230 erly. In particular under GNOME and KDE to implement the
2231 "-solid color" feature external commands (gconftool-2 and dcop)
2232 unfortunately must be run as the user owning the desktop ses‐
2233 sion. Since this option switches userid it also affects the
2234 userid used to run the processes for the -accept and -gone
2235 options. It also affects the ability to read files for options
2236 such as -connect, -allow, and -remap and also the ultra and
2237 tight filetransfer feature if enabled. Note that the -connect
2238 file is also sometimes written to.
2239 So be careful with this option since in some situations its use
2241 can decrease security.
2242 In general the switch to a user will only take place if the dis‐
2244 play can still be successfully opened as that user (this is pri‐
2245 marily to try to guess the actual owner of the session). Exam‐
2246 ple: "-users fred,wilma,betty". Note that a malicious local
2247 user "barney" by quickly using "xhost +" when logging in may
2248 possibly get the x11vnc process to switch to user "fred". What
2249 happens next?
2250 Under display managers it may be a long time before the switch
2252 succeeds (i.e. a user logs in). To instead make it switch imme‐
2253 diately regardless if the display can be reopened prefix the
2254 username with the "+" character. E.g. "-users +bob" or "-users
2255 +nobody".
2256 The latter (i.e. switching immediately to user "nobody") is the
2258 only obvious use of the -users option that increases security.
2259 Use the following notation to associate a group with a user:
2261 user1.group1,user2.group2,... Note that initgroups(2) will
2262 still be called first to try to switch to ALL of a user's groups
2263 (primary and additional groups). Only if that fails or it is
2264 not available then the single group specified as above (or the
2265 user's primary group if not specified) is switched to with set‐
2266 gid(2). Use -env X11VNC_SINGLE_GROUP=1 to prevent trying init‐
2267 groups(2) and only switch to the single group. This sort of
2268 setting is only really needed to make the ultra or tight file‐
2269 transfer permissions work properly. This format applies to any
2270 comma separated list of users, even the special "=" modes
2271 described below.
2272 In -unixpw mode, if "-users unixpw=" is supplied then after a
2274 user authenticates himself via the -unixpw mechanism, x11vnc
2275 will try to switch to that user as though "-users +username" had
2276 been supplied. If you want to limit which users this will be
2277 done for, provide them as a comma separated list after "unixpw="
2278 Groups can also be specified as described above.
2279 Similarly, in -ssl mode, if "-users sslpeer=" is supplied then
2281 after an SSL client authenticates with his cert (the -sslverify
2282 option is required for this) x11vnc will extract a UNIX username
2283 from the "emailAddress" field (username@hostname.com) of the
2284 "Subject" of the x509 SSL cert and then try to switch to that
2285 user as though "-users +username" had been supplied. If you
2286 want to limit which users this will be done for, provide them as
2287 a comma separated list after "sslpeer=". Set the env. var
2288 X11VNC_SSLPEER_CN to use the Common Name (normally a hostname)
2289 instead of the Email field.
2290 NOTE: for sslpeer= mode the x11vnc administrator must take care
2292 that any client certs he adds to -sslverify have the intended
2293 UNIX username in the "emailAddress" field of the cert. Other‐
2294 wise a user may be able to log in as another. This command can
2295 be of use in checking: "openssl x509 -text -in file.crt", see
2296 the "Subject:" line. Also, along with the normal RFB_* env.
2297 vars. (see -accept) passed to external cmd= commands,
2298 RFB_SSL_CLIENT_CERT will be set to the client's x509 certificate
2299 string.
2300 The sslpeer= mode can aid finding X sessions via the FINDDISPLAY
2302 and FINDCREATEDISPLAY mechanisms.
2303 To immediately switch to a user *before* connections to the X
2305 display are made or any files opened use the "=" character:
2306 "-users =bob". That user needs to be able to open the X display
2307 and any files of course.
2308 The special user "guess=" means to examine the utmpx database
2310 (see who(1) ) looking for a user attached to the display number
2311 (from DISPLAY or -display option) and try him/her. To limit the
2312 list of guesses, use: "-users guess=bob,betty".
2313 Even more sinister is the special user "lurk=" that means to try
2315 to guess the DISPLAY from the utmpx login database as well. So
2316 it "lurks" waiting for anyone to log into an X session and then
2317 connects to it. Specify a list of users after the = to limit
2318 which users will be tried. To enable a different searching
2319 mode, if the first user in the list is something like ":0" or
2320 ":0-2" that indicates a range of DISPLAY numbers that will be
2321 tried (regardless of whether they are in the utmpx database) for
2322 all users that are logged in. Also see the "-display WAIT:..."
2323 functionality. Examples: "-users lurk=" and also "-users
2324 lurk=:0-1,bob,mary"
2325 Be especially careful using the "guess=" and "lurk=" modes.
2327 They are not recommended for use on machines with untrustworthy
2328 local users.
2329 -noshm
2331 Do not use the MIT-SHM extension for the polling. Remote dis‐
2333 plays can be polled this way: be careful this can use large
2334 amounts of network bandwidth. This is also of use if the local
2335 machine has a limited number of shm segments and -onetile is not
2336 sufficient.
2337 -flipbyteorder
2339 Sometimes needed if remotely polled host has different endian‐
2341 ness. Ignored unless -noshm is set.
2342 -onetile
2344 Do not use the new copy_tiles() framebuffer mechanism, just use
2346 1 shm tile for polling. Limits shm segments used to 3.
2347 -solid [color]
2349 To improve performance, when VNC clients are connected try to
2351 change the desktop background to a solid color. The [color] is
2352 optional: the default color is "cyan4". For a different one
2353 specify the X color (rgb.txt name, e.g. "darkblue" or numerical
2354 "#RRGGBB").
2355 Currently this option only works on GNOME, KDE, CDE, and classic
2357 X (i.e. with the background image on the root window). The
2358 "gconftool-2" and "dcop" external commands are run for GNOME and
2359 KDE respectively. Other desktops won't work, e.g. Xfce (send us
2360 the corresponding commands if you find them). If x11vnc is run‐
2361 ning as root ( inetd(8) or gdm(1) ), the -users option may be
2362 needed for GNOME and KDE. If x11vnc guesses your desktop incor‐
2363 rectly, you can force it by prefixing color with "gnome:",
2364 "kde:", "cde:" or "root:".
2365 This mode works in a limited way on the Mac OS X Console with
2367 one color ('kelp') using the screensaver writing to the back‐
2368 ground. Look in "~/Library/Screen Savers" for VncSolidColor.png
2369 to change the color.
2370 -blackout string
2372 Black out rectangles on the screen. string is a comma separated
2374 list of WxH+X+Y type geometries for each rectangle. If one of
2375 the items on the list is the string "noptr" the mouse pointer
2376 will not be allowed to go into a blacked out region.
2377 -xinerama, -noxinerama
2379 If your screen is composed of multiple monitors glued together
2381 via XINERAMA, and that screen is not a rectangle this option
2382 will try to guess the areas to black out (if your system has
2383 libXinerama). default: -xinerama
2384 In general, we have noticed on XINERAMA displays you may need to
2386 use the "-xwarppointer" option if the mouse pointer misbehaves
2387 and it is enabled by default. Use "-noxwarppointer" if you do
2388 not want this.
2389 -xtrap
2391 Use the DEC-XTRAP extension for keystroke and mouse input inser‐
2393 tion. For use on legacy systems, e.g. X11R5, running an incom‐
2394 plete or missing XTEST extension. By default DEC-XTRAP will be
2395 used if XTEST server grab control is missing, use -xtrap to do
2396 the keystroke and mouse insertion via DEC-XTRAP as well.
2397 -xrandr [mode]
2399 If the display supports the XRANDR (X Resize, Rotate and Reflec‐
2401 tion) extension, and you expect XRANDR events to occur to the
2402 display while x11vnc is running, this options indicates x11vnc
2403 should try to respond to them (as opposed to simply crashing by
2404 assuming the old screen size). See the xrandr(1) manpage and
2405 run ´xrandr -q' for more info. [mode] is optional and described
2406 below.
2407 Since watching for XRANDR events and trapping errors increases
2409 polling overhead, only use this option if XRANDR changes are
2410 expected. For example on a rotatable screen PDA or laptop, or
2411 using a XRANDR-aware Desktop where you resize often. It is best
2412 to be viewing with a vncviewer that supports the NewFBSize
2413 encoding, since it knows how to react to screen size changes.
2414 Otherwise, libvncserver tries to do so something reasonable for
2415 viewers that cannot do this (portions of the screen may be
2416 clipped, unused, etc).
2417 Note: the default now is to check for XRANDR events, but do not
2419 trap every X call that may fail due to resize. If a resize
2420 event is received, the full -xrandr mode is enabled. To disable
2421 even checking for events supply: -noxrandr.
2422 "mode" defaults to "resize", which means create a new, resized,
2424 framebuffer and hope all viewers can cope with the change.
2425 "newfbsize" means first disconnect all viewers that do not sup‐
2426 port the NewFBSize VNC encoding, and then resize the frame‐
2427 buffer. "exit" means disconnect all viewer clients, and then
2428 terminate x11vnc.
2429 -rotate string
2431 Rotate and/or flip the framebuffer view exported by VNC. This
2433 transformation is independent of XRANDR and is done in software
2434 in main memory and so may be slower. This mode could be useful
2435 on a handheld with portrait or landscape modes that do not cor‐
2436 respond to the scanline order of the actual framebuffer. string
2437 can be:
2438 x flip along x-axis y flip along y-axis xy flip
2440 along x- and y-axes +90 rotate 90 degrees clockwise -90
2441 rotate 90 degrees counter-clockwise +90x rotate 90 degrees
2442 CW, then flip along x +90y rotate 90 degrees CW, then flip
2443 along y
2444 these give all possible rotations and reflections.
2446 Aliases: same as xy: yx, +180, -180, 180 same as -90: +270, 270
2448 same as +90: 90, (ditto for 90x, 90y)
2449 Like -scale, this transformation is applied at the very end of
2451 any chain of framebuffer transformations and so any options with
2452 geometries, e.g. -blackout, -clip, etc. are relative to the
2453 original X (or -rawfb) framebuffer, not the final one sent to
2454 VNC viewers.
2455 If you do not want the cursor shape to be rotated prefix string
2457 with "nc:", e.g. "nc:+90", "nc:xy", etc.
2458 -padgeom WxH
2460 Whenever a new vncviewer connects, the framebuffer is replaced
2462 with a fake, solid black one of geometry WxH. Shortly after‐
2463 wards the framebuffer is replaced with the real one. This is
2464 intended for use with vncviewers that do not support NewFBSize
2465 and one wants to make sure the initial viewer geometry will be
2466 big enough to handle all subsequent resizes (e.g. under -xrandr,
2467 -remote id:windowid, rescaling, etc.)
2468 In -unixpw mode this sets the size of the login screen. Use
2470 "once:WxH" it ignore padgeom after the login screen is set up.
2471 -o logfile
2473 Write stderr messages to file logfile instead of to the termi‐
2475 nal. Same as "-logfile file". To append to the file use "-oa
2476 file" or "-logappend file". If logfile contains the string
2477 "%VNCDISPLAY" it is expanded to the vnc display (the name may
2478 need to be guessed at.) "%HOME" works too.
2479 -flag file
2481 Write the "PORT=NNNN" (e.g. PORT=5900) string to file in addi‐
2483 tion to stdout. This option could be useful by wrapper script
2484 to detect when x11vnc is ready.
2485 -rmflag file
2487 Remove file at exit to signal when x11vnc is done. The file is
2489 created at startup if it does not already exist or if file is
2490 prefixed with "create:". If the file is created, the x11vnc PID
2491 is placed in the file. Otherwise the files contents is not
2492 changed. Use prefix "nocreate:" to prevent creation.
2493 -rc filename
2495 Use filename instead of $HOME/.x11vncrc for rc file.
2497 -norc
2499 Do not process any .x11vncrc file for options.
2501 -env VAR=VALUE
2503 Set the environment variable 'VAR' to value 'VALUE' at x11vnc
2505 startup. This is a convenience utility to avoid shell script
2506 wrappers, etc. to set the env. var. You may specify as many of
2507 these as needed on the command line.
2508 -prog /path/to/x11vnc
2510 Set the full path to the x11vnc program for cases when it cannot
2512 be determined from argv[0] (e.g. tcpd/inetd)
2513 -h, -help
2515 Print this help text. -?, -opts Only list the
2517 x11vnc options.
2518 -V, -version
2520 Print program version and last modification date.
2522 -license
2524 Print out license information. Same as -copying and -warranty.
2526 -dbg
2528 Instead of exiting after cleaning up, run a simple "debug crash
2530 shell" when fatal errors are trapped.
2531 -q, -quiet
2533 Be quiet by printing less informational output to stderr.
2535 -v, -verbose
2537 Print out more information to stderr.
2539 -bg
2541 Go into the background after screen setup. Messages to stderr
2543 are lost unless -o logfile is used. Something like this could
2544 be useful in a script:
2545 port=`ssh -t $host "x11vnc -display :0 -bg" | grep PORT`
2547 port=`echo "$port" | sed -e 's/PORT=//'`
2549 port=`expr $port - 5900`
2551 vncviewer $host:$port
2553 -modtweak, -nomodtweak
2555 Option -modtweak automatically tries to adjust the AltGr and
2557 Shift modifiers for differing language keyboards between client
2558 and host. Otherwise, only a single key press/release of a Key‐
2559 code is simulated (i.e. ignoring the state of the modifiers:
2560 this usually works for identical keyboards). Also useful in
2561 resolving cases where a Keysym is bound to multiple keys (e.g.
2562 "<" + ">" and "," + "<" keys). Default: -modtweak
2563 If you are having trouble with with keys and -xkb or -noxkb, and
2565 similar things don't help, try -nomodtweak.
2566 On some HP-UX systems it is been noted that they have an odd
2568 keymapping where a single keycode will have a keysym, e.g. "#",
2569 up to three times. You can check via "xmodmap -pk" or the -dk
2570 option. The failure is when you try to type "#" it yields "3".
2571 If you see this problem try setting the environment variable
2572 MODTWEAK_LOWEST=1 to see if it helps.
2573 -xkb, -noxkb
2575 When in modtweak mode, use the XKEYBOARD extension (if the X
2577 display supports it) to do the modifier tweaking. This is pow‐
2578 erful and should be tried if there are still keymapping problems
2579 when using -modtweak by itself. The default is to check whether
2580 some common keysyms, e.g. !, @, [, are only accessible via -xkb
2581 mode and if so then automatically enable the mode. To disable
2582 this automatic detection use -noxkb.
2583 When -xkb mode is active you can set these env. vars. They
2585 apply only when there is ambiguity as to which key to choose
2586 (i.e the mapping is not one-to-one). NOKEYHINTS=1: for up ascii
2587 keystrokes do not use score hints saved when the key was pressed
2588 down. NOANYDOWN=1: for up keystrokes do not resort to searching
2589 through keys that are currently pressed down. KEYSDOWN=N:
2590 remember the last N keys press down for tie-breaking when an up
2591 keystroke comes in.
2592 -capslock
2594 When in -modtweak (the default) or -xkb mode, if a keysym in the
2596 range A-Z comes in check the X server to see if the Caps_Lock is
2597 set. If it is do not artificially press Shift to generate the
2598 keysym. This will enable the CapsLock key to behave correctly
2599 in some circumstances: namely *both* the VNC viewer machine and
2600 the x11vnc X server are in the CapsLock on state. If one side
2601 has CapsLock on and the other off and the keyboard is not behav‐
2602 ing as you think it should you should correct the CapsLock
2603 states (hint: pressing CapsLock inside and outside of the viewer
2604 can help toggle them both to the correct state). However, for
2605 best results do not use this option, but rather *only* enable
2606 CapsLock on the VNC viewer side (i.e. by pressing CapsLock out‐
2607 side of the viewer window, also -skip_lockkeys below). Also try
2608 -nomodtweak for a possible workaround.
2609 -skip_lockkeys, -noskip_lockkeys
2611 Have x11vnc ignore all Caps_Lock, Shift_Lock, Num_Lock,
2613 Scroll_Lock keysyms received from viewers. The idea is you
2614 press Caps_Lock on the VNC Viewer side but that does not change
2615 the lock state in the x11vnc-side X server. Nevertheless your
2616 capitalized letters come in over the wire and are applied cor‐
2617 rectly to the x11vnc-side X server. Note this mode probably
2618 won't do what you want in -nomodtweak mode. Also, a kludge for
2619 KP_n digits is always done it this mode: they are mapped to reg‐
2620 ular digit keysyms. See also -capslock above. The default is
2621 -noskip_lockkeys.
2622 -skip_keycodes string
2624 Ignore the comma separated list of decimal keycodes. Perhaps
2626 these are keycodes not on your keyboard but your X server thinks
2627 exist. Currently only applies to -xkb mode. Use this option to
2628 help x11vnc in the reverse problem it tries to solve: Keysym ->
2629 Keycode(s) when ambiguities exist (more than one Keycode per
2630 Keysym). Run 'xmodmap -pk' to see your keymapping. Example:
2631 "-skip_keycodes 94,114"
2632 -sloppy_keys
2634 Experimental option that tries to correct some "sloppy" key
2636 behavior. E.g. if at the viewer you press Shift+Key but then
2637 release the Shift before Key that could give rise to extra
2638 unwanted characters (usually only between keyboards of different
2639 languages). Only use this option if you observe problems with
2640 some keystrokes.
2641 -skip_dups, -noskip_dups
2643 Some VNC viewers send impossible repeated key events, e.g. key-
2645 down, key-down, key-up, key-up all for the same key, or 20 downs
2646 in a row for the same modifier key! Setting -skip_dups means to
2647 skip these duplicates and just process the first event. Note:
2648 some VNC viewers assume they can send down's without the corre‐
2649 sponding up's and so you should not set this option for these
2650 viewers (symptom: some keys do not autorepeat) Default:
2651 -noskip_dups
2652 -add_keysyms, -noadd_keysyms
2654 If a Keysym is received from a VNC viewer and that Keysym does
2656 not exist in the X server, then add the Keysym to the X server's
2657 keyboard mapping on an unused key. Added Keysyms will be
2658 removed periodically and also when x11vnc exits. Default:
2659 -add_keysyms
2660 -clear_mods
2662 At startup and exit clear the modifier keys by sending KeyRe‐
2664 lease for each one. The Lock modifiers are skipped. Used to
2665 clear the state if the display was accidentally left with any
2666 pressed down.
2667 -clear_keys
2669 As -clear_mods, except try to release ANY pressed key. Note
2671 that this option and -clear_mods can interfere with a person
2672 typing at the physical keyboard.
2673 -clear_all
2675 As -clear_keys, except try to release any CapsLock, NumLock,
2677 etc. locks as well.
2678 -remap string
2680 Read Keysym remappings from file named string. Format is one
2682 pair of Keysyms per line (can be name or hex value) separated by
2683 a space. If no file named string exists, it is instead inter‐
2684 preted as this form: key1-key2,key3-key4,... See
2685 <X11/keysymdef.h> header file for a list of Keysym names, or use
2686 xev(1).
2687 To map a key to a button click, use the fake Keysyms "Button1",
2689 ..., etc. E.g: "-remap Super_R-Button2" (useful for pasting on a
2690 laptop)
2691 I use these if the machine I am viewing from does not have a
2693 scrollwheel or I don't like using the one it has:
2694 -remap Super_R-Button4,Menu-Button5 -remap KP_Add-But‐
2696 ton4,KP_Enter-Button5
2697 the former would be used on a PC, the latter on a MacBook. This
2699 way those little used keys can be used to generate bigger hops
2700 than the Up and Down arrows provide. One can scroll through
2701 text or web pages more quickly this way (especially if x11vnc
2702 scroll detection is active.)
2703 Use Button44, Button12, etc. for multiple clicks.
2705 To disable a keysym (i.e. make it so it will not be injected),
2707 remap it to "NoSymbol" or "None".
2708 Dead keys: "dead" (or silent, mute) keys are keys that do not
2710 produce a character but must be followed by a 2nd keystroke.
2711 This is often used for accenting characters, e.g. to put "`" on
2712 top of "a" by pressing the dead key and then "a". Note that
2713 this interpretation is not part of core X11, it is up to the
2714 toolkit or application to decide how to react to the sequence.
2715 The X11 names for these keysyms are "dead_grave", "dead_acute",
2716 etc. However some VNC viewers send the keysyms "grave", "acute"
2717 instead thereby disabling the accenting. To work around this
2718 -remap can be used. For example "-remap grave-dead_grave,acute-
2719 dead_acute"
2720 As a convenience, "-remap DEAD" applies these remaps:
2722 g grave-dead_grave
2724 a acute-dead_acute
2725 c asciicircum-dead_circumflex
2726 t asciitilde-dead_tilde
2727 m macron-dead_macron
2728 b breve-dead_breve
2729 D abovedot-dead_abovedot
2730 d diaeresis-dead_diaeresis
2731 o degree-dead_abovering
2732 A doubleacute-dead_doubleacute
2733 r caron-dead_caron
2734 e cedilla-dead_cedilla
2735 If you just want a subset use the first letter label, e.g.
2737 "-remap DEAD=ga" to get the first two. Additional remaps may
2738 also be supplied via commas, e.g. "-remap DEAD=ga,Super_R-But‐
2739 ton2". Finally, "DEAD=missing" means to apply all of the above
2740 as long as the left hand member is not already in the X11
2741 keymap.
2742 -norepeat, -repeat
2744 Option -norepeat disables X server key auto repeat when VNC
2746 clients are connected and VNC keyboard input is not idle for
2747 more than 5 minutes. This works around a repeating keystrokes
2748 bug (triggered by long processing delays between key down and
2749 key up client events: either from large screen changes or high
2750 latency). Default: -norepeat
2751 You can set the env. var. X11VNC_IDLE_TIMEOUT to the number of
2753 idle seconds you want (5min = 300secs).
2754 Note: your VNC viewer side will likely do autorepeating, so this
2756 is no loss unless someone is simultaneously at the real X dis‐
2757 play.
2758 Use "-norepeat N" to set how many times norepeat will be reset
2760 if something else (e.g. X session manager) undoes it. The
2761 default is 2. Use a negative value for unlimited resets.
2762 -nofb
2764 Ignore video framebuffer: only process keyboard and pointer.
2766 Intended for use with Win2VNC and x2vnc dual-monitor setups.
2767 -nobell
2769 Do not watch for XBell events. (no beeps will be heard) Note:
2771 XBell monitoring requires the XKEYBOARD extension.
2772 -nosel
2774 Do not manage exchange of X selection/cutbuffer between VNC
2776 viewers and the X server at all.
2777 -noprimary
2779 Do not poll the PRIMARY selection for changes to send back to
2781 clients. (PRIMARY is still set on received changes, however).
2782 -nosetprimary
2784 Do not set the PRIMARY selection for changes received from VNC
2786 clients.
2787 -noclipboard
2789 Do not poll the CLIPBOARD selection for changes to send back to
2791 clients. (CLIPBOARD is still set on received changes, however).
2792 -nosetclipboard
2794 Do not set the CLIPBOARD selection for changes received from VNC
2796 clients.
2797 -seldir string
2799 If direction string is "send", only send the selection to view‐
2801 ers, and if it is "recv" only receive it from viewers. To work
2802 around apps setting the selection too frequently and messing up
2803 the other end. You can actually supply a comma separated list
2804 of directions, including "debug" to turn on debugging output.
2805 -cursor [mode], -nocursor
2807 Sets how the pointer cursor shape (little icon at the mouse
2809 pointer) should be handled. The "mode" string is optional and
2810 is described below. The default is to show some sort of cursor
2811 shape(s). How this is done depends on the VNC viewer and the X
2812 server. Use -nocursor to disable cursor shapes completely.
2813 Some VNC viewers support the TightVNC CursorPosUpdates and Cur‐
2815 sorShapeUpdates extensions (cuts down on network traffic by not
2816 having to send the cursor image every time the pointer is
2817 moved), in which case these extensions are used (see -nocursor‐
2818 shape and -nocursorpos below to disable). For other viewers the
2819 cursor shape is written directly to the framebuffer every time
2820 the pointer is moved or changed and gets sent along with the
2821 other framebuffer updates. In this case, there will be some lag
2822 between the vnc viewer pointer and the remote cursor position.
2823 If the X display supports retrieving the cursor shape informa‐
2825 tion from the X server, then the default is to use that mode.
2826 On Solaris this can be done with the SUN_OVL extension using
2827 -overlay (see also the -overlay_nocursor option). A similar
2828 overlay scheme is used on IRIX. Xorg (e.g. Linux) and recent
2829 Solaris Xsun servers support the XFIXES extension to retrieve
2830 the exact cursor shape from the X server. If XFIXES is present
2831 it is preferred over Overlay and is used by default (see -nox‐
2832 fixes below). This can be disabled with -nocursor, and also
2833 some values of the "mode" option below.
2834 Note that under XFIXES cursors with transparency (alpha channel)
2836 will usually not be exactly represented and one may find Overlay
2837 preferable. See also the -alphacut and -alphafrac options below
2838 as fudge factors to try to improve the situation for cursors
2839 with transparency for a given theme.
2840 The "mode" string can be used to fine-tune the displaying of
2842 cursor shapes. It can be used the following ways:
2843 "-cursor arrow" - just show the standard arrow nothing more or
2845 nothing less.
2846 "-cursor none" - same as "-nocursor"
2848 "-cursor X" - when the cursor appears to be on the root window,
2850 draw the familiar X shape. Some desktops such as GNOME cover up
2851 the root window completely, and so this will not work, try "X1",
2852 etc, to try to shift the tree depth. On high latency links or
2853 slow machines there will be a time lag between expected and the
2854 actual cursor shape.
2855 "-cursor some" - like "X" but use additional heuristics to try
2857 to guess if the window should have a windowmanager-like resizer
2858 cursor or a text input I-beam cursor. This is a complete hack,
2859 but may be useful in some situations because it provides a lit‐
2860 tle more feedback about the cursor shape.
2861 "-cursor most" - try to show as many cursors as possible. Often
2863 this will only be the same as "some" unless the display has
2864 overlay visuals or XFIXES extensions available. On Solaris and
2865 IRIX if XFIXES is not available, -overlay mode will be
2866 attempted.
2867 -cursor_drag
2869 Show cursor shape changes even when the mouse is being dragged
2871 with a mouse button down. This is useful if you want to be able
2872 to see Drag-and-Drop cursor icons, etc.
2873 -arrow n
2875 Choose an alternate "arrow" cursor from a set of some common
2877 ones. n can be 1 to 6. Default is: 1 Ignored when in XFIXES
2878 cursor-grabbing mode.
2879 -noxfixes
2881 Do not use the XFIXES extension to draw the exact cursor shape
2883 even if it is available.
2884 -alphacut n
2886 When using the XFIXES extension for the cursor shape, cursors
2888 with transparency will not usually be displayed exactly (but
2889 opaque ones will). This option sets n as a cutoff for cursors
2890 that have transparency ("alpha channel" with values ranging from
2891 0 to 255) Any cursor pixel with alpha value less than n becomes
2892 completely transparent. Otherwise the pixel is completely
2893 opaque. Default 240
2894 -alphafrac fraction
2896 With the threshold in -alphacut some cursors will become almost
2898 completely transparent because their alpha values are not high
2899 enough. For those cursors adjust the alpha threshold until
2900 fraction of the non-zero alpha channel pixels become opaque.
2901 Default 0.33
2902 -alpharemove
2904 By default, XFIXES cursors pixels with transparency have the
2906 alpha factor multiplied into the RGB color values (i.e. that
2907 corresponding to blending the cursor with a black background).
2908 Specify this option to remove the alpha factor. (useful for
2909 light colored semi-transparent cursors).
2910 -noalphablend
2912 In XFIXES mode do not send cursor alpha channel data to libvnc‐
2914 server. The default is to send it. The alphablend effect will
2915 only be visible in -nocursorshape mode or for clients with cur‐
2916 sorshapeupdates turned off. (However there is a hack for 32bpp
2917 with depth 24, it uses the extra 8 bits to store cursor trans‐
2918 parency for use with a hacked vncviewer that applies the trans‐
2919 parency locally. See the FAQ for more info).
2920 -nocursorshape
2922 Do not use the TightVNC CursorShapeUpdates extension even if
2924 clients support it. See -cursor above.
2925 -cursorpos, -nocursorpos
2927 Option -cursorpos enables sending the X cursor position back to
2929 all vnc clients that support the TightVNC CursorPosUpdates
2930 extension. Other clients will be able to see the pointer
2931 motions. Default: -cursorpos
2932 -xwarppointer, -noxwarppointer
2934 Move the pointer with XWarpPointer(3X) instead of the XTEST
2936 extension. Use this as a workaround if the pointer motion
2937 behaves incorrectly, e.g. on touchscreens or other non-standard
2938 setups.
2939 It is also sometimes needed on XINERAMA displays and is enabled
2941 by default if XINERAMA is found to be active. To prevent this,
2942 use -noxwarppointer.
2943 -buttonmap string
2945 String to remap mouse buttons. Format: IJK-LMN, this maps but‐
2947 tons I -> L, etc., e.g. -buttonmap 13-31
2948 Button presses can also be mapped to keystrokes: replace a but‐
2950 ton digit on the right of the dash with :<sym>: or
2951 :<sym1>+<sym2>: etc. for multiple keys. For example, if the
2952 viewing machine has a mouse-wheel (buttons 4 5) but the x11vnc
2953 side does not, these will do scrolls:
2954 -buttonmap 12345-123:Prior::Next:
2956 -buttonmap 12345-123:Up+Up+Up::Down+Down+Down:
2958 See <X11/keysymdef.h> header file for a list of Keysyms, or use
2960 the xev(1) program. Note: mapping of button clicks to Keysyms
2961 may not work if -modtweak or -xkb is needed for the Keysym.
2962 If you include a modifier like "Shift_L" the modifier's up/down
2964 state is toggled, e.g. to send "The" use :Shift_L+t+Shift_L+h+e:
2965 (the 1st one is shift down and the 2nd one is shift up). (note:
2966 the initial state of the modifier is ignored and not reset) To
2967 include button events use "Button1", ... etc.
2968 -buttonmap currently does not work on MacOSX console or in
2970 -rawfb mode.
2971 -nodragging
2973 Do not update the display during mouse dragging events (mouse
2975 button held down). Greatly improves response on slow setups,
2976 but you lose all visual feedback for drags, text selection, and
2977 some menu traversals. It overrides any -pointer_mode setting.
2978 -ncache n
2980 Client-side caching scheme. Framebuffer memory n (an integer)
2982 times that of the full display is allocated below the actual
2983 framebuffer to cache screen contents for rapid retrieval. So a
2984 W x H frambuffer is expanded to a W x (n+1)*H one. Use 0 to
2985 disable. Default: XXX.
2986 The n is actually optional, the default is 10.
2988 For this and the other -ncache* options below you can abbreviate
2990 "-ncache" with "-nc". Also, "-nonc" is the same as "-ncache 0"
2991 This is an experimental option, currently implemented in an awk‐
2993 ward way in that in the VNC Viewer you can see the cache con‐
2994 tents if you scroll down, etc. So you will have to set things
2995 up so you can't see that region. If this method is successful,
2996 the changes required for clients to do this less awkwardly will
2997 be investigated.
2998 Note that this mode consumes a huge amount of memory, both on
3000 the x11vnc server side and on the VNC Viewer side. If n=2 then
3001 the amount of RAM used is roughly tripled for both x11vnc and
3002 the VNC Viewer. As a rule of thumb, note that 1280x1024 at
3003 depth 24 is about 5MB of pixel data.
3004 For reasonable response when cycling through 4 to 6 large (e.g.
3006 web browser) windows a value n of 6 to 12 is recommended.
3007 (that's right: ~10X more memory...)
3008 Because of the way window backingstore and saveunders are imple‐
3010 mented, n must be even. It will be incremented by 1 if it is
3011 not.
3012 This mode also works for native MacOS X, but may not be as
3014 effective as the X version. This is due to a number of things,
3015 one is the drop-shadow compositing that leaves extra areas that
3016 need to be repaired (see -ncache_pad). Another is the window
3017 iconification animations need to be avoided (see -macicontime).
3018 It appears the that the 'Scale' animation mode gives better
3019 results than the 'Genie' one. Also, window event detection not
3020 as accurate as the X version.
3021 -ncache_cr
3023 In -ncache mode, try to do copyrect opaque window moves/drags
3025 instead of wireframes (this can induce painting errors). The
3026 wireframe will still be used when moving a window whose save-
3027 unders has not yet been set or has been invalidated.
3028 Some VNC Viewers provide better response than others with this
3030 option. On Unix, realvnc viewer gives smoother drags than
3031 tightvnc viewer. Response may also be choppy if the server side
3032 machine is too slow.
3033 Sometimes on very slow modem connections, this actually gives an
3035 improvement because no pixel data at all (not even the box ani‐
3036 mation) is sent during the drag.
3037 -ncache_no_moveraise
3039 In -ncache mode, do not assume that moving a window will cause
3041 the window manager to raise it to the top of the stack. The
3042 default is to assume it does, and so at the beginning of any
3043 wireframe, etc, window moves the window will be pushed to top in
3044 the VNC viewer.
3045 -ncache_no_dtchange
3047 In -ncache mode, do not try to guess when the desktop (viewport)
3049 changes to another one (i.e. another workarea). The default is
3050 to try to guess and when detected try to make the transistion
3051 more smoothly.
3052 -ncache_no_rootpixmap
3054 In -ncache mode, do not try to snapshot the desktop background
3056 to use in guessing or reconstructing window save-unders.
3057 -ncache_keep_anims
3059 In -ncache mode, do not try to disable window manager animations
3061 and other effects (that usually degrade ncache performance or
3062 cause painting errors). The default is to try to disable them
3063 on KDE (but not GNOME) when VNC clients are connected.
3064 For other window managers or desktops that provide animations,
3066 effects, compositing, translucency, etc. that interfere with the
3067 -ncache method you will have to disable them manually.
3068 -ncache_old_wm
3070 In -ncache mode, enable some heuristics for old style window
3072 managers such as fvwm and twm.
3073 -ncache_pad n
3075 In -ncache mode, pad each window with n pixels for the caching
3077 rectangles. This can be used to try to improve the situation
3078 with dropshadows or other compositing (e.g. MacOS X window man‐
3079 ager), although it could make things worse. The default is 0 on
3080 Unix and 24 on MacOS X.
3081 -debug_ncache
3083 Turn on debugging and profiling output under -ncache.
3085 -wireframe [str], -nowireframe
3087 Try to detect window moves or resizes when a mouse button is
3089 held down and show a wireframe instead of the full opaque win‐
3090 dow. This is based completely on heuristics and may not always
3091 work: it depends on your window manager and even how you move
3092 things around. See -pointer_mode below for discussion of the
3093 "bogging down" problem this tries to avoid. Default: -wireframe
3094 Shorter aliases: -wf [str] and -nowf
3096 The value "str" is optional and, of course, is packed with many
3098 tunable parameters for this scheme:
3099 Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 Default:
3101 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125
3102 If you leave nothing between commas: ",," the default value is
3104 used. If you don't specify enough commas, the trailing parame‐
3105 ters are set to their defaults.
3106 "shade" indicate the "color" for the wireframe, usually a
3108 greyscale: 0-255, however for 16 and 32bpp you can specify an
3109 rgb.txt X color (e.g. "dodgerblue") or a value > 255 is treated
3110 as RGB (e.g. red is 0xff0000). "linewidth" sets the width of
3111 the wireframe in pixels. "percent" indicates to not apply the
3112 wireframe scheme to windows with area less than this percent of
3113 the full screen.
3114 "T+B+L+R" indicates four integers for how close in pixels the
3116 pointer has to be from the Top, Bottom, Left, or Right edges of
3117 the window to consider wireframing. This is a speedup to
3118 quickly exclude a window from being wireframed: set them all to
3119 zero to not try the speedup (scrolling and selecting text will
3120 likely be slower).
3121 "mod" specifies if a button down event in the interior of the
3123 window with a modifier key (Alt, Shift, etc.) down should indi‐
3124 cate a wireframe opportunity. It can be "0" or "none" to skip
3125 it, "1" or "all" to apply it to any modifier, or "Shift", "Alt",
3126 "Control", "Meta", "Super", or "Hyper" to only apply for that
3127 type of modifier key.
3128 "t1+t2+t3+t4" specify four floating point times in seconds: t1
3130 is how long to wait for the pointer to move, t2 is how long to
3131 wait for the window to start moving or being resized (for some
3132 window managers this can be rather long), t3 is how long to keep
3133 a wireframe moving before repainting the window. t4 is the mini‐
3134 mum time between sending wireframe "animations". If a slow link
3135 is detected, these values may be automatically changed to some‐
3136 thing better for a slow link.
3137 -nowireframelocal
3139 By default, mouse motion and button presses of a user sitting at
3141 the LOCAL display are monitored for wireframing opportunities
3142 (so that the changes will be sent efficiently to the VNC
3143 clients). Use this option to disable this behavior.
3144 -wirecopyrect mode, -nowirecopyrect
3146 Since the -wireframe mechanism evidently tracks moving windows
3148 accurately, a speedup can be obtained by telling the VNC viewers
3149 to locally copy the translated window region. This is the VNC
3150 CopyRect encoding: the framebuffer update doesn't need to send
3151 the actual new image data.
3152 Shorter aliases: -wcr [mode] and -nowcr
3154 "mode" can be "never" (same as -nowirecopyrect) to never try the
3156 copyrect, "top" means only do it if the window was not covered
3157 by any other windows, and "always" means to translate the
3158 orginally unobscured region (this may look odd as the remaining
3159 pieces come in, but helps on a slow link). Default: "always"
3160 Note: there can be painting errors or slow response when using
3162 -scale so you may want to disable CopyRect in this case "-wire‐
3163 copyrect never" on the command line or by remote-control. Or
3164 you can also use the "-scale xxx:nocr" scale option.
3165 -debug_wireframe
3167 Turn on debugging info printout for the wireframe heuristics.
3169 "-dwf" is an alias. Specify multiple times for more output.
3170 -scrollcopyrect mode, -noscrollcopyrect
3172 Like -wirecopyrect, but use heuristics to try to guess if a win‐
3174 dow has scrolled its contents (either vertically or horizon‐
3175 tally). This requires the RECORD X extension to "snoop" on X
3176 applications (currently for certain XCopyArea and XConfigureWin‐
3177 dow X protocol requests). Examples: Hitting <Return> in a ter‐
3178 minal window when the cursor was at the bottom, the text scrolls
3179 up one line. Hitting <Down> arrow in a web browser window, the
3180 web page scrolls up a small amount. Or scrolling with a scroll‐
3181 bar or mouse wheel.
3182 Shorter aliases: -scr [mode] and -noscr
3184 This scheme will not always detect scrolls, but when it does
3186 there is a nice speedup from using the VNC CopyRect encoding
3187 (see -wirecopyrect). The speedup is both in reduced network
3188 traffic and reduced X framebuffer polling/copying. On the other
3189 hand, it may induce undesired transients (e.g. a terminal cursor
3190 being scrolled up when it should not be) or other painting
3191 errors (window tearing, bunching-up, etc). These are automati‐
3192 cally repaired in a short period of time. If this is unaccept‐
3193 able disable the feature with -noscrollcopyrect.
3194 Screen clearing kludges: for testing at least, there are some
3196 "magic key sequences" (must be done in less than 1 second) to
3197 aid repairing painting errors that may be seen when using this
3198 mode:
3199 3 Alt_L's in a row: resend whole screen, 4 Alt_L's in a row:
3201 reread and resend whole screen, 3 Super_L's in a row: mark whole
3202 screen for polling, 4 Super_L's in a row: reset RECORD context,
3203 5 Super_L's in a row: try to push a black screen
3204 note: Alt_L is the Left "Alt" key (a single key) Super_L is the
3206 Left "Super" key (Windows flag). Both of these are modifier
3207 keys, and so should not generate characters when pressed by
3208 themselves. Also, your VNC viewer may have its own refresh hot-
3209 key or button.
3210 "mode" can be "never" (same as -noscrollcopyrect) to never try
3212 the copyrect, "keys" means to try it in response to keystrokes
3213 only, "mouse" means to try it in response to mouse events only,
3214 "always" means to do both. Default: "always"
3215 Note: there can be painting errors or slow response when using
3217 -scale so you may want to disable CopyRect in this case
3218 "-scrollcopyrect never" on the command line or by remote-con‐
3219 trol. Or you can also use the "-scale xxx:nocr" scale option.
3220 -scr_area n
3222 Set the minimum area in pixels for a rectangle to be considered
3224 for the -scrollcopyrect detection scheme. This is to avoid
3225 wasting the effort on small rectangles that would be quickly
3226 updated the normal way. E.g. suppose an app updated the posi‐
3227 tion of its skinny scrollbar first and then shifted the large
3228 panel it controlled. We want to be sure to skip the small
3229 scrollbar and get the large panel. Default: 60000
3230 -scr_skip list
3232 Skip scroll detection for applications matching the comma sepa‐
3234 rated list of strings in list. Some applications implement
3235 their scrolling in strange ways where the XCopyArea, etc, also
3236 applies to invisible portions of the window: if we CopyRect
3237 those areas it looks awful during the scroll and there may be
3238 painting errors left after the scroll. Soffice.bin is the worst
3239 known offender.
3240 Use "##" to denote the start of the application class (e.g.
3242 "##XTerm") and "++" to denote the start of the application
3243 instance name (e.g. "++xterm"). The string your list is matched
3244 against is of the form "^^WM_NAME##Class++Instance<same-for-any-
3245 subwindows>" The "xlsclients -la" command will provide this
3246 info.
3247 If a pattern is prefixed with "KEY:" it only applies to Key‐
3249 stroke generated scrolls (e.g. Up arrow). If it is prefixed
3250 with "MOUSE:" it only applies to Mouse induced scrolls (e.g.
3251 dragging on a scrollbar). Default: ##Soffice.bin,##StarOf‐
3252 fice,##OpenOffice
3253 -scr_inc list
3255 Opposite of -scr_skip: this list is consulted first and if there
3257 is a match the window will be monitored via RECORD for scrolls
3258 irrespective of -scr_skip. Use -scr_skip '*' to skip anything
3259 that does not match your -scr_inc. Use -scr_inc '*' to include
3260 everything.
3261 -scr_keys list
3263 For keystroke scroll detection, only apply the RECORD heuristics
3265 to the comma separated list of keysyms in list. You may find
3266 the RECORD overhead for every one of your keystrokes disrupts
3267 typing too much, but you don't want to turn it off completely
3268 with "-scr mouse" and -scr_parms does not work or is too confus‐
3269 ing.
3270 The listed keysyms can be numeric or the keysym names in the
3272 <X11/keysymdef.h> header file or from the xev(1) program. Exam‐
3273 ple: "-scr_keys Up,Down,Return". One probably wants to have
3274 application specific lists (e.g. for terminals, etc) but that is
3275 too icky to think about for now...
3276 If list begins with the "-" character the list is taken as an
3278 exclude list: all keysyms except those list will be considered.
3279 The special string "builtin" expands to an internal list of
3280 keysyms that are likely to cause scrolls. BTW, by default modi‐
3281 fier keys, Shift_L, Control_R, etc, are skipped since they
3282 almost never induce scrolling by themselves.
3283 -scr_term list
3285 Yet another cosmetic kludge. Apply shell/terminal heuristics to
3287 applications matching comma separated list (same as for
3288 -scr_skip/-scr_inc). For example an annoying transient under
3289 scroll detection is if you hit Enter in a terminal shell with
3290 full text window, the solid text cursor block will be scrolled
3291 up. So for a short time there are two (or more) block cursors
3292 on the screen. There are similar scenarios, (e.g. an output
3293 line is duplicated).
3294 These transients are induced by the approximation of scroll
3296 detection (e.g. it detects the scroll, but not the fact that the
3297 block cursor was cleared just before the scroll). In nearly all
3298 cases these transient errors are repaired when the true X frame‐
3299 buffer is consulted by the normal polling. But they are dis‐
3300 tracting, so what this option provides is extra "padding" near
3301 the bottom of the terminal window: a few extra lines near the
3302 bottom will not be scrolled, but rather updated from the actual
3303 X framebuffer. This usually reduces the annoying artifacts.
3304 Use "none" to disable. Default: "term"
3305 -scr_keyrepeat lo-hi
3307 If a key is held down (or otherwise repeats rapidly) and this
3309 induces a rapid sequence of scrolls (e.g. holding down an Arrow
3310 key) the "scrollcopyrect" detection and overhead may not be able
3311 to keep up. A time per single scroll estimate is performed and
3312 if that estimate predicts a sustainable scrollrate of keys per
3313 second between "lo" and "hi" then repeated keys will be DIS‐
3314 CARDED to maintain the scrollrate. For example your key autore‐
3315 peat may be 25 keys/sec, but for a large window or slow link
3316 only 8 scrolls per second can be sustained, then roughly 2 out
3317 of every 3 repeated keys will be discarded during this period.
3318 Default: "4-20"
3319 -scr_parms string
3321 Set various parameters for the scrollcopyrect mode. The format
3323 is similar to that for -wireframe and packed with lots of param‐
3324 eters:
3325 Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 Default:
3327 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0
3328 If you leave nothing between commas: ",," the default value is
3330 used. If you don't specify enough commas, the trailing parame‐
3331 ters are set to their defaults.
3332 "T+B+L+R" indicates four integers for how close in pixels the
3334 pointer has to be from the Top, Bottom, Left, or Right edges of
3335 the window to consider scrollcopyrect. If -wireframe overlaps
3336 it takes precedence. This is a speedup to quickly exclude a
3337 window from being watched for scrollcopyrect: set them all to
3338 zero to not try the speedup (things like selecting text will
3339 likely be slower).
3340 "t1+t2+t3" specify three floating point times in seconds that
3342 apply to scrollcopyrect detection with *Keystroke* input: t1 is
3343 how long to wait after a key is pressed for the first scroll, t2
3344 is how long to keep looking after a Keystroke scroll for more
3345 scrolls. t3 is how frequently to try to update surrounding
3346 scrollbars outside of the scrolling area (0.0 to disable)
3347 "s1+s2+s3+s4+s5" specify five floating point times in seconds
3349 that apply to scrollcopyrect detection with *Mouse* input: s1 is
3350 how long to wait after a mouse button is pressed for the first
3351 scroll, s2 is how long to keep waiting for additional scrolls
3352 after the first Mouse scroll was detected. s3 is how frequently
3353 to try to update surrounding scrollbars outside of the scrolling
3354 area (0.0 to disable). s4 is how long to buffer pointer motion
3355 (to try to get fewer, bigger mouse scrolls). s5 is the maximum
3356 time to spend just updating the scroll window without updating
3357 the rest of the screen.
3358 -fixscreen string
3360 Periodically "repair" the screen based on settings in string.
3362 Hopefully you won't need this option, it is intended for cases
3363 when the -scrollcopyrect or -wirecopyrect features leave too
3364 many painting errors, but it can be used for any scenario. This
3365 option periodically performs costly operations and so interac‐
3366 tive response may be reduced when it is on. You can use 3
3367 Alt_L's (the Left "Alt" key) taps in a row (as described under
3368 -scrollcopyrect) instead to manually request a screen repaint
3369 when it is needed.
3370 string is a comma separated list of one or more of the follow‐
3372 ing: "V=t", "C=t", "X=t", and "8=t". In these "t" stands for a
3373 time in seconds (it is a floating point even though one should
3374 usually use values > 2 to avoid wasting resources). V sets how
3375 frequently the entire screen should be sent to viewers (it is
3376 like the 3 Alt_L's). C sets how long to wait after a CopyRect
3377 to repaint the full screen. X sets how frequently to reread the
3378 full X11 framebuffer from the X server and push it out to con‐
3379 nected viewers. Use of X should be rare, please report a bug if
3380 you find you need it. 8= applies only for -8to24 mode: it sets
3381 how often the non-default visual regions of the screen (e.g.
3382 8bpp windows) are refreshed. Examples: -fixscreen V=10
3383 -fixscreen C=10
3384 -debug_scroll
3386 Turn on debugging info printout for the scroll heuristics.
3388 "-ds" is an alias. Specify it multiple times for more output.
3389 -noxrecord
3391 Disable any use of the RECORD extension. This is currently used
3393 by the -scrollcopyrect scheme and to monitor X server grabs.
3394 -grab_buster, -nograb_buster
3396 Some of the use of the RECORD extension can leave a tiny window
3398 for XGrabServer deadlock. This is only if the whole-server
3399 grabbing application expects mouse or keyboard input before
3400 releasing the grab. It is usually a window manager that does
3401 this. x11vnc takes care to avoid the the problem, but if caught
3402 x11vnc will freeze. Without -grab_buster, the only solution is
3403 to go the physical display and give it some input to satisfy the
3404 grabbing app. Or manually kill and restart the window manager
3405 if that is feasible. With -grab_buster, x11vnc will fork a
3406 helper thread and if x11vnc appears to be stuck in a grab after
3407 a period of time (20-30 sec) then it will inject some user
3408 input: button clicks, Escape, mouse motion, etc to try to break
3409 the grab. If you experience a lot of grab deadlock, please
3410 report a bug.
3411 -debug_grabs
3413 Turn on debugging info printout with respect to XGrabServer()
3415 deadlock for -scrollcopyrect__mode_.
3416 -debug_sel
3418 Turn on debugging info printout with respect to PRIMARY, CLIP‐
3420 BOARD, and CUTBUFFER0 selections.
3421 -pointer_mode n
3423 Various pointer motion update schemes. "-pm" is an alias. The
3425 problem is pointer motion can cause rapid changes on the screen:
3426 consider the rapid changes when you drag a large window around
3427 opaquely. Neither x11vnc's screen polling and vnc compression
3428 routines nor the bandwidth to the vncviewers can keep up these
3429 rapid screen changes: everything will bog down when dragging or
3430 scrolling. So a scheme has to be used to "eat" much of that
3431 pointer input before re-polling the screen and sending out
3432 framebuffer updates. The mode number n can be 0 to 4 and selects
3433 one of the schemes desribed below.
3434 Note that the -wireframe and -scrollcopyrect__mode_s complement
3436 -pointer_mode by detecting (and improving) certain periods of
3437 "rapid screen change".
3438 n=0: does the same as -nodragging. (all screen polling is sus‐
3440 pended if a mouse button is pressed.)
3441 n=1: was the original scheme used to about Jan 2004: it basi‐
3443 cally just skips -input_skip keyboard or pointer events before
3444 repolling the screen.
3445 n=2 is an improved scheme: by watching the current rate of input
3447 events it tries to detect if it should try to "eat" additional
3448 pointer events before continuing.
3449 n=3 is basically a dynamic -nodragging mode: it detects when the
3451 mouse motion has paused and then refreshes the display.
3452 n=4 attempts to measures network rates and latency, the video
3454 card read rate, and how many tiles have been changed on the
3455 screen. From this, it aggressively tries to push screen
3456 "frames" when it decides it has enough resources to do so. NOT
3457 FINISHED.
3458 The default n is 2. Note that modes 2, 3, 4 will skip
3460 -input_skip keyboard events (but it will not count pointer
3461 events). Also note that these modes are not available in
3462 -threads mode which has its own pointer event handling mecha‐
3463 nism.
3464 To try out the different pointer modes to see which one gives
3466 the best response for your usage, it is convenient to use the
3467 remote control function, for example "x11vnc -R pm:4" or the
3468 tcl/tk gui (Tuning -> pointer_mode -> n).
3469 -input_skip n
3471 For the pointer handling when non-threaded: try to read n user
3473 input events before scanning display. n < 0 means to act as
3474 though there is always user input. Default: 10
3475 -allinput
3477 Have x11vnc read and process all available client input before
3479 proceeding.
3480 -speeds rd,bw,lat
3482 x11vnc tries to estimate some speed parameters that are used to
3484 optimize scheduling (e.g. -pointer_mode 4, -wireframe, -scroll‐
3485 copyrect) and other things. Use the -speeds option to set these
3486 manually. The triple rd,bw,lat corresponds to video h/w read
3487 rate in MB/sec, network bandwidth to clients in KB/sec, and net‐
3488 work latency to clients in milliseconds, respectively. If a
3489 value is left blank, e.g. "-speeds ,100,15", then the internal
3490 scheme is used to estimate the empty value(s).
3491 Typical PC video cards have read rates of 5-10 MB/sec. If the
3493 framebuffer is in main memory instead of video h/w (e.g. SunRay,
3494 shadowfb, dummy driver, Xvfb), the read rate may be much faster.
3495 "x11perf -getimage500" can be used to get a lower bound (remem‐
3496 ber to factor in the bytes per pixel). It is up to you to esti‐
3497 mate the network bandwith and latency to clients. For the
3498 latency the ping(1) command can be used.
3499 For convenience there are some aliases provided, e.g. "-speeds
3501 modem". The aliases are: "modem" for 6,4,200; "dsl" for
3502 6,100,50; and "lan" for 6,5000,1
3503 -wmdt string
3505 For some features, e.g. -wireframe and -scrollcopyrect, x11vnc
3507 has to work around issues for certain window managers or desk‐
3508 tops (currently kde and xfce). By default it tries to guess
3509 which one, but it can guess incorrectly. Use this option to
3510 indicate which wm/dt. string can be "gnome", "kde", "cde",
3511 "xfce", or "root" (classic X wm). Anything else is interpreted
3512 as "root".
3513 -debug_pointer
3515 Print debugging output for every pointer event.
3517 -debug_keyboard
3519 Print debugging output for every keyboard event.
3521 Same as -dp and -dk, respectively. Use multiple times for more output.
3523 -defer time
3525 Time in ms to wait for updates before sending to client (defer‐
3527 UpdateTime) Default: 20
3528 -wait time
3530 Time in ms to pause between screen polls. Used to cut down on
3532 load. Default: 20
3533 -wait_ui factor
3535 Factor by which to cut the -wait time if there has been recent
3537 user input (pointer or keyboard). Improves response, but
3538 increases the load whenever you are moving the mouse or typing.
3539 Default: 2.00
3540 -setdefer n
3542 When the -wait_ui mechanism cuts down the wait time ms, set the
3544 defer time to the same ms value. n=1 to enable, 0 to disable,
3545 and -1 to set defer to 0 (no delay). Similarly, 2 and -2 indi‐
3546 cate 'urgent_update' mode should be used to push the updates
3547 even sooner. Default: 1
3548 -nowait_bog
3550 Do not detect if the screen polling is "bogging down" and sleep
3552 more. Some activities with no user input can slow things down a
3553 lot: consider a large terminal window with a long build running
3554 in it continuously streaming text output. By default x11vnc
3555 will try to detect this (3 screen polls in a row each longer
3556 than 0.25 sec with no user input), and sleep up to 1.5 secs to
3557 let things "catch up". Use this option to disable that detec‐
3558 tion.
3559 -slow_fb time
3561 Floating point time in seconds to delay all screen polling. For
3563 special purpose usage where a low frame rate is acceptable and
3564 desirable, but you want the user input processed at the normal
3565 rate so you cannot use -wait.
3566 -xrefresh time
3568 Floating point time in seconds to indicate how often to do the
3570 equivalent of xrefresh(1) to force all windows (in the viewable
3571 area if -id, -sid, or -clip is used) to repaint themselves. Use
3572 this only if applications misbehave by not repainting themselves
3573 properly. See also -noxdamage.
3574 -nap, -nonap
3576 Monitor activity and if it is low take longer naps between
3578 screen polls to really cut down load when idle. Default: take
3579 naps
3580 -sb time
3582 Time in seconds after NO activity (e.g. screen blank) to really
3584 throttle down the screen polls (i.e. sleep for about 1.5 secs).
3585 Use 0 to disable. Default: 20
3586 -readtimeout n
3588 Set libvncserver rfbMaxClientWait to n seconds. On slow links
3590 that take a long time to paint the first screen libvncserver may
3591 hit the timeout and drop the connection. Default: 60 seconds.
3592 -ping n
3594 Send a 1x1 framebuffer update to all clients every n seconds
3596 (e.g. to try to keep a network connection alive)
3597 -nofbpm, -fbpm
3599 If the system supports the FBPM (Frame Buffer Power Management)
3601 extension (i.e. some Sun systems), then prevent the video h/w
3602 from going into a reduced power state when VNC clients are con‐
3603 nected.
3604 FBPM capable video h/w save energy when the workstation is idle
3606 by going into low power states (similar to DPMS for monitors).
3607 This interferes with x11vnc's polling of the framebuffer data.
3608 "-nofbpm" means prevent FBPM low power states whenever VNC
3610 clients are connected, while "-fbpm" means to not monitor the
3611 FBPM state at all. See the xset(1) manpage for details. -nof‐
3612 bpm is basically the same as running "xset fbpm force on" peri‐
3613 odically. Default: -fbpm
3614 -nodpms, -dpms
3616 If the system supports the DPMS (Display Power Management Sig‐
3618 naling) extension, then prevent the monitor from going into a
3619 reduced power state when VNC clients are connected.
3620 DPMS reduced power monitor states are a good thing and you nor‐
3622 mally want the power down to take place (usually x11vnc has no
3623 problem exporting the display in this state). You probably only
3624 want to use "-nodpms" to work around problems with Screen Savers
3625 kicking on in DPMS low power states. There is known problem
3626 with kdesktop_lock on KDE where the screen saver keeps kicking
3627 in every time user input stops for a second or two. Specifying
3628 "-nodpms" works around it.
3629 "-nodpms" means prevent DPMS low power states whenever VNC
3631 clients are connected, while "-dpms" means to not monitor the
3632 DPMS state at all. See the xset(1) manpage for details.
3633 -nodpms is basically the same as running "xset dpms force on"
3634 periodically. Default: -dpms
3635 -forcedpms
3637 If the system supports the DPMS (Display Power Management Sig‐
3639 naling) extension, then try to keep the monitor in a powered off
3640 state. This is to prevent nosey people at the physical display
3641 from viewing what is on the screen. Be sure to lock the screen
3642 before disconnecting.
3643 This method is far from bullet proof, e.g. suppose someone
3645 attaches a non-DPMS monitor, or loads the machine so that there
3646 is a gap of time before x11vnc restores the powered off state?
3647 On many machines if he floods it with keyboard and mouse input
3648 he can see flashes of what is on the screen before the DPMS off
3649 state is reestablished. For this to work securely there would
3650 need to be support in the X server to do this exactly rather
3651 than approximately with DPMS.
3652 -clientdpms
3654 As -forcedpms but only when VNC clients are connected.
3656 -noserverdpms
3658 The UltraVNC ServerInput extension is supported. This allows
3660 the VNC viewer to click a button that will cause the server
3661 (x11vnc) to try to disable keyboard and mouse input at the phys‐
3662 ical display and put the monitor in dpms powered off state. Use
3663 this option to skip powering off the monitor.
3664 -noultraext
3666 Disable the following UltraVNC extensions: SingleWindow and
3668 ServerInput. The others managed by libvncserver (textchat, 1/n
3669 scaling, rfbEncodingUltra) are not.
3670 -chatwindow
3672 Place a local UltraVNC chat window on the X11 display that
3674 x11vnc is polling. That way the person on the VNC viewer-side
3675 can chat with the person at the physical X11 console. (e.g.
3676 helpdesk w/o telephone)
3677 For this to work the SSVNC package (version 1.0.21 or later)
3679 MUST BE installed on the system where x11vnc runs and the
3680 'ssvnc' command must be available in $PATH. The ssvncviewer is
3681 used as a chat window helper. See http://www.karl‐
3682 runge.com/x11vnc/ssvnc.html
3683 This option implies '-rfbversion 3.6' so as to trick UltraVNC
3685 viewers, otherwise they assume chat is not available. To spec‐
3686 ify a different rfbversion, place it after the -chatwindow
3687 option on the cmdline.
3688 See also the remote control 'chaton' and 'chatoff' actions.
3690 These can also be set from the tkx11vnc GUI.
3691 -noxdamage
3693 Do not use the X DAMAGE extension to detect framebuffer changes
3695 even if it is available. Use -xdamage if your default is to
3696 have it off.
3697 x11vnc's use of the DAMAGE extension: 1) significantly reduces
3699 the load when the screen is not changing much, and 2) detects
3700 changed areas (small ones by default) more quickly.
3701 Currently the DAMAGE extension is overly conservative and often
3703 reports large areas (e.g. a whole terminal or browser window) as
3704 damaged even though the actual changed region is much smaller
3705 (sometimes just a few pixels). So heuristics were introduced to
3706 skip large areas and use the damage rectangles only as "hints"
3707 for the traditional scanline polling. The following tuning
3708 parameters are introduced to adjust this behavior:
3709 -xd_area A
3711 Set the largest DAMAGE rectangle area A (in pixels: width *
3713 height) to trust as truly damaged: the rectangle will be copied
3714 from the framebuffer (slow) no matter what. Set to zero to
3715 trust *all* rectangles. Default: 20000
3716 -xd_mem f
3718 Set how long DAMAGE rectangles should be "remembered", f is a
3720 floating point number and is in units of the scanline repeat
3721 cycle time (32 iterations). The default (1.0) should give no
3722 painting problems. Increase it if there are problems or decrease
3723 it to live on the edge (perhaps useful on a slow machine).
3724 -sigpipe string
3726 Broken pipe (SIGPIPE) handling. string can be "ignore" or
3728 "exit". For "ignore" libvncserver will handle the abrupt loss
3729 of a client and continue, for "exit" x11vnc will cleanup and
3730 exit at the 1st broken connection.
3731 This option is not really needed since libvncserver is doing the
3733 correct thing now for quite some time. However, for convenience
3734 you can use it to ignore other signals, e.g. "-sigpipe
3735 ignore:HUP,INT,TERM" in case that would be useful for some sort
3736 of application. You can also put "exit:.." in the list to have
3737 x11vnc cleanup on the listed signals. "-sig" is an alias for
3738 this option if you don't like the 'pipe'. Example: -sig
3739 ignore:INT,TERM,exit:USR1
3740 -threads, -nothreads
3742 Whether or not to use the threaded libvncserver algorithm
3744 [rfbRunEventLoop] if libpthread is available. In this mode new
3745 threads (one for input and one for output) are created to handle
3746 each new client. Default: -nothreads.
3747 NOTE: The -threads mode may be disabled due to its unstable
3749 behavior. If it is disabled, a warning is printed out. Stabil‐
3750 ity has been improved in version 0.9.8 and so the feature has
3751 been re-enabled.
3752 Multiple clients in threaded mode should be stable for the ZRLE
3754 encoding on all platforms. The Tight and Zlib encodings are
3755 currently only stable on Linux for multiple clients. Compile
3756 with -DTLS=__thread if your OS and compiler and linker support
3757 it.
3758 Multiple clients in threaded mode could yield better performance
3760 for 'class-room' broadcasting usage. See also the -reflect
3761 option.
3762 -fs f
3764 If the fraction of changed tiles in a poll is greater than f,
3766 the whole screen is updated. Default: 0.75
3767 -gaps n
3769 Heuristic to fill in gaps in rows or cols of n or less tiles.
3771 Used to improve text paging. Default: 4
3772 -grow n
3774 Heuristic to grow islands of changed tiles n or wider by check‐
3776 ing the tile near the boundary. Default: 3
3777 -fuzz n
3779 Tolerance in pixels to mark a tiles edges as changed. Default:
3781 2
3782 -debug_tiles
3784 Print debugging output for tiles, fb updates, etc.
3786 -snapfb
3788 Instead of polling the X display framebuffer (fb) for changes,
3790 periodically copy all of X display fb into main memory and exam‐
3791 ine that copy for changes. (This setting also applies for non-X
3792 -rawfb modes). Under some circumstances this will improve
3793 interactive response, or at least make things look smoother, but
3794 in others (most!) it will make the response worse. If the video
3795 h/w fb is such that reading small tiles is very slow this mode
3796 could help. To keep the "framerate" up the screen size x bpp
3797 cannot be too large. Note that this mode is very wasteful of
3798 memory I/O resources (it makes full screen copies even if noth‐
3799 ing changes). It may be of use in video capture-like applica‐
3800 tions, webcams, or where window tearing is a problem.
3801 -rawfb string
3803 Instead of polling X, poll the memory object specified in
3805 string.
3806 For file polling, to memory map mmap(2) a file use:
3808 "map:/path/to/a/file@WxHxB", with framebuffer Width, Height, and
3809 Bits per pixel. "mmap:..." is the same.
3810 If there is trouble with mmap, use "file:/..." for slower
3812 lseek(2) based reading.
3813 Use "snap:..." to imply -snapfb mode and the "file:" access
3815 (this is for unseekable devices that only provide the fb all at
3816 once, e.g. a video camera provides the whole frame).
3817 For shared memory segments string is of the form: "shm:N@WxHxB"
3819 which specifies a shmid N and with WxHxB as above. See shmat(1)
3820 and ipcs(1)
3821 If you do not supply a type "map" is assumed if the file exists
3823 (see the next paragraphs for some exceptions to this.)
3824 If string is "setup:cmd", then the command "cmd" is run and the
3826 first line from it is read and used as string. This allows ini‐
3827 tializing the device, determining WxHxB, etc. These are often
3828 done as root so take care.
3829 If the string begins with "video", see the VIDEO4LINUX discus‐
3831 sion below where the device may be queried for (and possibly
3832 set) the framebuffer parameters.
3833 If the string begins with "console", "/dev/fb", "fb", or "vt",
3835 see the LINUX CONSOLE discussion below where the framebuffer
3836 device is opened and keystrokes (and possibly mouse events) are
3837 inserted into the console.
3838 If the string begins with "vnc", see the VNC HOST discussion
3840 below where the framebuffer is taken as that of another remote
3841 VNC server.
3842 Optional suffixes are ":R/G/B" and "+O" to specify red, green,
3844 and blue masks (in hex) and an offset into the memory object.
3845 If the masks are not provided x11vnc guesses them based on the
3846 bpp (if the colors look wrong, you need to provide the masks.)
3847 Another optional suffix is the Bytes Per Line which in some
3849 cases is not WxB/8. Specify it as WxHxB-BPL e.g.
3850 800x600x16-2048. This could be a normal width 1024 at 16bpp fb,
3851 but only width 800 shows up.
3852 So the full format is: mode:file@WxHxB:R/G/B+O-BPL
3854 Examples:
3856 -rawfb shm:210337933@800x600x32:ff/ff00/ff0000
3858 -rawfb map:/dev/fb0@1024x768x32
3860 -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232
3862 -rawfb file:/tmp/my.pnm@250x200x24+37
3864 -rawfb file:/dev/urandom@128x128x8 -rawfb
3866 snap:/dev/video0@320x240x24 -24to32 -rawfb video0 -rawfb video
3867 -pipeinput VID -rawfb console -rawfb vt2 -rawfb vnc:somehost:0
3868 (see ipcs(1) and fbset(1) for the first two examples)
3870 In general all user input is discarded by default (see the
3872 -pipeinput option for how to use a helper program to insert).
3873 Most of the X11 (screen, keyboard, mouse) options do not make
3874 sense and many will cause this mode to crash, so please think
3875 twice before setting or changing them in a running x11vnc.
3876 If you DO NOT want x11vnc to close the X DISPLAY in rawfb mode,
3878 prepend a "+" e.g. +file:/dev/fb0... Keeping the display open
3879 enables the default remote-control channel, which could be use‐
3880 ful. Alternatively, if you specify -noviewonly, then the mouse
3881 and keyboard input are STILL sent to the X display, this usage
3882 should be very rare, i.e. doing something strange with /dev/fb0.
3883 If the device is not "seekable" (e.g. webcam) try reading it all
3885 at once in full snaps via the "snap:" mode (note: this is a
3886 resource hog). If you are using file: or map: AND the device
3887 needs to be reopened for *every* snapfb snapshot, set the envi‐
3888 ronment variable: SNAPFB_RAWFB_RESET=1 as well.
3889 If you want x11vnc to dynamically transform a 24bpp rawfb to
3891 32bpp (note that this will be slower) also supply the -24to32
3892 option. This would be useful for, say, a video camera that
3893 delivers the pixel data as 24bpp packed RGB. This is the
3894 default under "video" mode if the bpp is 24.
3895 Normally the bits per pixel, B, is 8, 16, or 32 (or rarely 24),
3897 however there is also some support for B < 8 (e.g. old graphics
3898 displays 4 bpp or 1 bpp). In this case you certainly must sup‐
3899 ply the masks as well: WxHxB:R/G/B. The pixels will be padded
3900 out to 8 bpp using depth 8 truecolor. The scheme currently does
3901 not work with snap fb (ask if interested.) B=1 monochrome exam‐
3902 ple: file:/dev/urandom@128x128x1:1/1/1 Some other like this are
3903 128x128x2:3/3/3 128x128x4:7/7/7
3904 For B < 8 framebuffers you can also set the env. var RAWFB_CGA=1
3906 to try a CGA mapping for B=4 (e.g. linux vga16fb driver.) Note
3907 with low bpp and/or resolution VGA and VGA16 modes on the Linux
3908 console one's attempt to export them via x11vnc can often be
3909 thwarted due to special color palettes, pixel packings, and even
3910 video painting buffering. OTOH, often experimenting with the
3911 RGB masks can yield something recognizable.
3912 VIDEO4LINUX: on Linux some attempt is made to handle video
3914 devices (webcams or TV tuners) automatically. The idea is the
3915 WxHxB will be extracted from the device itself. So if you do
3916 not supply "@WxHxB... parameters x11vnc will try to determine
3917 them. It first tries the v4l API if that support has been com‐
3918 piled in. Otherwise it will run the v4l- info(1) external pro‐
3919 gram if it is available.
3920 The simplest examples are "-rawfb video" and "-rawfb video1"
3922 which imply the device file /dev/video and /dev/video1, respec‐
3923 tively. You can also supply the /dev if you like, e.g. "-rawfb
3924 /dev/video0"
3925 Since the video capture device framebuffer usually changes con‐
3927 tinuously (e.g. brightness fluctuations), you may want to use
3928 the -wait, -slow_fb, or -defer options to lower the "framerate"
3929 to cut down on network VNC traffic.
3930 A more sophisticated video device scheme allows initializing the
3932 device's settings using:
3933 -rawfb video:<settings>
3935 The prefix could also be, as above, e.g. "video1:" to specify
3937 the device file. The v4l API must be available for this to
3938 work. Otherwise, you will need to try to initialize the device
3939 with an external program, e.g. xawtv, spcaview, and hope they
3940 persist when x11vnc re-opens the device.
3941 <settings> is a comma separated list of key=value pairs. The
3943 device's brightness, color, contrast, and hue can be set to per‐
3944 centages, e.g. br=80,co=50,cn=44,hu=60.
3945 The device filename can be set too if needed (if it does not
3947 start with "video"), e.g. fn=/dev/qcam.
3948 The width, height and bpp of the framebuffer can be set via,
3950 e.g., w=160,h=120,bpp=16.
3951 Related to the bpp above, the pixel format can be set via the
3953 fmt=XXX, where XXX can be one of: GREY, HI240, RGB555, RGB565,
3954 RGB24, and RGB32 (with bpp 8, 8, 16, 16, 24, and 32 respec‐
3955 tively). See http://www.linuxtv.org for more info (V4L api).
3956 For TV/rf tuner cards one can set the tuning mode via tun=XXX
3958 where XXX can be one of PAL, NTSC, SECAM, or AUTO.
3959 One can switch the input channel by the inp=XXX setting, where
3961 XXX is the name of the input channel (Television, Composite1, S-
3962 Video, etc). Use the name that is in the information about the
3963 device that is printed at startup.
3964 For input channels with tuners (e.g. Television) one can change
3966 which station is selected by the sta=XXX setting. XXX is the
3967 station number. Currently only the ntsc-cable-us (US cable)
3968 channels are built into x11vnc. See the -freqtab option below
3969 to supply one from xawtv. If XXX is greater than 500, then it is
3970 interpreted as a raw frequency in KHz.
3971 Example:
3973 -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47
3975 one might need to add inp=Television too for the input channel
3977 to be TV if the card doesn't come up by default in that one.
3978 Note that not all video capture devices will support all of the
3980 above settings.
3981 See the -pipeinput VID option below for a way to control the
3983 settings through the VNC Viewer via keystrokes. As a shortcut,
3984 if the string begins "Video.." instead of "video.." then
3985 -pipeinput VID is implied.
3986 As above, if you specify a "@WxHxB..." after the <settings>
3988 string they are used verbatim: the device is not queried for the
3989 current values. Otherwise the device will be queried.
3990 LINUX CONSOLE: The following describes some ways to view and
3992 possibly interact with the Linux text/graphics console (i.e. not
3993 X11 XFree86/Xorg)
3994 Note: If the libvncserver LinuxVNC program is on your system you
3996 may want to use that instead of the following method because it
3997 will be faster and more accurate for the Linux text console and
3998 includes mouse support. There is, however, the basic LinuxVNC
3999 functionality in x11vnc if you replace "console" with "vt" in
4000 the examples below.
4001 If the rawfb string begins with "console" the framebuffer device
4003 /dev/fb0 is opened and /dev/tty0 is opened too. The latter is
4004 used to inject keystrokes (not all are supported, but the basic
4005 ones are). You will need to be root to inject keystrokes, but
4006 not necessarily to open /dev/fb0. /dev/tty0 refers to the
4007 active VT, to indicate one explicitly, use, e.g., "console2" for
4008 /dev/tty2, etc. by indicating the specific VT number.
4009 For the Linux framebuffer device, /dev/fb0, (fb1, etc) to be
4011 enabled the appropriate kernel drivers must be loaded. E.g.
4012 vesafb or vga16fb and also by setting the boot parameter
4013 vga=0x301 (or 0x314, 0x317, etc.) (The vga=... method is the
4014 preferred way; set your machines up that way.) Otherwise there
4015 will be a ´No such device' error. You can also load a Linux
4016 framebuffer driver specific to your make of video card for more
4017 functionality. Once the machine is booted one can often 'mod‐
4018 probe' the fb driver as root to obtain a framebuffer device.
4019 If you cannot get /dev/fb0 working on Linux, try using the Lin‐
4021 uxVNC emulation mode by "-rawfb vtN" where N = 1, ... 6 is the
4022 Linux Virtual Terminal (aka virtual console) you wish to view,
4023 e.g. "-rawfb vt2". Unlike /dev/fb mode, it need not be the
4024 active Virtual Terminal. Note that this mode can only show text
4025 and not graphics. x11vnc polls the text in /dev/vcsaN
4026 Set the env. var. RAWFB_VCSA_BW=1 to disable colors in the "vtN"
4028 mode (i.e. black and white only.) If you do not prefer the
4029 default 16bpp set RAWFB_VCSA_BPP to 8 or 32. If you need to
4030 tweak the rawfb parameters by using the 'console_guess' string
4031 printed at startup, be sure to indicate the snap: method.
4032 uinput: If the Linux version appears to be 2.6 or later and the
4034 "uinput" module appears to be present (modprobe uinput), then
4035 the uinput method will be used instead of /dev/ttyN. uinput
4036 allows insertion of BOTH keystrokes and mouse input and so it
4037 preferred when accessing graphical (e.g. QT-embedded) linux con‐
4038 sole apps. See -pipeinput UINPUT below for more information on
4039 this mode; you will have to use -pipeinput if you want to tweak
4040 any UINPUT parameters. You may also want to also use the
4041 -nodragging and -cursor none options. Use "console0", etc or
4042 -pipeinput CONSOLE to force the /dev/ttyN method.
4043 Note you can change the Linux VT remotely using the chvt(1) com‐
4045 mand to make the one you want be the active one (e.g. 'chvt 3').
4046 Sometimes switching out and back corrects the framebuffer's
4047 graphics state. For the "-rawfb vtN" mode there is no need to
4048 switch the VT's.
4049 To skip input injecting entirely use "consolex" or "vtx".
4051 The string "/dev/fb0" (1, etc.) can be used instead of "con‐
4053 sole". This can be used to specify a different framebuffer
4054 device, e.g. /dev/fb1. As a shortcut the "/dev/" can be
4055 dropped. If the name is something nonstandard, use "con‐
4056 sole:/dev/foofb"
4057 If you do not want x11vnc to guess the framebuffer's WxHxB and
4059 masks automatically (sometimes the kernel gives incorrect infor‐
4060 mation), specify them with a @WxHxB (and optional :R/G/B masks)
4061 at the end of the string.
4062 Examples: -rawfb console -rawfb /dev/fb0 (same) -rawfb
4064 console3 (force /dev/tty3) -rawfb consolex
4065 (no keystrokes or mouse) -rawfb console:/dev/nonstd -rawfb con‐
4066 sole -pipeinput UINPUT:accel=4.0 -rawfb vt3
4067 (/dev/tty3 w/o /dev/fb0)
4068 VNC HOST: if the -rawfb string is of the form "vnc:host:N" then
4070 the VNC display "N" on the remote VNC server "host" is connected
4071 to (i.e. x11vnc acts as a VNC client itself) and that frame‐
4072 buffer is exported.
4073 This mode is really only of use if you are trying to improve
4075 performance in the case of many (e.g. > 10) simultaneous VNC
4076 viewers, and you try a divide and conquer scheme to reduce band‐
4077 width and improve responsiveness.
4078 For example, if there will be 64 simultaneous VNC viewers this
4080 can lead to a lot of redundant VNC traffic to and from the
4081 server host:N, extra CPU usage, and all viewers response can be
4082 reduced by having to wait for writes to the slowest client to
4083 finish. However, if you set up 8 reflectors/repeaters started
4084 with option -rawfb vnc:host:N, then there are only 8 connections
4085 to host:N. Each repeater then handles 8 vnc viewer connections
4086 thereby spreading the load around. In classroom broadcast
4087 usage, try to put the repeaters on different switches. This
4088 mode is the same as -reflect host:N. Replace "host:N" by "lis‐
4089 ten" or "listen:port" for a reverse connection.
4090 Overall performance will not be as good as a single direct con‐
4092 nection because, among other things, there is an additional
4093 level of framebuffer polling and pointer motion can still induce
4094 many changes per second that must be propagated. Tip: if the
4095 remote VNC is x11vnc doing wireframing, or an X display that
4096 does wireframing that gives much better response than opaque
4097 window dragging. Consider the -nodragging option if the problem
4098 is severe.
4099 The env. var. X11VNC_REFLECT_PASSWORD can be set to the password
4101 needed to log into the vnc host server, or to
4102 "file:path_to_file" to indicate a file containing the password
4103 as its first line.
4104 The VNC HOST mode implies -shared. Use -noshared as a subse‐
4106 quent cmdline option to disable sharing.
4107 -freqtab file
4109 For use with "-rawfb video" for TV tuner devices to specify sta‐
4111 tion frequencies. Instead of using the built in ntsc-cable-us
4112 mapping of station number to frequency, use the data in file.
4113 For stations that are not numeric, e.g. SE20, they are placed
4114 above the highest numbered station in the order they are found.
4115 Example: "-freqtab /usr/X11R6/share/xawtv/europe-west.list" You
4116 can make your own freqtab by copying the xawtv format.
4117 -pipeinput cmd
4119 This option lets you supply an external command in cmd that
4121 x11vnc will pipe all of the user input events to in a simple
4122 format. In -pipeinput mode by default x11vnc will not process
4123 any of the user input events. If you prefix cmd with "tee:" it
4124 will both send them to the pipe command and process them. For a
4125 description of the format run "-pipeinput tee:/bin/cat".
4126 Another prefix is "reopen" which means to reopen pipe if it
4127 exits. Separate multiple prefixes with commas.
4128 In combination with -rawfb one might be able to do amusing
4130 things (e.g. control non-X devices). To facilitate this, if
4131 -rawfb is in effect then the value is stored in X11VNC_RAWFB_STR
4132 for the pipe command to use if it wants. Do 'env | grep X11VNC'
4133 for more.
4134 Built-in pipeinput modes (no external program required):
4136 If cmd is "VID" and you are using the -rawfb for a video capture
4138 device, then an internal list of keyboard mappings is used to
4139 set parameters of the video. The mappings are:
4140 "B" and "b" adjust the brightness up and down. "H" and "h"
4142 adjust the hue. "C" and "c" adjust the colour. "N" and "n"
4143 adjust the contrast. "S" and "s" adjust the size of the capture
4144 screen. "I" and "i" cycle through input channels. Up and Down
4145 arrows adjust the station (if a tuner) F1, F2, ..., F6 will
4146 switch the video capture pixel format to HI240, RGB565, RGB24,
4147 RGB32, RGB555, and GREY respectively. See -rawfb video for
4148 details.
4149 If cmd is "CONSOLE" or "CONSOLEn" where n is a Linux console
4151 number, then the linux console keystroke insertion to /dev/ttyN
4152 (see -rawfb console) is performed.
4153 If cmd begins with "UINPUT" then the Linux uinput module is used
4155 to insert both keystroke and mouse events to the Linux console
4156 (see -rawfb above). This usually is the /dev/input/uinput
4157 device file (you may need to create it with "mknod
4158 /dev/input/uinput c 10 223" and insert the module with "modprobe
4159 uinput".
4160 The UINPUT mode currently only does US keyboards (a scan code
4162 option may be added), and not all keysyms are supported.
4163 You may want to use the options -cursor none and -nodragging in
4165 this mode.
4166 Additional tuning options may be supplied via: UIN‐
4168 PUT:opt1,opt2,... (a comma separated list). If an option begins
4169 with "/" it is taken as the uinput device file.
4170 Which uinput is injected can be controlled by an option string
4172 made of the characters "K", "M", and "B" (see the -input
4173 option), e.g. "KM" allows keystroke and motion but not button
4174 clicks.
4175 A UINPUT option of the form: accel=f, or accel=fx+fy sets the
4177 mouse motion "acceleration". This is used to correct raw mouse
4178 relative motion into how much the application cursor moves
4179 (x11vnc has no control over, or knowledge of how the windowing
4180 application interprets the raw mouse motions). Typically the
4181 acceleration for an X display is 2 (see xset "m" option). "f"
4182 is a floating point number, e.g. 3.0. Use "fx+fy" if you need
4183 to supply different corrections for x and y.
4184 Note: the default acceleration is 2.0 since it seems both X and
4186 qt-embedded often (but not always) use this value.
4187 Even with a correct accel setting the mouse position will get
4189 out of sync (probably due to a mouse "threshold" setting where
4190 the acceleration doe not apply, set xset(1) ). The option
4191 reset=N sets the number of ms (default 150) after which the cur‐
4192 sor is attempted to be reset (by forcing the mouse to (0, 0) via
4193 small increments and then back out to (x, y) in 1 jump), This
4194 correction seems to be needed but can cause jerkiness or unex‐
4195 pected behavior with menus, etc. Use reset=0 to disable.
4196 If the uinput device has an absolute pointer (as opposed to a
4198 normal mouse that is a relative pointer) you can specify the
4199 option "abs". Note that a touchpad on a laptop is an absolute
4200 device to some degree. This (usually) avoids all the problems
4201 with mouse acceleration. If x11vnc has trouble deducing the
4202 size of the device, use "abs=WxH". Furthermore, if the device
4203 is a touchscreen (assumed to have an absolute pointer) use
4204 "touch" or "touch=WxH".
4205 If you set the env. var X11VNC_UINPUT_THRESHOLDS then the
4207 thresh=n mode will be enabled. It is currently not working
4208 well. If |dx| <= thresh and |dy| < thresh no acceleration is
4209 applied. Use "thresh=+n" |dx| + |dy| < thresh to be used
4210 instead (X11?)
4211 Example: -pipeinput UINPUT:accel=4.0 -cursor none
4213 You can also set the env. var X11VNC_UINPUT_DEBUG=1 or higher to
4215 get debugging output for UINPUT mode.
4216 -macnodim
4218 For the native MacOSX server, disable dimming.
4220 -macnosleep
4222 For the native MacOSX server, disable display sleep.
4224 -macnosaver
4226 For the native MacOSX server, disable screensaver.
4228 -macnowait
4230 For the native MacOSX server, do not wait for the user to switch
4232 back to his display.
4233 -macwheel n
4235 For the native MacOSX server, set the mouse wheel speed to n
4237 (default 5).
4238 -macnoswap
4240 For the native MacOSX server, do not swap mouse buttons 2 and 3.
4242 -macnoresize
4244 For the native MacOSX server, do not resize or reset the frame‐
4246 buffer even if it is detected that the screen resolution or
4247 depth has changed.
4248 -maciconanim n
4250 For the native MacOSX server, set n to the number of millisec‐
4252 onds that the window iconify/deiconify animation takes. In
4253 -ncache mode this value will be used to skip the animation if
4254 possible. (default 400)
4255 -macmenu
4257 For the native MacOSX server, in -ncache client-side caching
4259 mode, try to cache pull down menus (not perfect because they
4260 have animated fades, etc.)
4261 -macuskbd
4263 For the native MacOSX server, use the original keystroke inser‐
4265 tion code based on a US keyboard.
4266 -gui [gui-opts]
4268 Start up a simple tcl/tk gui based on the the remote control
4270 options -remote/-query described below. Requires the "wish"
4271 program to be installed on the machine. "gui-opts" is not
4272 required: the default is to start up both the full gui and
4273 x11vnc with the gui showing up on the X display in the environ‐
4274 ment variable DISPLAY.
4275 "gui-opts" can be a comma separated list of items. Currently
4277 there are these types of items: 1) a gui mode, a 2) gui "sim‐
4278 plicity", 3) the X display the gui should display on, 4) a
4279 "tray" or "icon" mode, and 5) a gui geometry.
4280 1) The gui mode can be "start", "conn", or "wait" "start" is the
4282 default mode above and is not required. "conn" means do not
4283 automatically start up x11vnc, but instead just try to connect
4284 to an existing x11vnc process. "wait" means just start the gui
4285 and nothing else (you will later instruct the gui to start
4286 x11vnc or connect to an existing one.)
4287 2) The gui simplicity is off by default (a power-user gui with
4289 all options is presented) To start with something less daunting
4290 supply the string "simple" ("ez" is an alias for this). Once
4291 the gui is started you can toggle between the two with "Misc ->
4292 simple_gui".
4293 3) Note the possible confusion regarding the potentially two
4295 different X displays: x11vnc polls one, but you may want the gui
4296 to appear on another. For example, if you ssh in and x11vnc is
4297 not running yet you may want the gui to come back to you via
4298 your ssh redirected X display (e.g. localhost:10).
4299 If you do not specify a gui X display in "gui-opts" then the
4301 DISPLAY environment variable and -display option are tried (in
4302 that order). Regarding the x11vnc X display the gui will try to
4303 communication with, it first tries -display and then DISPLAY.
4304 For example, "x11vnc -display :0 -gui otherhost:0", will remote
4305 control an x11vnc polling :0 and display the gui on otherhost:0
4306 The "tray/icon" mode below reverses this preference, preferring
4307 to display on the x11vnc display.
4308 4) When "tray" or "icon" is specified, the gui presents itself
4310 as a small icon with behavior typical of a "system tray" or
4311 "dock applet". The color of the icon indicates status (con‐
4312 nected clients) and there is also a balloon status. Clicking on
4313 the icon gives a menu from which properties, etc, can be set and
4314 the full gui is available under "Advanced". To be fully func‐
4315 tional, the gui mode should be "start" (the default).
4316 Note that tray or icon mode will imply the -forever x11vnc
4318 option (if the x11vnc server is started along with the gui)
4319 unless -connect or -connect_or_exit has been specified. So
4320 x11vnc (and the tray/icon gui) will wait for more connections
4321 after the first client disconnects. If you want only one viewer
4322 connection include the -once option.
4323 For "icon" the gui just a small standalone window. For "tray"
4325 it will attempt to embed itself in the "system tray" if possi‐
4326 ble. If "=setpass" is appended then at startup the X11 user will
4327 be prompted to set the VNC session password. If =<hexnumber> is
4328 appended that icon will attempt to embed itself in the window
4329 given by hexnumber. Use =noadvanced to disable the full gui.
4330 (To supply more than one, use "+" sign). E.g. -gui tray=setpass
4331 and -gui icon=0x3600028
4332 Other modes: "full", the default and need not be specified.
4334 "-gui none", do not show a gui, useful to override a ~/.x11vncrc
4335 setting, etc.
4336 5) When "geom=+X+Y" is specified, that geometry is passed to the
4338 gui toplevel. This is the icon in icon/tray mode, or the full
4339 gui otherwise. You can also specify width and height, i.e.
4340 WxH+X+Y, but it is not recommended. In "tray" mode the geometry
4341 is ignored unless the system tray manager does not seem to be
4342 running. One could imagine using something like "-gui
4343 tray,geom=+4000+4000" with a display manager to keep the gui
4344 invisible until someone logs in...
4345 More icon tricks, "icon=minimal" gives an icon just with the VNC
4347 display number. You can also set the font with "iconfont=...".
4348 The following could be useful: "-gui icon=minimal,icon‐
4349 font=5x8,geom=24x10+0-0"
4350 General examples of the -gui option: "x11vnc -gui", "x11vnc -gui
4352 ez" "x11vnc -gui localhost:10", "x11vnc -gui conn,host:0",
4353 "x11vnc -gui tray,ez" "x11vnc -gui tray=setpass"
4354 If you do not intend to start x11vnc from the gui (i.e. just
4356 remote control an existing one), then the gui process can run on
4357 a different machine from the x11vnc server as long as X permis‐
4358 sions, etc. permit communication between the two.
4359 -remote command
4361 Remotely control some aspects of an already running x11vnc
4363 server. "-R" and "-r" are aliases for "-remote". After the
4364 remote control command is sent to the running server the 'x11vnc
4365 -remote ...' command exits. You can often use the -query com‐
4366 mand (see below) to see if the x11vnc server processed your
4367 -remote command.
4368 The default communication channel is that of X properties
4370 (specifically X11VNC_REMOTE), and so this command must be run
4371 with correct settings for DISPLAY and possibly XAUTHORITY to
4372 connect to the X server and set the property. Alternatively,
4373 use the -display and -auth options to set them to the correct
4374 values. The running server cannot use the -novncconnect option
4375 because that disables the communication channel. See below for
4376 alternate channels.
4377 For example: 'x11vnc -remote stop' (which is the same as ´x11vnc
4379 -R stop') will close down the x11vnc server. ´x11vnc -R shared'
4380 will enable shared connections, and ´x11vnc -R scale:3/4' will
4381 rescale the desktop.
4382 The following -remote/-R commands are supported:
4384 stop terminate the server, same as "quit" "exit" or
4386 "shutdown".
4387 ping see if the x11vnc server responds. Return is:
4389 ans=ping:<xdisplay>
4390 blacken try to push a black fb update to all clients
4392 (due to timings a client could miss it). Same as "zero", also
4393 "zero:x1,y1,x2,y2" for a rectangle.
4394 refresh send the entire fb to all clients.
4396 reset recreate the fb, polling memory, etc.
4398 id:windowid set -id window to "windowid". empty or "root" to
4400 go back to root window
4401 sid:windowid set -sid window to "windowid"
4403 waitmapped wait until subwin is mapped.
4405 nowaitmapped do not wait until subwin is mapped.
4407 clip:WxH+X+Y set -clip mode to "WxH+X+Y"
4409 flashcmap enable -flashcmap mode.
4411 noflashcmap disable -flashcmap mode.
4413 shiftcmap:n set -shiftcmap to n.
4415 notruecolor enable -notruecolor mode.
4417 truecolor disable -notruecolor mode.
4419 overlay enable -overlay mode (if applicable).
4421 nooverlay disable -overlay mode.
4423 overlay_cursor in -overlay mode, enable cursor drawing.
4425 overlay_nocursor disable cursor drawing. same as nooverlay_cur‐
4427 sor.
4428 8to24 enable -8to24 mode (if applicable).
4430 no8to24 disable -8to24 mode.
4432 8to24_opts:str set the -8to24 opts to "str".
4434 24to32 enable -24to32 mode (if applicable).
4436 no24to32 disable -24to32 mode.
4438 visual:vis set -visual to "vis"
4440 scale:frac set -scale to "frac"
4442 scale_cursor:f set -scale_cursor to "f"
4444 viewonly enable -viewonly mode.
4446 noviewonly disable -viewonly mode.
4448 shared enable -shared mode.
4450 noshared disable -shared mode.
4452 forever enable -forever mode.
4454 noforever disable -forever mode.
4456 timeout:n reset -timeout to n, if there are currently no
4458 clients, exit unless one connects in the next n secs.
4459 tightfilexfer enable filetransfer for NEW clients.
4461 notightfilexfer disable filetransfer for NEW clients.
4463 ultrafilexfer enable filetransfer for clients.
4465 noultrafilexfer disable filetransfer for clients.
4467 rfbversion:n.m set -rfbversion for new clients.
4469 http enable http client connections.
4471 nohttp disable http client connections.
4473 deny deny any new connections, same as "lock"
4475 nodeny allow new connections, same as "unlock"
4477 avahi enable avahi service advertising.
4479 noavahi disable avahi service advertising.
4481 mdns enable avahi service advertising.
4483 nomdns disable avahi service advertising.
4485 zeroconf enable avahi service advertising.
4487 nozeroconf disable avahi service advertising.
4489 connect:host do reverse connection to host, "host" may be a
4491 comma separated list of hosts or host:ports. See -connect.
4492 Passwords required as with fwd connections. See
4493 X11VNC_REVERSE_CONNECTION_NO_AUTH=1
4494 disconnect:host disconnect any clients from "host" same as
4496 "close:host". Use host "all" to close all current clients. If
4497 you know the client internal hex ID, e.g. 0x3 (returned by
4498 "-query clients" and RFB_CLIENT_ID) you can use that too.
4499 proxy:host:port set reverse connection proxy (empty to disable).
4501 allowonce:host For the next connection only, allow connection
4503 from "host". In -ssl mode two connections are allowed (i.e.
4504 Fetch Cert) unless X11VNC_NO_SSL_ALLOW_TWICE=1
4505 allow:hostlist set -allow list to (comma separated) "hostlist".
4507 See -allow and -localhost. Do not use with -allow /path/to/file
4508 Use "+host" to add a single host, and use "-host" to delete a
4509 single host
4510 localhost enable -localhost mode
4512 nolocalhost disable -localhost mode
4514 listen:str set -listen to str, empty to disable.
4516 nolookup enable -nolookup mode.
4518 lookup disable -nolookup mode.
4520 input:str set -input to "str", empty to disable.
4522 grabkbd enable -grabkbd mode.
4524 nograbkbd disable -grabkbd mode.
4526 grabptr enable -grabptr mode.
4528 nograbptr disable -grabptr mode.
4530 grabalways enable -grabalways mode.
4532 nograbalways disable -grabalways mode.
4534 client_input:str set the K, M, B -input on a per-client basis.
4536 select which client as for disconnect, e.g. client_input:host:MB
4537 or client_input:0x2:K
4538 accept:cmd set -accept "cmd" (empty to disable).
4540 afteraccept:cmd set -afteraccept (empty to disable).
4542 gone:cmd set -gone "cmd" (empty to disable).
4544 noshm enable -noshm mode.
4546 shm disable -noshm mode (i.e. use shm).
4548 flipbyteorder enable -flipbyteorder mode, you may need to set
4550 noshm for this to do something.
4551 noflipbyteorder disable -flipbyteorder mode.
4553 onetile enable -onetile mode. (you may need to set shm
4555 for this to do something)
4556 noonetile disable -onetile mode.
4558 solid enable -solid mode
4560 nosolid disable -solid mode.
4562 solid_color:color set -solid color (and apply it).
4564 blackout:str set -blackout "str" (empty to disable). See
4566 -blackout for the form of "str" (basically: WxH+X+Y,...) Use
4567 "+WxH+X+Y" to append a single rectangle use "-WxH+X+Y" to delete
4568 one
4569 xinerama enable -xinerama mode. (if applicable)
4571 noxinerama disable -xinerama mode.
4573 xtrap enable -xtrap input mode(if applicable)
4575 noxtrap disable -xtrap input mode.
4577 xrandr enable -xrandr mode. (if applicable)
4579 noxrandr disable -xrandr mode.
4581 xrandr_mode:mode set the -xrandr mode to "mode".
4583 rotate:mode set the -rotate mode to "mode".
4585 padgeom:WxH set -padgeom to WxH (empty to disable) If WxH is
4587 "force" or "do" the padded geometry fb is immediately applied.
4588 quiet enable -quiet mode.
4590 noquiet disable -quiet mode.
4592 modtweak enable -modtweak mode.
4594 nomodtweak enable -nomodtweak mode.
4596 xkb enable -xkb modtweak mode.
4598 noxkb disable -xkb modtweak mode.
4600 capslock enable -capslock mode.
4602 nocapslock disable -capslock mode.
4604 skip_lockkeys enable -skip_lockkeys mode.
4606 noskip_lockkeys disable -skip_lockkeys mode.
4608 skip_keycodes:str enable -xkb -skip_keycodes "str".
4610 sloppy_keys enable -sloppy_keys mode.
4612 nosloppy_keys disable -sloppy_keys mode.
4614 skip_dups enable -skip_dups mode.
4616 noskip_dups disable -skip_dups mode.
4618 add_keysyms enable -add_keysyms mode.
4620 noadd_keysyms stop adding keysyms. those added will still be
4622 removed at exit.
4623 clear_mods enable -clear_mods mode and clear them.
4625 noclear_mods disable -clear_mods mode.
4627 clear_keys enable -clear_keys mode and clear them.
4629 noclear_keys disable -clear_keys mode.
4631 clear_locks do the clear_locks action.
4633 clear_all do the clear_all action.
4635 keystate have x11vnc print current keystate.
4637 remap:str set -remap "str" (empty to disable). See -remap
4639 for the form of "str" (basically: key1-key2,key3-key4,...) Use
4640 "+key1-key2" to append a single keymapping, use "-key1-key2" to
4641 delete.
4642 norepeat enable -norepeat mode.
4644 repeat disable -norepeat mode.
4646 nofb enable -nofb mode.
4648 fb disable -nofb mode.
4650 bell enable bell (if supported).
4652 nobell disable bell.
4654 sendbell ring the bell now.
4656 nosel enable -nosel mode.
4658 sel disable -nosel mode.
4660 noprimary enable -noprimary mode.
4662 primary disable -noprimary mode.
4664 nosetprimary enable -nosetprimary mode.
4666 setprimary disable -nosetprimary mode.
4668 noclipboard enable -noclipboard mode.
4670 clipboard disable -noclipboard mode.
4672 nosetclipboard enable -nosetclipboard mode.
4674 setclipboard disable -nosetclipboard mode.
4676 seldir:str set -seldir to "str"
4678 cursor:mode enable -cursor "mode".
4680 show_cursor enable showing a cursor.
4682 noshow_cursor disable showing a cursor. (same as "nocursor")
4684 cursor_drag enable cursor changes during drag.
4686 nocursor_drag disable cursor changes during drag.
4688 arrow:n set -arrow to alternate n.
4690 xfixes enable xfixes cursor shape mode.
4692 noxfixes disable xfixes cursor shape mode.
4694 alphacut:n set -alphacut to n.
4696 alphafrac:f set -alphafrac to f.
4698 alpharemove enable -alpharemove mode.
4700 noalpharemove disable -alpharemove mode.
4702 alphablend disable -noalphablend mode.
4704 noalphablend enable -noalphablend mode.
4706 cursorshape disable -nocursorshape mode.
4708 nocursorshape enable -nocursorshape mode.
4710 cursorpos disable -nocursorpos mode.
4712 nocursorpos enable -nocursorpos mode.
4714 xwarp enable -xwarppointer mode.
4716 noxwarp disable -xwarppointer mode.
4718 buttonmap:str set -buttonmap "str", empty to disable
4720 dragging disable -nodragging mode.
4722 nodragging enable -nodragging mode.
4724 ncache reenable -ncache mode.
4726 noncache disable -ncache mode.
4728 ncache_size:n set -ncache size to n.
4730 ncache_cr enable -ncache_cr mode.
4732 noncache_cr disable -ncache_cr mode.
4734 ncache_no_moveraise enable no_moveraise mode.
4736 noncache_no_moveraise disable no_moveraise mode.
4738 ncache_no_dtchange enable ncache_no_dtchange mode.
4740 noncache_no_dtchange disable ncache_no_dtchange mode.
4742 ncache_old_wm enable ncache_old_wm mode.
4744 noncache_old_wm disable ncache_old_wm mode.
4746 ncache_no_rootpixmap enable ncache_no_rootpixmap.
4748 noncache_no_rootpixmap disable ncache_no_rootpixmap.
4750 ncache_reset_rootpixmap recheck the root pixmap, ncrp
4752 ncache_keep_anims enable ncache_keep_anims.
4754 noncache_keep_anims disable ncache_keep_anims.
4756 ncache_pad:n set -ncache_pad to n.
4758 wireframe enable -wireframe mode. same as "wf"
4760 nowireframe disable -wireframe mode. same as "nowf"
4762 wireframe:str enable -wireframe mode string.
4764 wireframe_mode:str enable -wireframe mode string.
4766 wireframelocal enable wireframelocal. same as "wfl"
4768 nowireframe disable wireframelocal. same as "nowfl"
4770 wirecopyrect:str set -wirecopyrect string. same as "wcr:"
4772 scrollcopyrect:str set -scrollcopyrect string. same "scr"
4774 noscrollcopyrect disable -scrollcopyrect__mode_. "noscr"
4776 scr_area:n set -scr_area to n
4778 scr_skip:list set -scr_skip to "list"
4780 scr_inc:list set -scr_inc to "list"
4782 scr_keys:list set -scr_keys to "list"
4784 scr_term:list set -scr_term to "list"
4786 scr_keyrepeat:str set -scr_keyrepeat to "str"
4788 scr_parms:str set -scr_parms parameters.
4790 fixscreen:str set -fixscreen to "str".
4792 noxrecord disable all use of RECORD extension.
4794 xrecord enable use of RECORD extension.
4796 reset_record reset RECORD extension (if avail.)
4798 pointer_mode:n set -pointer_mode to n. same as "pm"
4800 input_skip:n set -input_skip to n.
4802 allinput enable use of -allinput mode.
4804 noallinput disable use of -allinput mode.
4806 ssltimeout:n set -ssltimeout to n.
4808 speeds:str set -speeds to str.
4810 wmdt:str set -wmdt to str.
4812 debug_pointer enable -debug_pointer, same as "dp"
4814 nodebug_pointer disable -debug_pointer, same as "nodp"
4816 debug_keyboard enable -debug_keyboard, same as "dk"
4818 nodebug_keyboard disable -debug_keyboard, same as "nodk"
4820 defer:n set -defer to n ms,same as deferupdate:n
4822 wait:n set -wait to n ms.
4824 wait_ui:f set -wait_ui factor to f.
4826 setdefer:n set -setdefer to -2,-1,0,1, or 2.
4828 wait_bog disable -nowait_bog mode.
4830 nowait_bog enable -nowait_bog mode.
4832 slow_fb:f set -slow_fb to f seconds.
4834 xrefresh:f set -xrefresh to f seconds.
4836 readtimeout:n set read timeout to n seconds.
4838 nap enable -nap mode.
4840 nonap disable -nap mode.
4842 sb:n set -sb to n s, same as screen_blank:n
4844 fbpm disable -nofbpm mode.
4846 nofbpm enable -nofbpm mode.
4848 dpms disable -nodpms mode.
4850 nodpms enable -nodpms mode.
4852 forcedpms enable -forcedpms mode.
4854 noforcedpms disable -forcedpms mode.
4856 clientdpms enable -clientdpms mode.
4858 noclientdpms disable -clientdpms mode.
4860 noserverdpms enable -noserverdpms mode.
4862 serverdpms disable -noserverdpms mode.
4864 noultraext enable -noultraext mode.
4866 ultraext disable -noultraext mode.
4868 chatwindow enable local chatwindow mode.
4870 nochatwindow disable local chatwindow mode.
4872 chaton begin chat using local window.
4874 chatoff end chat using local window.
4876 xdamage enable xdamage polling hints.
4878 noxdamage disable xdamage polling hints.
4880 xd_area:A set -xd_area max pixel area to "A"
4882 xd_mem:f set -xd_mem remembrance to "f"
4884 fs:frac set -fs fraction to "frac", e.g. 0.5
4886 gaps:n set -gaps to n.
4888 grow:n set -grow to n.
4890 fuzz:n set -fuzz to n.
4892 snapfb enable -snapfb mode.
4894 nosnapfb disable -snapfb mode.
4896 rawfb:str set -rawfb mode to "str".
4898 uinput_accel:f set uinput_accel to f.
4900 uinput_reset:n set uinput_reset to n ms.
4902 uinput_always:n set uinput_always to 1/0.
4904 progressive:n set libvncserver -progressive slice height
4906 parameter to n.
4907 desktop:str set -desktop name to str for new clients.
4909 rfbport:n set -rfbport to n.
4911 macnosaver enable -macnosaver mode.
4913 macsaver disable -macnosaver mode.
4915 macnowait enable -macnowait mode.
4917 macwait disable -macnowait mode.
4919 macwheel:n set -macwheel to n.
4921 macnoswap enable -macnoswap mouse button mode.
4923 macswap disable -macnoswap mouse button mode.
4925 macnoresize enable -macnoresize mode.
4927 macresize disable -macnoresize mode.
4929 maciconanim:n set -maciconanim to n.
4931 macmenu enable -macmenu mode.
4933 macnomenu disable -macnmenu mode.
4935 httpport:n set -httpport to n.
4937 httpdir:dir set -httpdir to dir (and enable http).
4939 enablehttpproxy enable -enablehttpproxy mode.
4941 noenablehttpproxy disable -enablehttpproxy mode.
4943 alwaysshared enable -alwaysshared mode.
4945 noalwaysshared disable -alwaysshared mode. (may interfere
4947 with other options)
4948 nevershared enable -nevershared mode.
4950 nonevershared disable -nevershared mode. (may interfere with
4952 other options)
4953 dontdisconnect enable -dontdisconnect mode.
4955 nodontdisconnect disable -dontdisconnect mode. (may interfere
4957 with other options)
4958 debug_xevents enable debugging X events.
4960 nodebug_xevents disable debugging X events.
4962 debug_xdamage enable debugging X DAMAGE mechanism.
4964 nodebug_xdamage disable debugging X DAMAGE mechanism.
4966 debug_wireframe enable debugging wireframe mechanism.
4968 nodebug_wireframe disable debugging wireframe mechanism.
4970 debug_scroll enable debugging scrollcopy mechanism.
4972 nodebug_scroll disable debugging scrollcopy mechanism.
4974 debug_tiles enable -debug_tiles
4976 nodebug_tiles disable -debug_tiles
4978 debug_grabs enable -debug_grabs
4980 nodebug_grabs disable -debug_grabs
4982 debug_sel enable -debug_sel
4984 nodebug_sel disable -debug_sel
4986 debug_ncache enable -debug_ncache
4988 nodebug_ncache disable -debug_ncache
4990 dbg enable -dbg crash shell
4992 nodbg disable -dbg crash shell
4994 noremote disable the -remote command processing, it can‐
4996 not be turned back on.
4997 The vncconnect(1) command from standard VNC
4999 distributions may also be used if string is prefixed
5001 with "cmd=" E.g. 'vncconnect cmd=stop'. Under some
5003 circumstances xprop(1) can used if it supports -set
5005 (see the FAQ).
5007 If "-connect /path/to/file" has been supplied to the
5009 running x11vnc server then that file can be used as a
5011 communication channel (this is the only way to remote
5013 control one of many x11vnc's polling the same X display)
5015 Simply run: 'x11vnc -connect /path/to/file -remote ...'
5017 or you can directly write to the file via something
5019 like: "echo cmd=stop > /path/to/file", etc.
5021 -query variable
5023 Like -remote, except just query the value of variable. "-Q" is
5025 an alias for "-query". Multiple queries can be done by separat‐
5026 ing variables by commas, e.g. -query var1,var2. The results come
5027 back in the form ans=var1:value1,ans=var2:value2,... to the
5028 standard output. If a variable is read-only, it comes back with
5029 prefix "aro=" instead of "ans=".
5030 Some -remote commands are pure actions that do not make sense as
5032 variables, e.g. "stop" or "disconnect", in these cases the value
5033 returned is "N/A". To direct a query straight to the
5034 X11VNC_REMOTE property or connect file use "qry=..." instead of
5035 "cmd=..."
5036 ans= stop quit exit shutdown ping blacken zero refresh reset
5038 close disconnect id sid waitmapped nowaitmapped clip flashcmap
5039 noflashcmap shiftcmap truecolor notruecolor overlay nooverlay
5040 overlay_cursor overlay_yescursor nooverlay_nocursor noover‐
5041 lay_cursor nooverlay_yescursor overlay_nocursor 8to24 no8to24
5042 8to24_opts 24to32 no24to32 visual scale scale_cursor viewonly
5043 noviewonly shared noshared forever noforever once timeout tight‐
5044 filexfer notightfilexfer ultrafilexfer noultrafilexfer rfbver‐
5045 sion deny lock nodeny unlock avahi mdns zeroconf noavahi nomdns
5046 nozeroconf connect proxy allowonce allow localhost nolocalhost
5047 listen lookup nolookup accept afteraccept gone shm noshm flipby‐
5048 teorder noflipbyteorder onetile noonetile solid_color solid
5049 nosolid blackout xinerama noxinerama xtrap noxtrap xrandr
5050 noxrandr xrandr_mode rotate padgeom quiet q noquiet modtweak
5051 nomodtweak xkb noxkb capslock nocapslock skip_lockkeys
5052 noskip_lockkeys skip_keycodes sloppy_keys nosloppy_keys
5053 skip_dups noskip_dups add_keysyms noadd_keysyms clear_mods
5054 noclear_mods clear_keys noclear_keys clear_all clear_locks
5055 keystate remap repeat norepeat fb nofb bell nobell sel nosel
5056 primary noprimary setprimary nosetprimary clipboard noclipboard
5057 setclipboard nosetclipboard seldir cursorshape nocursorshape
5058 cursorpos nocursorpos cursor_drag nocursor_drag cursor show_cur‐
5059 sor noshow_cursor nocursor arrow xfixes noxfixes xdamage noxdam‐
5060 age xd_area xd_mem alphacut alphafrac alpharemove noalpharemove
5061 alphablend noalphablend xwarppointer xwarp noxwarppointer
5062 noxwarp buttonmap dragging nodragging ncache_cr noncache_cr
5063 ncache_no_moveraise noncache_no_moveraise ncache_no_dtchange
5064 noncache_no_dtchange ncache_no_rootpixmap noncache_no_rootpixmap
5065 ncache_reset_rootpixmap ncrp ncache_keep_anims non‐
5066 cache_keep_anims ncache_old_wm noncache_old_wm ncache_pad ncache
5067 noncache ncache_size debug_ncache nodebug_ncache wireframe_mode
5068 wireframe wf nowireframe nowf wireframelocal wfl nowireframelo‐
5069 cal nowfl wirecopyrect wcr nowirecopyrect nowcr scr_area
5070 scr_skip scr_inc scr_keys scr_term scr_keyrepeat scr_parms
5071 scrollcopyrect scr noscrollcopyrect noscr fixscreen noxrecord
5072 xrecord reset_record pointer_mode pm input_skip allinput
5073 noallinput input grabkbd nograbkbd grabptr nograbptr grabalways
5074 nograbalways grablocal client_input ssltimeout speeds wmdt
5075 debug_pointer dp nodebug_pointer nodp debug_keyboard dk node‐
5076 bug_keyboard nodk keycode deferupdate defer setdefer wait_ui
5077 wait_bog nowait_bog slow_fb xrefresh wait readtimeout nap nonap
5078 sb screen_blank fbpm nofbpm dpms nodpms clientdpms noclientdpms
5079 forcedpms noforcedpms noserverdpms serverdpms noultraext ultra‐
5080 ext chatwindow nochatwindow chaton chatoff fs gaps grow fuzz
5081 snapfb nosnapfb rawfb uinput_accel uinput_thresh uinput_reset
5082 uinput_always progressive rfbport http nohttp httpport httpdir
5083 enablehttpproxy noenablehttpproxy alwaysshared noalwaysshared
5084 nevershared noalwaysshared dontdisconnect nodontdisconnect desk‐
5085 top debug_xevents nodebug_xevents debug_xevents debug_xdamage
5086 nodebug_xdamage debug_xdamage debug_wireframe nodebug_wireframe
5087 debug_wireframe debug_scroll nodebug_scroll debug_scroll
5088 debug_tiles dbt nodebug_tiles nodbt debug_tiles debug_grabs
5089 nodebug_grabs debug_sel nodebug_sel dbg nodbg macnosaver mac‐
5090 saver nomacnosaver macnowait macwait nomacnowait macwheel mac‐
5091 noswap macswap nomacnoswap macnoresize macresize nomacnoresize
5092 maciconanim macmenu macnomenu nomacmenu macuskbd nomacuskbd
5093 noremote
5094 aro= noop display vncdisplay desktopname guess_desktop http_url
5096 auth xauth users rootshift clipshift scale_str scaled_x scaled_y
5097 scale_numer scale_denom scale_fac_x scale_fac_y scaling_blend
5098 scaling_nomult4 scaling_pad scaling_interpolate inetd privremote
5099 unsafe safer nocmds passwdfile unixpw unixpw_nis unixpw_list ssl
5100 ssl_pem sslverify stunnel stunnel_pem https httpsredir usepw
5101 using_shm logfile o flag rc norc h help V version lastmod bg
5102 sigpipe threads readrate netrate netlatency pipeinput clients
5103 client_count pid ext_xtest ext_xtrap ext_xrecord ext_xkb
5104 ext_xshm ext_xinerama ext_overlay ext_xfixes ext_xdamage
5105 ext_xrandr rootwin num_buttons button_mask mouse_x mouse_y bpp
5106 depth indexed_color dpy_x dpy_y wdpy_x wdpy_y off_x off_y cdpy_x
5107 cdpy_y coff_x coff_y rfbauth passwd viewpasswd
5108 -QD variable
5110 Just like -query variable, but returns the default value for
5112 that parameter (no running x11vnc server is consulted)
5113 -sync
5115 By default -remote commands are run asynchronously, that is, the
5117 request is posted and the program immediately exits. Use -sync
5118 to have the program wait for an acknowledgement from the x11vnc
5119 server that command was processed (somehow). On the other hand
5120 -query requests are always processed synchronously because they
5121 have to wait for the answer.
5122 Also note that if both -remote and -query requests are supplied
5124 on the command line, the -remote is processed first (syn‐
5125 chronously: no need for -sync), and then the -query request is
5126 processed in the normal way. This allows for a reliable way to
5127 see if the -remote command was processed by querying for any new
5128 settings. Note however that there is timeout of a few seconds
5129 so if the x11vnc takes longer than that to process the requests
5130 the requester will think that a failure has taken place.
5131 -noremote, -yesremote
5133 Do not process any remote control commands or queries. Do
5135 process remote control commands or queries. Default: -yesremote
5136 A note about security wrt remote control commands. If someone
5138 can connect to the X display and change the property
5139 X11VNC_REMOTE, then they can remotely control x11vnc. Normally
5140 access to the X display is protected. Note that if they can
5141 modify X11VNC_REMOTE on the X server, they have enough permis‐
5142 sions to also run their own x11vnc and thus have complete con‐
5143 trol of the desktop. If the "-connect /path/to/file" channel
5144 is being used, obviously anyone who can write to /path/to/file
5145 can remotely control x11vnc. So be sure to protect the X dis‐
5146 play and that file's write permissions. See -privremote below.
5147 If you are paranoid and do not think -noremote is enough, to
5149 disable the X11VNC_REMOTE property channel completely use
5150 -novncconnect, or use the -safer option that shuts many things
5151 off.
5152 -unsafe
5154 A few remote commands are disabled by default (currently:
5156 id:pick, accept:<cmd>, gone:<cmd>, and rawfb:setup:<cmd>)
5157 because they are associated with running external programs. If
5158 you specify -unsafe, then these remote-control commands are
5159 allowed. Note that you can still specify these parameters on
5160 the command line, they just cannot be invoked via remote-con‐
5161 trol.
5162 -safer
5164 Equivalent to: -novncconnect -noremote and prohibiting -gui and
5166 the -connect file. Shuts off communcation channels.
5167 -privremote
5169 Perform some sanity checks and disable remote-control commands
5171 if it appears that the X DISPLAY and/or connectfile can be
5172 accessed by other users. Once remote-control is disabled it
5173 cannot be turned back on.
5174 -nocmds
5176 No external commands (e.g. system(3) , popen(3) , exec(3) )
5178 will be run at all.
5179 -allowedcmds list
5181 list contains a comma separated list of the only external com‐
5183 mands that can be run. The full list of associated options is:
5184 stunnel, ssl, unixpw, WAIT, zeroconf, id, accept, afteraccept,
5186 gone, pipeinput, v4l-info, rawfb-setup, dt, gui, ssh,
5187 storepasswd, passwdfile, custom_passwd, crash.
5188 See each option's help to learn the associated external command.
5190 Note that the -nocmds option takes precedence and disables all
5191 external commands.
5192 -deny_all
5194 For use with -remote nodeny: start out denying all incoming
5196 clients until "-remote nodeny" is used to let them in.
5197 These options are passed to libvncserver:
5199 -rfbport port
5201 TCP port for RFB protocol
5203 -rfbwait time
5205 max time in ms to wait for RFB client
5207 -rfbauth passwd-file
5209 use authentication on RFB protocol (use 'storepasswd' to create
5211 a password file)
5212 -rfbversion 3.x
5214 Set the version of the RFB we choose to advertise
5216 -permitfiletransfer
5218 permit file transfer support
5220 -passwd plain-password
5222 use authentication (use plain-password as password, USE AT YOUR
5224 RISK)
5225 -deferupdate time
5227 time in ms to defer updates (default 40)
5229 -deferptrupdate time
5231 time in ms to defer pointer updates (default none)
5233 -desktop name
5235 VNC desktop name (default "LibVNCServer")
5237 -alwaysshared
5239 always treat new clients as shared
5241 -nevershared
5243 never treat new clients as shared
5245 -dontdisconnect
5247 don't disconnect existing clients when a new non-shared connec‐
5249 tion comes in (refuse new connection instead)
5250 -httpdir dir-path
5252 enable http server using dir-path home
5254 -httpport portnum
5256 use portnum for http connection
5258 -enablehttpproxy
5260 enable http proxy support
5262 -progressive height
5264 enable progressive updating for slow links
5266 -listen ipaddr
5268 listen for connections only on network interface with addr
5270 ipaddr. '-listen localhost' and hostname work too.
5271 libvncserver-tight-extension options:
5273 -disablefiletransfer
5275 disable file transfer
5277 -ftproot string
5279 set ftp root
5281
5283 $HOME/.x11vncrc, $HOME/.Xauthority
5284
5286 DISPLAY, XAUTHORITY, HOME
5287 The following are set for the auxiliary commands run by -accept, -gone
5289 and other cases:
5290 RFB_CLIENT_IP, RFB_CLIENT_PORT, RFB_SERVER_IP, RFB_SERVER_PORT,
5292 RFB_X11VNC_PID, RFB_CLIENT_ID, RFB_CLIENT_COUNT, RFB_MODE RFB_STATE
5293 RFB_LOGIN_VIEWONLY RFB_LOGIN_TIME RFB_CURRENT_TIME RFB_USERNAME
5294 RFB_SSL_CLIENT_CERT
5295
5297 vncviewer(1), vncpasswd(1), vncconnect(1), vncserver(1), Xvnc(1),
5298 xev(1), xdpyinfo(1), xwininfo(1), xprop(1), xmodmap(1), xrandr(1),
5299 Xserver(1), xauth(1), xhost(1), Xsecurity(7), xmessage(1), XGetIm‐
5300 age(3X11), ipcrm(1), inetd(1), xdm(1), gdm(1), kdm(1), ssh(1), stun‐
5301 nel(8), su(1), http://www.tightvnc.com, http://www.realvnc.com,
5302 http://www.karlrunge.com/x11vnc/, http://www.karlrunge.com/x11vnc/#faq
5303
5305 x11vnc was written by Karl J. Runge <runge@karlrunge.com>, it is part
5306 of the LibVNCServer project <http://sf.net/projects/libvncserver>.
5307 This manual page is based one the one written by Ludovic Drolez
5308 <ldrolez@debian.org>, for the Debian project (both may be used by oth‐
5309 ers).
5310x11vnc June 2009 X11VNC(1)