1X11VNC(1) User Commands X11VNC(1)
2
6 x11vnc - allow VNC connections to real X11 displays
7 version: 0.9.16, lastmod: 2019-01-05
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 Use '-auth guess' to have x11vnc use its -findauth mechanism
79 (described below) to try to guess the XAUTHORITY filename and
80 use it.
81 XDM/GDM/KDM: if you are running x11vnc as root and want to find
83 the XAUTHORITY before anyone has logged into an X session yet,
84 use: x11vnc -env FD_XDM=1 -auth guess ... (This will also find
85 the XAUTHORITY if a user is already logged into the X session.)
86 When running as root, FD_XDM=1 will be tried if the initial
87 -auth guess fails.
88 -N
90 If the X display is :N, try to set the VNC display to also be :N
92 This just sets the -rfbport option to 5900+N The program will
93 exit immediately if that port is not available. The -N option
94 only works with normal -display usage, e.g. :0 or :8, -N is
95 ignored in the -display WAIT:..., -create, -find, -svc, -redi‐
96 rect, etc modes.
97 -autoport n
99 Automatically probe for a free VNC port starting at n. The
101 default is to start probing at 5900. Use this to stay away from
102 other VNC servers near 5900.
103 -rfbport str
105 The VNC port to listen on (a LibVNCServer option), e.g. 5900,
107 5901, etc. If specified as "-rfbport PROMPT" then the x11vnc
108 -gui is used to prompt the user to enter the port number.
109 -6
111 IPv6 listening support. In addition to IPv4, the IPv6 address
113 is listened on for incoming connections. The same port number
114 as IPv4 is used.
115 NOTE: This x11vnc binary was compiled to have the "-6" IPv6
117 listening mode ENABLED by default (CPPFLAGS -DX11VNC_LISTEN6=1).
118 So to disable IPv6 listening mode you MUST supply the "-no6"
119 option (see below.)
120 The "-6" mode works for both normal connections and -ssl
122 encrypted ones. Nearly everything is supported for the IPv6
123 case, but there are a few exceptions. See -stunnel for its IPv6
124 support.
125 Currently, for absolutely everything to work correctly the
127 machine may need to have some IPv4 support, at the least for the
128 loopback interface. However, for nearly all usage modes no IPv4
129 support is required. See -noipv4.
130 If you have trouble compiling or running in IPv6 mode, set
132 -DX11VNC_IPV6=0 in CPPFLAGS when configuring to disable IPv6
133 support.
134 -no6
136 Disable IPv6 listening support (only useful if the "-6" mode is
138 compiled in to be the default; see the X11VNC_LISTEN6 descrip‐
139 tion above under "-6".)
140 -noipv6
142 Do not try to use IPv6 for any listening or connecting sockets.
144 This includes both the listening service port(s) and outgoing
145 connections from -connect, -connect_or_exit, or -proxy. Use
146 this if you are having problems due to IPv6.
147 -noipv4
149 Do not try to use IPv4 for any listening or connecting sockets.
151 This is mainly for exploring the behavior of x11vnc on an
152 IPv6-only system, but may have other uses.
153 -reopen
155 If the X server connection is disconnected, try to reopen the X
157 display (up to one time.) This is of use for display managers
158 like GDM (KillInitClients option) that kill x11vnc just after
159 the user logs into the X session. Note: the reopened state may
160 be unstable. Set X11VNC_REOPEN_DISPLAY=n to reopen n times and
161 set X11VNC_REOPEN_SLEEP_MAX to the number of seconds, default
162 10, to keep trying to reopen the display (once per second.)
163 Update: as of 0.9.9, x11vnc tries to automatically avoid being
165 killed by the display manager by delaying creating windows or
166 using XFIXES. So you shouldn't need to use KillInit‐
167 Clients=false as long as you log in quickly enough (within 45
168 seconds of connecting.) You can disable this by setting
169 X11VNC_AVOID_WINDOWS=never. You can also set it to the number
170 of seconds to delay.
171 -reflect host:N
173 Instead of connecting to and polling an X display, connect to
175 the remote VNC server host:N and be a reflector/repeater for it.
176 This is useful for trying to manage the case of many simultane‐
177 ous VNC viewers (e.g. classroom broadcasting) where, e.g. you
178 put a repeater on each network switch, etc, to improve perfor‐
179 mance by distributing the load and network traffic. Implies
180 -shared (use -noshared as a later option to disable). See the
181 discussion below under -rawfb vnc:host:N for more details.
182 -id windowid
184 Show the X window corresponding to windowid not the entire dis‐
186 play. New windows like popup menus, transient toplevels, etc,
187 may not be seen or may be clipped. Disabling SaveUnders or
188 BackingStore in the X server may help show them. x11vnc may
189 crash if the window is initially partially obscured, changes
190 size, is iconified, etc. Some steps are taken to avoid this and
191 the -xrandr mechanism is used to track resizes. Use xwininfo(1)
192 to get the window id, or use "-id pick" to have x11vnc run xwin‐
193 info(1) for you and extract the id. The -id option is useful
194 for exporting very simple applications (e.g. the current view on
195 a webcam).
196 -sid windowid
198 As -id, but instead of using the window directly it shifts a
200 root view to it: this shows SaveUnders menus, etc, although they
201 will be clipped if they extend beyond the window.
202 -appshare
204 Simple application sharing based on the -id/-sid mechanism.
206 Every new toplevel window that the application creates induces a
207 new viewer window via a reverse connection. The -id/-sid and
208 -connect options are required. Run 'x11vnc -appshare -help' for
209 more info.
210 -clip WxH+X+Y
212 Only show the sub-region of the full display that corresponds to
214 the rectangle geometry with size WxH and offset +X+Y. The VNC
215 display has size WxH (i.e. smaller than the full display). This
216 also works for -id/-sid mode where the offset is relative to the
217 upper left corner of the selected window. An example use of
218 this option would be to split a large (e.g. Xinerama) display
219 into two parts to be accessed via separate viewers by running a
220 separate x11vnc on each part.
221 Use '-clip xinerama0' to clip to the first xinerama sub-screen
223 (if xinerama is active). xinerama1 for the 2nd sub-screen, etc.
224 This way you don't need to figure out the WxH+X+Y of the desired
225 xinerama sub-screen. screens are sorted in increasing distance
226 from the (0,0) origin (I.e. not the Xserver's order).
227 -flashcmap
229 In 8bpp indexed color, let the installed colormap flash as the
231 pointer moves from window to window (slow). Also try the -8to24
232 option to avoid flash altogether.
233 -shiftcmap n
235 Rare problem, but some 8bpp displays use less than 256 color‐
237 cells (e.g. 16-color grayscale, perhaps the other bits are used
238 for double buffering) *and* also need to shift the pixels values
239 away from 0, .., ncells. n indicates the shift to be applied to
240 the pixel values. To see the pixel values set DEBUG_CMAP=1 to
241 print out a colormap histogram. Example: -shiftcmap 240
242 -notruecolor
244 For 8bpp displays, force indexed color (i.e. a colormap) even if
246 it looks like 8bpp TrueColor (rare problem).
247 -advertise_truecolor
249 If the X11 display is indexed color, lie to clients when they
251 first connect by telling them it is truecolor. To workaround
252 RealVNC: inPF has colourMap but not 8bpp Use '-advertise_true‐
253 color reset' to reset client fb too.
254 -visual n
256 This option probably does not do what you think. It simply
258 *forces* the visual used for the framebuffer; this may be a bad
259 thing... (e.g. messes up colors or cause a crash). It is useful
260 for testing and for some workarounds. n may be a decimal num‐
261 ber, or 0x hex. Run xdpyinfo(1) for the values. One may also
262 use "TrueColor", etc. see <X11/X.h> for a list. If the string
263 ends in ":m" then for better or for worse the visual depth is
264 forced to be m. You may want to use -noshm when using this
265 option (so XGetImage may automatically translate the pixel
266 data).
267 -overlay
269 Handle multiple depth visuals on one screen, e.g. 8+24 and 24+8
271 overlay visuals (the 32 bits per pixel are packed with 8 for
272 PseudoColor and 24 for TrueColor).
273 Currently -overlay only works on Solaris via XReadScreen(3X11)
275 and IRIX using XReadDisplay(3). On Solaris there is a problem
276 with image "bleeding" around transient popup menus (but not for
277 the menu itself): a workaround is to disable SaveUnders by pass‐
278 ing the "-su" argument to Xsun (in /etc/dt/config/Xservers).
279 Use -overlay as a workaround for situations like these: Some
281 legacy applications require the default visual to be 8bpp
282 (8+24), or they will use 8bpp PseudoColor even when the default
283 visual is depth 24 TrueColor (24+8). In these cases colors in
284 some windows will be incorrect in x11vnc unless -overlay is
285 used. Another use of -overlay is to enable showing the exact
286 mouse cursor shape (details below).
287 Under -overlay, performance will be somewhat slower due to the
289 extra image transformations required. For optimal performance
290 do not use -overlay, but rather configure the X server so that
291 the default visual is depth 24 TrueColor and try to have all
292 apps use that visual (e.g. some apps have -use24 or -visual
293 options).
294 -overlay_nocursor
296 Sets -overlay, but does not try to draw the exact mouse cursor
298 shape using the overlay mechanism.
299 -8to24 [opts]
301 Try this option if -overlay is not supported on your OS, and you
303 have a legacy 8bpp app that you want to view on a multi-depth
304 display with default depth 24 (and is 32 bpp) OR have a default
305 depth 8 display with depth 24 overlay windows for some apps.
306 This option may not work on all X servers and hardware (tested
307 on XFree86/Xorg mga driver and Xsun). The "opts" string is not
308 required and is described below.
309 This mode enables a hack where x11vnc monitors windows within 3
311 levels from the root window. If it finds any that are 8bpp it
312 extracts the indexed color pixel values using XGetImage() and
313 then applies a transformation using the colormap(s) to create
314 TrueColor RGB values that it in turn inserts into bits 1-24 of
315 the framebuffer. This creates a depth 24 "view" of the display
316 that is then exported via VNC.
317 Conversely, for default depth 8 displays, the depth 24 regions
319 are read by XGetImage() and everything is transformed and
320 inserted into a depth 24 TrueColor framebuffer.
321 Note that even if there are *no* depth 24 visuals or windows
323 (i.e. pure 8bpp), this mode is potentially an improvement over
324 -flashcmap because it avoids the flashing and shows each window
325 in the correct color.
326 This method works OK, but may still have bugs and it does hog
328 resources. If there are multiple 8bpp windows using different
329 colormaps, one may have to iconify all but one for the colors to
330 be correct.
331 There may be painting errors for clipping and switching between
333 windows of depths 8 and 24. Heuristics are applied to try to
334 minimize the painting errors. One can also press 3 Alt_L's in a
335 row to refresh the screen if the error does not repair itself.
336 Also the option -fixscreen 8=3.0 or -fixscreen V=3.0 may be used
337 to periodically refresh the screen at the cost of bandwidth
338 (every 3 sec for this example).
339 The [opts] string can contain the following settings. Multiple
341 settings are separated by commas.
342 For for some X servers with default depth 24 a speedup may be
344 achieved via the option "nogetimage". This enables a scheme
345 were XGetImage() is not used to retrieve the 8bpp data.
346 Instead, it assumes that the 8bpp data is in bits 25-32 of the
347 32bit X pixels. There is no requirement that the X server
348 should put the data there for our poll requests, but some do and
349 so the extra steps to retrieve it can be skipped. Tested with
350 mga driver with XFree86/Xorg. For the default depth 8 case this
351 option is ignored.
352 To adjust how often XGetImage() is used to poll the non-default
354 visual regions for changes, use the option "poll=t" where "t" is
355 a floating point time. (default: 0.05)
356 Setting the option "level2" will limit the search for non-
358 default visual windows to two levels from the root window. Do
359 this on slow machines where you know the window manager only
360 imposes one extra window between the app window and the root
361 window.
362 Also for very slow machines use "cachewin=t" where t is a float‐
364 ing point amount of time to cache XGetWindowAttributes results.
365 E.g. cachewin=5.0. This may lead to the windows being unnoticed
366 for this amount of time when deiconifying, painting errors, etc.
367 While testing on a very old SS20 these options gave tolerable
369 response: -8to24 poll=0.2,cachewin=5.0. For this machine -over‐
370 lay is supported and gives better response.
371 Debugging for this mode can be enabled by setting "dbg=1",
373 "dbg=2", or "dbg=3".
374 -24to32
376 Very rare problem: if the framebuffer (X display or -rawfb) is
378 24bpp instead of the usual 32bpp, then dynamically transform the
379 pixels to 32bpp. This will be slower, but can be used to work
380 around problems where VNC viewers cannot handle 24bpp (e.g.
381 "main: setPF: not 8, 16 or 32 bpp?"). See the FAQ for more
382 info.
383 In the case of -rawfb mode, the pixels are directly modified by
385 inserting a 0 byte to pad them out to 32bpp. For X displays, a
386 kludge is done that is equivalent to "-noshm -visual True‐
387 Color:32". (If better performance is needed for the latter,
388 feel free to ask).
389 -scale fraction
391 Scale the framebuffer by factor fraction. Values less than 1
393 shrink the fb, larger ones expand it. Note: the image may not be
394 sharp and response may be slower. If fraction contains a deci‐
395 mal point "." it is taken as a floating point number, alterna‐
396 tively the notation "m/n" may be used to denote fractions
397 exactly, e.g. -scale 2/3
398 To scale asymmetrically in the horizontal and vertical direc‐
400 tions, specify a WxH geometry to stretch to: e.g. '-scale
401 1024x768', or also '-scale 0.9x0.75'
402 Scaling Options: can be added after fraction via ":", to supply
404 multiple ":" options use commas. If you just want a quick,
405 rough scaling without blending, append ":nb" to fraction (e.g.
406 -scale 1/3:nb). No blending is the default for 8bpp indexed
407 color, to force blending for this case use ":fb".
408 To disable -scrollcopyrect and -wirecopyrect under -scale use
410 ":nocr". If you need to to enable them use ":cr" or specify
411 them explicitly on the command line. If a slow link is
412 detected, ":nocr" may be applied automatically. Default: :cr
413 More esoteric options: for compatibility with vncviewers the
415 scaled width is adjusted to be a multiple of 4: to disable this
416 use ":n4". ":in" use interpolation scheme even when shrinking,
417 ":pad" pad scaled width and height to be multiples of scaling
418 denominator (e.g. 3 for 2/3).
419 -geometry WxH
421 Same as -scale WxH
423 -scale_cursor frac
425 By default if -scale is supplied the cursor shape is scaled by
427 the same factor. Depending on your usage, you may want to scale
428 the cursor independently of the screen or not at all. If you
429 specify -scale_cursor the cursor will be scaled by that factor.
430 When using -scale mode to keep the cursor at its "natural" size
431 use "-scale_cursor 1". Most of the ":" scaling options apply
432 here as well.
433 -viewonly
435 All VNC clients can only watch (default off).
437 -shared
439 VNC display is shared, i.e. more than one viewer can connect at
441 the same time (default off).
442 -once
444 Exit after the first successfully connected viewer disconnects,
446 opposite of -forever. This is the Default.
447 -forever
449 Keep listening for more connections rather than exiting as soon
451 as the first client(s) disconnect. Same as -many
452 To get the standard non-shared VNC behavior where when a new VNC
454 client connects the existing VNC client is dropped use: -never‐
455 shared -forever This method can also be used to guard against
456 hung TCP connections that do not go away.
457 -loop
459 Create an outer loop restarting the x11vnc process whenever it
461 terminates. -bg and -inetd are ignored in this mode (however
462 see -loopbg below).
463 Useful for continuing even if the X server terminates and
465 restarts (at that moment the process will need permission to
466 reconnect to the new X server of course).
467 Use, e.g., -loop100 to sleep 100 millisecs between restarts,
469 etc. Default is 2000ms (i.e. 2 secs) Use, e.g. -loop300,5 to
470 sleep 300 ms and only loop 5 times.
471 If -loopbg (plus any numbers) is specified instead, the "-bg"
473 option is implied and the mode approximates inetd(8) usage to
474 some degree. In this case when it goes into the background any
475 listening sockets (i.e. ports 5900, 5800) are closed, so the
476 next one in the loop can use them. This mode will only be of
477 use if a VNC client (the only client for that process) is
478 already connected before the process goes into the background,
479 for example, usage of -display WAIT:.., -svc, and -connect can
480 make use of this "poor man's" inetd mode. The default wait time
481 is 500ms in this mode. This usage could use useful: -svc -bg
482 -loopbg
483 -timeout n
485 Exit unless a client connects within the first n seconds after
487 startup.
488 If there have been no connection attempts after n seconds x11vnc
490 exits immediately. If a client is trying to connect but has not
491 progressed to the normal operating state, x11vnc gives it a few
492 more seconds to finish and exits if it does not make it to the
493 normal state.
494 For reverse connections via -connect or -connect_or_exit a time‐
496 out of n seconds will be set for all reverse connects. If the
497 connect timeout alarm goes off, x11vnc will exit immediately.
498 -sleepin n
500 At startup sleep n seconds before proceeding (e.g. to allow
502 redirs and listening clients to start up)
503 If a range is given: '-sleepin min-max', a random value between
505 min and max is slept. E.g. '-sleepin 0-20' and ´-sleepin 10-30'.
506 Floats are allowed too.
507 -inetd
509 Launched by inetd(8): stdio instead of listening socket. Note:
511 if you are not redirecting stderr to a log file (via shell 2> or
512 -o option) you MUST also specify the -q option, otherwise the
513 stderr goes to the viewer which will cause it to abort. Speci‐
514 fying both -inetd and -q and no -o will automatically close the
515 stderr.
516 -tightfilexfer
518 Enable the TightVNC file transfer extension. Note that that when
520 the -viewonly option is supplied all file transfers are dis‐
521 abled. Also clients that log in viewonly cannot transfer files.
522 However, if the remote control mechanism is used to change the
523 global or per-client viewonly state the filetransfer permissions
524 will NOT change.
525 IMPORTANT: please understand if -tightfilexfer is specified and
527 you run x11vnc as root for, say, inetd or display manager (gdm,
528 kdm, ...) access and you do not have it switch users via the
529 -users option, then VNC Viewers that connect are able to do
530 filetransfer reads and writes as *root*.
531 Also, tightfilexfer is disabled in -unixpw mode.
533 -ultrafilexfer
535 Note: to enable UltraVNC filetransfer and to get it to work you
537 probably need to supply these LibVNCServer options: "-rfbversion
538 3.6 -permitfiletransfer" "-ultrafilexfer" is an alias for this
539 combination.
540 IMPORTANT: please understand if -ultrafilexfer is specified and
542 you run x11vnc as root for, say, inetd or display manager (gdm,
543 kdm, ...) access and you do not have it switch users via the
544 -users option, then VNC Viewers that connect are able to do
545 filetransfer reads and writes as *root*.
546 Note that sadly you cannot do both -tightfilexfer and -ultra‐
548 filexfer at the same time because the latter requires setting
549 the version to 3.6 and tightvnc will not do filetransfer when it
550 sees that version number.
551 -http
553 Instead of using -httpdir (see below) to specify where the Java
555 vncviewer applet is, have x11vnc try to *guess* where the direc‐
556 tory is by looking relative to the program location and in stan‐
557 dard locations (/usr/local/share/x11vnc/classes, etc). Under
558 -ssl or -stunnel the ssl classes subdirectory is sought.
559 -http_ssl
561 As -http, but force lookup for ssl classes subdir.
563 Note that for HTTPS, single-port Java applet delivery you can
565 set X11VNC_HTTPS_DOWNLOAD_WAIT_TIME to the max number of seconds
566 to wait for the applet download to finish. The default is 15.
567 -avahi
569 Use the Avahi/mDNS ZeroConf protocol to advertise this VNC
571 server to the local network. (Related terms: Rendezvous, Bon‐
572 jour). Depending on your setup, you may need to start avahi-
573 daemon and open udp port 5353 in your firewall.
574 You can set X11VNC_AVAHI_NAME, X11VNC_AVAHI_HOST, and/or
576 X11VNC_AVAHI_PORT environment variables to override the default
577 values. For example: -env X11VNC_AVAHI_NAME=wally
578 If the avahi API cannot be found at build time, a helper program
580 like avahi- publish(1) or dns- sd(1) will be tried
581 -mdns
583 Same as -avahi.
585 -zeroconf
587 Same as -avahi.
589 -connect string
591 For use with "vncviewer -listen" reverse connections. If string
593 has the form "host" or "host:port" the connection is made once
594 at startup.
595 Use commas for a list of host's and host:port's. E.g. -connect
597 host1,host2 or host1:0,host2:5678. Note that to reverse connect
598 to multiple hosts at the same time you will likely need to also
599 supply: -shared
600 Note that unlike most vnc servers, x11vnc will require a pass‐
602 word for reverse as well as for forward connections. (provided
603 password auth has been enabled, -rfbauth, etc) If you do not
604 want to require a password for reverse connections set
605 X11VNC_REVERSE_CONNECTION_NO_AUTH=1 in your environment before
606 starting x11vnc.
607 If string contains "/" it is instead interpreted as a file to
609 periodically check for new hosts. The first line is read and
610 then the file is truncated. Be careful about the location of
611 this file if x11vnc is running as root (e.g. via gdm(1) , etc).
612 Repeater mode: Some services provide an intermediate "vnc
614 repeater": http://www.uvnc.com/addons/repeater.html (and also
615 http://koti.mbnet.fi/jtko/ for linux port) that acts as a
616 proxy/gateway. Modes like these require an initial string to be
617 sent for the reverse connection before the VNC protocol is
618 started. Here are the ways to do this:
619 -connect pre=some_string+host:port -connect
621 pre128=some_string+host:port -connect repeater=ID:1234+host:port
622 -connect repeater=23.45.67.89::5501+host:port
623 SSVNC notation is also supported:
625 -connect repeater://host:port+ID:1234
627 As with normal -connect usage, if the repeater port is not sup‐
629 plied 5500 is assumed.
630 The basic idea is between the special tag, e.g. "pre=" and "+"
632 is the pre-string to be sent. Note that in this case host:port
633 is the repeater server, NOT the vnc viewer. Somehow the pre-
634 string tells the repeater server how to find the vnc viewer and
635 connect you to it.
636 In the case pre=some_string+host:port, "some_string" is simply
638 sent. In the case preNNN=some_string+host:port "some_string" is
639 sent in a null padded buffer of length NNN. repeater= is the
640 same as pre250=, this is the ultravnc repeater buffer size.
641 Strings like "\n" and "\r", etc. are expanded to newline and
643 carriage return. "\c" is expanded to "," since the connect
644 string is comma separated.
645 See also the -proxy option below for additional ways to plumb
647 reverse connections.
648 Reverse SSL: using -connect in -ssl mode makes x11vnc act as an
650 SSL client (initiates SSL connection) rather than an SSL server.
651 The idea is x11vnc might be connecting to stunnel on the viewer
652 side with the viewer in listening mode. If you do not want this
653 behavior, use -env X11VNC_DISABLE_SSL_CLIENT_MODE=1. With this
654 the viewer side can act as the SSL client as it normally does
655 for forward connections.
656 Reverse SSL Repeater mode: This will work, but note that if the
658 VNC Client does any sort of a 'Fetch Cert' action before con‐
659 necting, then the Repeater will likely drop the connection and
660 both sides will need to restart. Consider the use of -con‐
661 nect_or_exit and -loop300,2 to have x11vnc reconnect once to the
662 repeater after the fetch. You will probably also want to supply
663 -sslonly to avoid x11vnc thinking the delay in response means
664 the connection is VeNCrypt. The env var X11VNC_DIS‐
665 ABLE_SSL_CLIENT_MODE=1 discussed above may also be useful (i.e.
666 the viewer can do a forward connection as it normally does.)
667 IPv6: as of x11vnc 0.9.10 the -connect option should connect to
669 IPv6 hosts properly. If there are problems you can disable IPv6
670 by setting -DX11VNC_IPV6=0 in CPPFLAGS when configuring. If
671 there problems connecting to IPv6 hosts consider a relay like
672 the included inet6to4 script or the -proxy option.
673 -connect_or_exit str
675 As with -connect, except if none of the reverse connections suc‐
677 ceed, then x11vnc shuts down immediately
678 An easier to type alias for this option is '-coe'
680 By the way, if you do not want x11vnc to listen on ANY interface
682 use -rfbport 0 which is handy for the -connect_or_exit mode.
683 -proxy string
685 Use proxy in string (e.g. host:port) as a proxy for making
687 reverse connections (-connect or -connect_or_exit options).
688 Web proxies are supported, but note by default most of them only
690 support destination connections to ports 443 or 563, so this
691 might not be very useful (the viewer would need to listen on
692 that port or the router would have to do a port redirection).
693 A web proxy may be specified by either "host:port" or
695 "http://host:port" (the port is required even if it is the com‐
696 mon choices 80 or 8080)
697 SOCKS4, SOCKS4a, and SOCKS5 are also supported. SOCKS proxies
699 normally do not have restrictions on the destination port num‐
700 ber.
701 Use a format like this: socks://host:port or socks5://host:port.
703 Note that ssh -D does not support SOCKS4a, so use socks5://.
704 For socks:// SOCKS4 is used on a numerical IP and "localhost",
705 otherwise SOCKS4a is used (and so the proxy tries to do the DNS
706 lookup).
707 An experimental mode is "-proxy http://host:port/..." Note the
709 "/" after the port that distinguishes it from a normal web
710 proxy. The port must be supplied even if it is the default 80.
711 For this mode a GET is done to the supplied URL with the string
712 host=H&port=P appended. H and P will be the -connect reverse
713 connect host and port. Use the string "__END__" to disable the
714 appending. The basic idea here is that maybe some cgi script
715 provides the actual viewer hookup and tunnelling. How to actu‐
716 ally achieve this within cgi, php, etc. is not clear... A cus‐
717 tom web server or apache module would be straight-forward.
718 Another experimental mode is "-proxy ssh://user@host" in which
720 case a SSH tunnel is used for the proxying. "user@" is not
721 needed unless your unix username is different on "host". For a
722 non-standard SSH port use ssh://user@host:port. If proxies are
723 chained (see next paragraph) then the ssh one must be the first
724 one. If ssh-agent is not active, then the ssh password needs to
725 be entered in the terminal where x11vnc is running. Examples:
726 -connect localhost:0 -proxy ssh://me@friends-pc:2222
728 -connect snoopy:0 -proxy ssh://ssh.company.com
730 Multiple proxies may be chained together in case one needs to
732 ricochet off of a number of hosts to finally reach the VNC
733 viewer. Up to 3 may be chained, separate them by commas in the
734 order they are to be connected to. E.g.:
735 http://host1:port1,socks5://host2:port2 or three like:
736 first,second,third
737 IPv6: as of x11vnc 0.9.10 the -proxy option should connect to
739 IPv6 hosts properly. If there are problems you can disable IPv6
740 by setting -DX11VNC_IPV6=0 in CPPFLAGS when configuring. If
741 there problems connecting to IPv6 hosts consider a relay like
742 the included inet6to4 script.
743 -vncconnect, -novncconnect
745 Monitor the VNC_CONNECT X property set by the standard VNC pro‐
747 gram vncconnect(1). When the property is set to "host" or
748 "host:port" establish a reverse connection. Using xprop(1)
749 instead of vncconnect may work (see the FAQ). The -remote con‐
750 trol mechanism uses X11VNC_REMOTE channel, and this option dis‐
751 ables/enables it as well. Default: -vncconnect
752 To use different names for these X11 properties (e.g. to have
754 separate communication channels for multiple x11vnc's on the
755 same display) set the VNC_CONNECT or X11VNC_REMOTE env. vars. to
756 the string you want, for example: -env
757 X11VNC_REMOTE=X11VNC_REMOTE_12345 Both sides of the channel must
758 use the same unique name. The same can be done for the internal
759 X11VNC_TICKER property (heartbeat and timestamp) if desired.
760 -allow host1[,host2..]
762 Only allow client connections from hosts matching the comma sep‐
764 arated list of hostnames or IP addresses. Can also be a numeri‐
765 cal IP prefix, e.g. "192.168.100." to match a simple subnet,
766 for more control build LibVNCServer with libwrap support (See
767 the FAQ). If the list contains a "/" it instead is a inter‐
768 preted as a file containing addresses or prefixes that is re-
769 read each time a new client connects. Lines can be commented
770 out with the "#" character in the usual way.
771 -allow applies in -ssl mode, but not in -stunnel mode.
773 IPv6: as of x11vnc 0.9.10 a host can be specified in IPv6 numer‐
775 ical format, e.g. 2001:4860:b009::93.
776 -localhost
778 Basically the same as "-allow 127.0.0.1".
780 Note: if you want to restrict which network interface x11vnc
782 listens on, see the -listen option below. E.g. "-listen local‐
783 host" or "-listen 192.168.3.21". As a special case, the option
784 "-localhost" implies "-listen localhost".
785 A rare case, but for non-localhost -listen usage, if you use the
787 remote control mechanism (-R) to change the -listen interface
788 you may need to manually adjust the -allow list (and vice versa)
789 to avoid situations where no connections (or too many) are
790 allowed.
791 If you do not want x11vnc to listen on ANY interface (evidently
793 you are using -connect or -connect_or_exit, or plan to use
794 remote control: -R connect:host), use -rfbport 0
795 IPv6: if IPv6 is supported, this option automatically implies
797 the IPv6 loopback address '::1' as well.
798 -unixsock str
800 Listen on the unix socket (AF_UNIX) 'str' for connections. This
802 mode is for either local connections or a tunnel endpoint where
803 one wants the file permission of the unix socket file to deter‐
804 mine what can connect to it. (This currently requires an edit
805 to libvnserver/rfbserver.c: comment out lines 310 and 311,
806 'close(sock)' and 'return NULL' in rfbserver.c after the set‐
807 sockopt() call.) Note that to disable all tcp listening ports
808 specify '-rfbport 0' and should be useful with this mode. Exam‐
809 ple: mkdir ~/s; chmod 700 ~/s; x11vnc -unixsock ~/s/mysock -rfb‐
810 port 0 ... The SSVNC unix vncviewer can connect to unix sock‐
811 ets.
812 -listen6 str
814 When in IPv6 listen mode "-6", listen only on the network inter‐
816 face with address str. It also works for link scope addresses
817 (fe80::219:dbff:fee5:3f92%eth0) and IPv6 hostname strings (e.g.
818 ipv6.google.com.) Use LibVNCServer -listen option for the IPv4
819 interface.
820 -nolookup
822 Do not use gethostbyname() or gethostbyaddr() to look up host
824 names or IP numbers. Use this if name resolution is incorrectly
825 set up and leads to long pauses as name lookups time out, etc.
826 -input string
828 Fine tuning of allowed user input. If string does not contain a
830 comma "," the tuning applies only to normal clients. Otherwise
831 the part before "," is for normal clients and the part after for
832 view-only clients. "K" is for Keystroke input, "M" for Mouse-
833 motion input, "B" for Button-click input, "C" is for Clipboard
834 input, and "F" is for File transfer (ultravnc only). Their
835 presence in the string enables that type of input. E.g. "-input
836 M" means normal users can only move the mouse and "-input
837 KMBCF,M" lets normal users do anything and enables view-only
838 users to move the mouse. This option is ignored when a global
839 -viewonly is in effect (all input is discarded in that case).
840 -grabkbd
842 When VNC viewers are connected, attempt to the grab the keyboard
844 so a (non-malicious) user sitting at the physical display is not
845 able to enter keystrokes. This method uses XGrabKeyboard(3X11)
846 and so it is not secure and does not rule out the person at the
847 physical display injecting keystrokes by flooding the server
848 with them, grabbing the keyboard himself, etc. Some degree of
849 cooperation from the person at the display is assumed. This is
850 intended for remote help-desk or educational usage modes.
851 Note: on some recent (12/2010) X servers and/or desktops,
853 -grabkbd no longer works: it prevents the window manager from
854 resizing windows and similar things. Try -ungrabboth below
855 (might not work.)
856 -grabptr
858 As -grabkbd, but for the mouse pointer using XGrabPointer(3X11).
860 Unfortunately due to the way the X server works, the mouse can
861 still be moved around by the user at the physical display, but
862 he will not be able to change window focus with it. Also some
863 window managers that call XGrabServer(3X11) for resizes, etc,
864 will act on the local user's input. Again, some degree of coop‐
865 eration from the person at the display is assumed.
866 -ungrabboth
868 Whenever there is any input (either keyboard or pointer), ungrab
870 *both* the keyboard and the pointer while injecting the syn‐
871 thetic input. This is to allow window managers, etc. a chance
872 to grab.
873 -grabalways
875 Apply both -grabkbd and -grabptr even when no VNC viewers are
877 connected. If you only want one of them, use the -R remote con‐
878 trol to turn the other back on, e.g. -R nograbptr.
879 -viewpasswd string
881 Supply a 2nd password for view-only logins. The -passwd (full-
883 access) password must also be supplied.
884 -passwdfile filename
886 Specify the LibVNCServer password via the first line of the file
888 filename (instead of via -passwd on the command line where oth‐
889 ers might see it via ps(1) ).
890 See the descriptions below for how to supply multiple passwords,
892 view-only passwords, to specify external programs for the
893 authentication, and other features.
894 If the filename is prefixed with "rm:" it will be removed after
896 being read. Perhaps this is useful in limiting the readability
897 of the file. In general, the password file should not be read‐
898 able by untrusted users (BTW: neither should the VNC -rfbauth
899 file: it is NOT encrypted, only obscured with a fixed key).
900 If the filename is prefixed with "read:" it will periodically be
902 checked for changes and reread. It is guaranteed to be reread
903 just when a new client connects so that the latest passwords
904 will be used.
905 If filename is prefixed with "cmd:" then the string after the
907 ":" is run as an external command: the output of the command
908 will be interpreted as if it were read from a password file (see
909 below). If the command does not exit with 0, then x11vnc termi‐
910 nates immediately. To specify more than 1000 passwords this way
911 set X11VNC_MAX_PASSWDS before starting x11vnc. The environment
912 variables are set as in -accept.
913 Note that due to the VNC protocol only the first 8 characters of
915 a password are used (DES key).
916 If filename is prefixed with "custom:" then a custom password
918 checker is supplied as an external command following the ":".
919 The command will be run when a client authenticates. If the
920 command exits with 0 the client is accepted, otherwise it is
921 rejected. The environment variables are set as in -accept.
922 The standard input to the custom command will be a decimal digit
924 "len" followed by a newline. "len" specifies the challenge size
925 and is usually 16 (the VNC spec). Then follows len bytes which
926 is the random challenge string that was sent to the client. This
927 is then followed by len more bytes holding the client's response
928 (i.e. the challenge string encrypted via DES with the user pass‐
929 word in the standard situation).
930 The "custom:" scheme can be useful to implement dynamic pass‐
932 words or to implement methods where longer passwords and/or dif‐
933 ferent encryption algorithms are used. The latter will require
934 customizing the VNC client as well. One could create an MD5SUM
935 based scheme for example.
936 File format for -passwdfile:
938 If multiple non-blank lines exist in the file they are all taken
940 as valid passwords. Blank lines are ignored. Password lines
941 may be "commented out" (ignored) if they begin with the charac‐
942 ter "#" or the line contains the string "__SKIP__". Lines may
943 be annotated by use of the "__COMM__" string: from it to the end
944 of the line is ignored. An empty password may be specified via
945 the "__EMPTY__" string on a line by itself (note your viewer
946 might not accept empty passwords).
947 If the string "__BEGIN_VIEWONLY__" appears on a line by itself,
949 the remaining passwords are used for viewonly access. For com‐
950 patibility, as a special case if the file contains only two
951 password lines the 2nd one is automatically taken as the
952 viewonly password. Otherwise the "__BEGIN_VIEWONLY__" token
953 must be used to have viewonly passwords. (tip: make the 3rd and
954 last line be "__BEGIN_VIEWONLY__" to have 2 full-access pass‐
955 words)
956 -showrfbauth filename
958 Print to the screen the obscured VNC password kept in the
960 rfbauth file filename and then exit.
961 -unixpw [list]
963 Use Unix username and password authentication. x11vnc will use
965 the su(1) program to verify the user's password. [list] is an
966 optional comma separated list of allowed Unix usernames. If the
967 [list] string begins with the character "!" then the entire list
968 is taken as an exclude list. See below for per-user options
969 that can be applied.
970 A familiar "login:" and "Password:" dialog is presented to the
972 user on a black screen inside the vncviewer. The connection is
973 dropped if the user fails to supply the correct password in 3
974 tries or does not send one before a 45 second timeout. Existing
975 clients are view-only during this period.
976 If the first character received is "Escape" then the unix user‐
978 name will not be displayed after "login:" as it is typed. This
979 could be of use for VNC viewers that automatically type the
980 username and password.
981 Since the detailed behavior of su(1) can vary from OS to OS and
983 for local configurations, test the mode before deployment to
984 make sure it is working properly. x11vnc will attempt to be
985 conservative and reject a login if anything abnormal occurs.
986 One case to note: FreeBSD and the other BSD's by default it is
988 impossible for the user running x11vnc to validate his *own*
989 password via su(1) (commenting out the pam_self.so entry in
990 /etc/pam.d/su eliminates this behavior). So the x11vnc login
991 will always *FAIL* for this case (even when the correct password
992 is supplied).
993 A possible workaround for this on *BSD would be to start x11vnc
995 as root with the "-users +nobody" option to immediately switch
996 to user nobody where the su'ing will proceed normally.
997 Another source of potential problems are PAM modules that prompt
999 for extra info, e.g. password aging modules. These logins will
1000 fail as well even when the correct password is supplied.
1001 **IMPORTANT**: to prevent the Unix password being sent in *clear
1003 text* over the network, one of two schemes will be enforced: 1)
1004 the -ssl builtin SSL mode, or 2) require both -localhost and
1005 -stunnel be enabled.
1006 Method 1) ensures the traffic is encrypted between viewer and
1008 server. A PEM file will be required, see the discussion under
1009 -ssl below (under some circumstances a temporary one can be
1010 automatically generated).
1011 Method 2) requires the viewer connection to appear to come from
1013 the same machine x11vnc is running on (e.g. from a ssh -L port
1014 redirection). And that the -stunnel SSL mode be used for
1015 encryption over the network. (see the description of -stunnel
1016 below).
1017 Note: as a convenience, if you ssh(1) in and start x11vnc it
1019 will check if the environment variable SSH_CONNECTION is set and
1020 appears reasonable. If it does, then the -ssl or -stunnel
1021 requirement will be dropped since it is assumed you are using
1022 ssh for the encrypted tunnelling. -localhost is still enforced.
1023 Use -ssl or -stunnel to force SSL usage even if SSH_CONNECTION
1024 is set.
1025 To override the above restrictions you can set environment vari‐
1027 ables before starting x11vnc:
1028 Set UNIXPW_DISABLE_SSL=1 to disable requiring either -ssl or
1030 -stunnel (as under SSH_CONNECTION.) Evidently you will be using
1031 a different method to encrypt the data between the vncviewer and
1032 x11vnc: perhaps ssh(1) or an IPSEC VPN. -localhost is still
1033 enforced (however, see the next paragraph.)
1034 Set UNIXPW_DISABLE_LOCALHOST=1 to disable the -localhost
1036 requirement in -unixpw modes. One should never do this (i.e.
1037 allow the Unix passwords to be sniffed on the network.) This
1038 also disables the localhost requirement for reverse connections
1039 (see below.)
1040 Note that use of -localhost with ssh(1) (and no -unixpw) is
1042 roughly the same as requiring a Unix user login (since a Unix
1043 password or the user's public key authentication is used by sshd
1044 on the machine where x11vnc runs and only local connections from
1045 that machine are accepted).
1046 Regarding reverse connections (e.g. -R connect:host and -connect
1048 host), when the -localhost constraint is in effect then reverse
1049 connections can only be used to connect to the same machine
1050 x11vnc is running on (default port 5500). Please use a ssh or
1051 stunnel port redirection to the viewer machine to tunnel the
1052 reverse connection over an encrypted channel.
1053 In -inetd mode the Method 1) will be enforced (not Method 2).
1055 With -ssl in effect reverse connections are disabled. If you
1056 override this via env. var, be sure to also use encryption from
1057 the viewer to inetd. Tip: you can also have your own stunnel
1058 spawn x11vnc in -inetd mode (thereby bypassing inetd). See the
1059 FAQ for details.
1060 The user names in the comma separated [list] may have per-user
1062 options after a ":", e.g. "fred:opts" where "opts" is a "+" sep‐
1063 arated list of "viewonly", "fullaccess", "input=XXXX", or
1064 "deny", e.g. "karl,wally:viewonly,boss:input=M". For "input="
1065 it is the K,M,B,C described under -input.
1066 If an item in the list is "*" that means those options apply to
1068 all users. It ALSO implies all users are allowed to log in
1069 after supplying a valid password. Use "deny" to explicitly deny
1070 some users if you use "*" to set a global option. If [list]
1071 begins with the "!" character then "*" is ignored for checking
1072 if the user is allowed, but the option values associated with it
1073 do apply as normal.
1074 There are also some utilities for checking passwords if [list]
1076 starts with the "%" character. See the quick_pw() function for
1077 more details. Description: "%-" or "%stdin" means read one line
1078 from stdin. "%env" means it is in $UNIXPW env var. A leading
1079 "%/" or "%." means read the first line from the filename that
1080 follows after the % character. % by itself means prompt for the
1081 username and password. Otherwise: %user:pass E.g. -unixpw
1082 %fred:swordfish For the other cases user:pass is read from the
1083 indicated source. If the password is correct 'Y user' is
1084 printed and the program exit code is 0. If the password is
1085 incorrect it prints 'N user' and the exit code is 1. If there
1086 is some other error the exit code is 2. This feature enables
1087 x11vnc to be a general unix user password checking tool; it
1088 could be used from scripts or other programs. These % password
1089 checks also apply to the -unixpw_nis and -unixpw_cmd options.
1090 For the % password check, if the env. var. UNIXPW_CMD is set to
1092 a command then it is run as the user (assuming the password is
1093 correct.) The output of the command is not printed, the program
1094 or script must manage that by some other means. The exit code
1095 of x11vnc will depend on the exit code of the command that is
1096 run.
1097 Use -nounixpw to disable unixpw mode if it was enabled earlier
1099 in the cmd line (e.g. -svc mode)
1100 -unixpw_nis [list]
1102 As -unixpw above, however do not use su(1) but rather use the
1104 traditional getpwnam(3) + crypt(3) method to verify passwords.
1105 All of the above -unixpw options and constraints apply.
1106 This mode requires that the encrypted passwords be readable.
1108 Encrypted passwords stored in /etc/shadow will be inaccessible
1109 unless x11vnc is run as root.
1110 This is called "NIS" mode simply because in most NIS setups user
1112 encrypted passwords are accessible (e.g. "ypcat passwd") by an
1113 ordinary user and so that user can authenticate ANY user.
1114 NIS is not required for this mode to work (only that getpwnam(3)
1116 return the encrypted password is required), but it is unlikely
1117 it will work (as an ordinary user) for most modern environments
1118 unless NIS is available. On the other hand, when x11vnc is run
1119 as root it will be able to to access /etc/shadow even if NIS is
1120 not available (note running as root is often done when running
1121 x11vnc from inetd and xdm/gdm/kdm).
1122 Looked at another way, if you do not want to use the su(1)
1124 method provided by -unixpw (i.e. su_verify()), you can run
1125 x11vnc as root and use -unixpw_nis. Any users with passwords in
1126 /etc/shadow can then be authenticated.
1127 In -unixpw_nis mode, under no circumstances is x11vnc's user
1129 password verifying function based on su called (i.e. the func‐
1130 tion su_verify() that runs /bin/su in a pseudoterminal to verify
1131 passwords.) However, if -unixpw_nis is used in conjunction with
1132 the -find and -create -display WAIT:... modes then, if x11vnc is
1133 running as root, /bin/su may be called externally to run the
1134 find or create commands.
1135 -unixpw_cmd cmd
1137 As -unixpw above, however do not use su(1) but rather run the
1139 externally supplied command cmd. The first line of its stdin
1140 will be the username and the second line the received password.
1141 If the command exits with status 0 (success) the VNC user will
1142 be accepted. It will be rejected for any other return status.
1143 Dynamic passwords and non-unix passwords, e.g. LDAP, can be
1145 implemented this way by providing your own custom helper pro‐
1146 gram. Note that the remote viewer is given 3 tries to enter the
1147 correct password, and so the program may be called in a row that
1148 many (or more) times.
1149 If a list of allowed users is needed to limit who can log in,
1151 use -unixpw [list] in addition to this option.
1152 In FINDDISPLAY and FINDCREATEDISPLAY modes the cmd will also be
1154 run with the RFB_UNIXPW_CMD_RUN env. var. non-empty and set to
1155 the corresponding display find/create command. The first two
1156 lines of input are the username and passwd as in the normal case
1157 described above. To support FINDDISPLAY and FINDCREATEDISPLAY,
1158 cmd should run the requested command as the user (and most
1159 likely refusing to run it if the password is not correct.) Here
1160 is an example script (note it has a hardwired bogus password
1161 "abc"!)
1162 #!/bin/sh # Example x11vnc -unixpw_cmd script. # Read the first
1164 two lines of stdin (user and passwd) read user read pass
1165 debug=0 if [ $debug = 1 ]; then echo "user: $user" 1>&2 echo
1167 "pass: $pass" 1>&2 env | egrep -i 'rfb|vnc' 1>&2 fi
1168 # Check if the password is valid. # (A real example would use
1170 ldap lookup, etc!) if [ "X$pass" != "Xabc" ]; then exit 1 #
1171 incorrect password fi
1172 if [ "X$RFB_UNIXPW_CMD_RUN" = "X" ]; then exit 0 # correct
1174 password else # Run the requested command (finddisplay) if [
1175 $debug = 1 ]; then echo "run: $RFB_UNIXPW_CMD_RUN" 1>&2 fi exec
1176 /bin/su - "$user" -c "$RFB_UNIXPW_CMD_RUN" fi
1177 In -unixpw_cmd mode, under no circumstances is x11vnc's user
1179 password verifying function based on su called (i.e. the func‐
1180 tion su_verify() that runs /bin/su in a pseudoterminal to verify
1181 passwords.) It is up to the supplied unixpw_cmd to do user
1182 switching if desired and if it has the permissions to do so.
1183 -find
1185 Find the user's display using FINDDISPLAY. This is an alias for
1187 "-display WAIT:cmd=FINDDISPLAY".
1188 Note: if a -display occurs later on the command line it will
1190 override the -find setting.
1191 For this and the next few options see -display WAIT:... below
1193 for all of the details.
1194 -finddpy
1196 Run the FINDDISPLAY program, print out the found display (if
1198 any) and exit. Output is like: DISPLAY=:0.0 DIS‐
1199 PLAY=:0.0,XPID=12345 or DISPLAY=:0.0,VT=7. XPID is the process
1200 ID of the found X server. VT is the Linux virtual terminal of
1201 the X server.
1202 -listdpy
1204 Have the FINDDISPLAY program list all of your displays (i.e. all
1206 the X displays on the local machine that you have access rights
1207 to). x11vnc then exits.
1208 -findauth [disp]
1210 Apply the -find/-finddpy heuristics to try to guess the XAUTHOR‐
1212 ITY file for DISPLAY 'disp'. If 'disp' is not supplied, then
1213 the value in the -display on the cmdline is used; failing that
1214 $DISPLAY is used; and failing that ":0" is used. x11vnc then
1215 exits.
1216 If nothing is printed out, that means no XAUTHORITY was found
1218 for 'disp'; i.e. failure. If "XAUTHORITY=" is printed out, that
1219 means use the default (i.e. do not set XAUTHORITY). If "XAU‐
1220 THORITY=/path/to/file" is printed out, then use that file.
1221 XDM/GDM/KDM: if you are running x11vnc as root and want to find
1223 the XAUTHORITY before anyone has logged into an X session yet,
1224 use: x11vnc -env FD_XDM=1 -findauth ... (This will also find
1225 the XAUTHORITY if a user is already logged into the X session.)
1226 When running as root, FD_XDM=1 will be tried if the initial
1227 -findauth fails.
1228 -create
1230 First try to find the user's display using FINDDISPLAY, if that
1232 doesn't succeed create an X session via the FINDCREATEDISPLAY
1233 method. This is an alias for "-display WAIT:cmd=FINDCREATEDIS‐
1234 PLAY-Xvfb".
1235 Note: if a -display occurs later on the command line it will
1237 override the -create setting.
1238 SSH NOTE: for both -find and -create you can (should!) add the
1240 "-localhost" option to force SSH tunnel access.
1241 -xdummy
1243 As in -create, except Xdummy instead of Xvfb.
1245 -xvnc
1247 As in -create, except Xvnc instead of Xvfb.
1249 -xvnc_redirect
1251 As in -create, except Xvnc.redirect instead of Xvfb.
1253 -xdummy_xvfb
1255 Sets WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb
1257 -create_xsrv str
1259 Sets WAIT:cmd=FINDCREATEDISPLAY-<str> Can be on cmdline after
1261 anything that sets WAIT:.. and other things (e.g. -svc, -xdmsvc)
1262 to adjust the X server list. Example: -svc ... -create_xsrv
1263 Xdummy,X
1264 -svc
1266 Terminal services mode based on SSL access. Alias for -display
1268 WAIT:cmd=FINDCREATEDISPLAY-Xvfb -unixpw -users unixpw= -ssl SAVE
1269 Also "-service".
1270 Note: if a -display, -unixpw, -users, or -ssl occurs later on
1272 the command line it will override the -svc setting.
1273 -svc_xdummy
1275 As -svc except Xdummy instead of Xvfb.
1277 -svc_xvnc
1279 As -svc except Xvnc instead of Xvfb.
1281 -svc_xdummy_xvfb
1283 As -svc with Xdummy,Xvfb.
1285 -xdmsvc
1287 Display manager Terminal services mode based on SSL. Alias for
1289 -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -unixpw -users
1290 unixpw= -ssl SAVE Also "-xdm_service".
1291 Note: if a -display, -unixpw, -users, or -ssl occurs later on
1293 the command line it will override the -xdmsvc setting.
1294 To create a session a user will have to first log in to the
1296 -unixpw dialog and then log in again to the XDM/GDM/KDM prompt.
1297 Subsequent re-connections will only require the -unixpw pass‐
1298 word. See the discussion under -display WAIT:... for more
1299 details about XDM, etc configuration.
1300 Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc
1302 configuration file. See -display WAIT: for more info.
1303 -sshxdmsvc
1305 Display manager Terminal services mode based on SSH. Alias for
1307 -display WAIT:cmd=FINDCREATEDISPLAY-Xvfb.xdmcp -localhost.
1308 The -localhost option constrains connections to come in via a
1310 SSH tunnel (which will require a login). To create a session a
1311 user will also have to log into the XDM GDM KDM prompt. Subse‐
1312 quent re-connections will only only require the SSH login. See
1313 the discussion under -display WAIT:... for more details about
1314 XDM, etc configuration.
1315 Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc
1317 configuration file. See -display WAIT: for more info.
1318 -unixpw_system_greeter
1320 Present a "Press 'Escape' for System Greeter" option to the con‐
1322 necting VNC client in combined -unixpw and xdmcp FINDCREATEDIS‐
1323 PLAY modes (e.g. -xdmsvc).
1324 Normally in a -unixpw mode the VNC client must supply a valid
1326 username and password to gain access. However, if -unixpw_sys‐
1327 tem_greeter is supplied AND the FINDCREATEDISPLAY command
1328 matches 'xdmcp', then the user has the option to press Escape
1329 and then get a XDM/GDM/KDM login/greeter panel instead. They
1330 will then supply a username and password directly to the
1331 greeter.
1332 Otherwise, in xdmcp FINDCREATEDISPLAY mode the user must supply
1334 his username and password TWICE. First to the initial unixpw
1335 login dialog, and second to the subsequent XDM/GDM/KDM greeter.
1336 Note that if the user re-connects and supplies his username and
1337 password in the unixpw dialog the xdmcp greeter is skipped and
1338 he is connected directly to his existing X session. So the
1339 -unixpw_system_greeter option avoids the extra password at X
1340 session creation time.
1341 Example: x11vnc -xdmsvc -unixpw_system_greeter See -unixpw and
1343 -display WAIT:... for more info.
1344 The special options after a colon at the end of the username
1346 (e.g. user:solid) described under -display WAIT: are also
1347 applied in this mode if they are typed in before the user hits
1348 Escape. The username is ignored but the colon options are not.
1349 The default message is 2 lines in a small font, set the env.
1351 var. X11VNC_SYSTEM_GREETER1=true for a 1 line message in a
1352 larger font.
1353 If the user pressed Escape the FINDCREATEDISPLAY command will be
1355 run with the env. var. X11VNC_XDM_ONLY=1.
1356 Remember to enable XDMCP in the xdm-config, gdm.conf, or kdmrc
1358 configuration file. See -display WAIT: for more info.
1359 -redirect port
1361 As in FINDCREATEDISPLAY-Xvnc.redirect mode except redirect imme‐
1363 diately (i.e. without X session finding or creation) to a VNC
1364 server listening on port. You can also supply host:port to redi‐
1365 rect to a different machine.
1366 If 0 <= port < 200 it is taken as a VNC display (5900 is added
1368 to get the actual port), if port < 0 then -port is used.
1369 Probably the only reason to use the -redirect option is in con‐
1371 junction with SSL support, e.g. -ssl SAVE. This provides an
1372 easy way to add SSL encryption to a VNC server that does not
1373 support SSL (e.g. Xvnc or vnc.so) In fact, the protocol does not
1374 even need to be VNC, and so "-rfbport port1 -ssl SAVE -redirect
1375 host:port2" can act as a replacement for stunnel(1).
1376 This mode only allows one redirected connection. The -forever
1378 option does not apply. Use -inetd or -loop for persistent ser‐
1379 vice.
1380 -display WAIT:...
1382 A special usage mode for the normal -display option. Useful
1384 with -unixpw, but can be used independently of it. If the dis‐
1385 play string begins with WAIT: then x11vnc waits until a VNC
1386 client connects before opening the X display (or -rawfb device).
1387 This could be useful for delaying opening the display for cer‐
1389 tain usage modes (say if x11vnc is started at boot time and no X
1390 server is running or users logged in yet).
1391 If the string is, e.g. WAIT:0.0 or WAIT:1, i.e. "WAIT" in front
1393 of a normal X display, then that indicated display is used.
1394 One can also insert a geometry between colons, e.g.
1396 WAIT:1280x1024:... to set the size of the display the VNC client
1397 first attaches to since some VNC viewers will not automatically
1398 adjust to a new framebuffer size.
1399 A more interesting case is like this:
1401 WAIT:cmd=/usr/local/bin/find_display
1403 in which case the command after "cmd=" is run to dynamically
1405 work out the DISPLAY and optionally the XAUTHORITY data. The
1406 first line of the command output must be of the form DIS‐
1407 PLAY=<xdisplay>. On Linux if the virtual terminal is known
1408 append ",VT=n" to this string and the chvt(1) program will also
1409 be run. Any remaining output is taken as XAUTHORITY data. It
1410 can be either of the form XAUTHORITY=<file> or raw xauthority
1411 data for the display. For example;
1412 xauth extract - $DISPLAY"
1414 NOTE: As specified in the previous paragraph, you can supply
1416 your own WAIT:cmd=... program or script, BUT there are two very
1417 useful *BUILT-IN* ones: FINDDISPLAY (alias -find above) and
1418 FINDCREATEDISPLAY (alias -create above.) Most people use these
1419 instead of creating their own script. Read the following (espe‐
1420 cially the BUILT-IN modes sections) to see how to configure
1421 these two useful builtin -display WAIT: modes.
1422 In the case of -unixpw (and -unixpw_nis only if x11vnc is run‐
1424 ning as root), then the cmd= command is run as the user who just
1425 authenticated via the login and password prompt.
1426 In the case of -unixpw_cmd, the commands will also be run as the
1428 logged-in user, as long as the user-supplied helper program sup‐
1429 ports RFB_UNIXPW_CMD_RUN (see the -unixpw_cmd option.)
1430 Also in the case of -unixpw, the user logging in can place a
1432 colon at the end of her username and supply a few options:
1433 scale=, scale_cursor= (or sc=), solid (or so), id=, clear_mods
1434 (or cm), clear_keys (or ck), clear_all (or ca), repeat, speeds=
1435 (or sp=), readtimeout= (or rd=), viewonly (or vo), nodisplay=
1436 (or nd=), rotate= (or ro=), or noncache (or nc), all separated
1437 by commas if there is more than one. After the user logs in
1438 successfully, these options will be applied to the VNC screen.
1439 For example,
1440 login: fred:scale=3/4,sc=1,repeat Password: ...
1442 login: runge:sp=modem,rd=120,solid
1444 for convenience m/n implies scale= e.g. fred:3/4 If you type
1446 and enter your password incorrectly, to retrieve your long
1447 "login:" line press the Up arrow once (before typing anything
1448 else).
1449 Most of these colon options only apply to the builtin FINDDIS‐
1451 PLAY and FINDCREATEDISPLAY modes, but note that they are passed
1452 to the extrenal command in the environment as well and so could
1453 be used.
1454 In the login panel, press F1 to get a list of the available
1456 options that you can add after the username.
1457 Another option is "geom=WxH" or "geom=WxHxD" (or ge=). This only
1459 has an effect in FINDCREATEDISPLAY mode when a virtual X server
1460 such as Xvfb is going to be created. It sets the width and
1461 height of the new display, and optionally the color depth as
1462 well.
1463 You can also supply "gnome", "kde", "twm", "fvwm", "mwm",
1465 "dtwm", "wmaker", "xfce", "lxde", "enlightenment", "Xsession",
1466 or "failsafe" (same as "xterm") to have the created display use
1467 that mode for the user session.
1468 Specify "tag=..." to set the unique FD_TAG desktop session tag
1470 described below. Note: this option will be ignored if the
1471 FD_TAG env. var. is already set or if the viewer-side supplied
1472 value is not completely composed of alphanumeric or '_' or '-'
1473 characters.
1474 User preferences file: Instead of having the user type in
1476 geom=WxH,... etc. every time he logs in to find or create his X
1477 session, if you set FD_USERPREFS to a string that does not con‐
1478 tain the "/" character, then the user's home directory is
1479 prepended to that string and if the file exists its first line
1480 is read and appended to any options he supplied at the login:
1481 prompt. For example -env FD_USERPREFS=.x11vnc_create and the
1482 user put "geom=1600x1200" in his ~/.x11vnc_create file.
1483 To disable the option setting set the environment variable
1485 X11VNC_NO_UNIXPW_OPTS=1 before starting x11vnc. To set any
1486 other options, the user can use the gui (x11vnc -gui connect) or
1487 the remote control method (x11vnc -R opt:val) during his VNC
1488 session.
1489 So we see the combination of -display WAIT:cmd=... and -unixpw
1491 allows automatic pairing of an unix authenticated VNC user with
1492 his desktop. This could be very useful on SunRays and also any
1493 system where multiple users share a given machine. The user
1494 does not need to remember special ports or passwords set up for
1495 his desktop and VNC.
1496 A nice way to use WAIT:cmd=... is out of inetd(8) (it automati‐
1498 cally forks a new x11vnc for each user). You can have the
1499 x11vnc inetd spawned process run as, say, root or nobody. When
1500 run as root (for either inetd or display manager), you can also
1501 supply the option "-users unixpw=" to have the x11vnc process
1502 switch to the user as well. Note: there will be a 2nd SSL
1503 helper process that will not switch, but it is only encoding and
1504 decoding the encrypted stream at that point.
1505 BUILT-IN modes:
1507 -- Automatic Finding of User X Sessions --
1509 As a special case, WAIT:cmd=FINDDISPLAY will run a script that
1511 works on most Unixes to determine a user's DISPLAY variable and
1512 xauthority data (see who(1) ).
1513 NOTE: The option "-find" is an alias for this mode.
1515 To have this default script printed to stdout (e.g. for cus‐
1517 tomization) run with WAIT:cmd=FINDDISPLAY-print To have the
1518 script run to print what display it would find use "-finddpy" or
1519 WAIT:cmd=FINDDISPLAY-run
1520 The standard script runs xdpyinfo(1) run on potential displays.
1522 If your X server(s) have a login greeter that exclusively grabs
1523 the Xserver, then xdpyinfo blocks forever and this mode will not
1524 work. See www.karlrunge.com/x11vnc/faq.html#faq-display-manager
1525 for how to disable this for dtgreet on Solaris and possibly for
1526 other greeters.
1527 In -find/cmd=FINDDISPLAY mode, if you set FD_XDM=1, e.g. 'x11vnc
1529 -env FD_XDM=1 -find ...' and x11vnc is running as root (e.g.
1530 inetd) then it will try to find the XAUTHORITY file of a running
1531 XDM/GDM/KDM login greeter (i.e. no user has logged into an X
1532 session yet.)
1533 As another special case, WAIT:cmd=HTTPONCE will allow x11vnc to
1535 service one http request and then exit. This is usually done in
1536 -inetd mode to run on, say, port 5800 and allow the Java
1537 vncviewer to be downloaded by client web browsers. For example:
1538 5815 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc \ -inetd
1540 -q -http_ssl -prog /.../x11vnc \ -display WAIT:cmd=HTTPONCE
1541 Where /.../x11vnc is the full path to x11vnc. It is used in the
1543 Apache SSL-portal example (see FAQ).
1544 In this mode you can set X11VNC_SKIP_DISPLAY to a comma sepa‐
1546 rated list of displays (e.g. ":0,:1") to ignore in the finding
1547 process. The ":" is optional. Ranges n-m e.g. 0-20 can also be
1548 supplied. This string can also be set by the connecting user via
1549 "nd=" using "+" instead of "," If "nd=all" or you set
1550 X11VNC_SKIP_DISPLAY=all then all display finding fails as if you
1551 set X11VNC_FINDDISPLAY_ALWAYS_FAILS=1 (below.)
1552 On some systems lsof(1) can be very slow. Set the env. var.
1554 FIND_DISPLAY_NO_LSOF=1 to skip using lsof to try to find the
1555 Linux VT the X server is running on. set FIND_DIS‐
1556 PLAY_NO_VT_FIND=1 to avoid looking at all.
1557 -- Automatic Creation of User X Sessions --
1559 An interesting option is WAIT:cmd=FINDCREATEDISPLAY that is like
1561 FINDDISPLAY in that is uses the same method to find an existing
1562 display. However, if it does not find one it will try to
1563 *start* up an X server session for the user. This is the only
1564 time x11vnc tries to actually start up an X server.
1565 NOTE: The option "-create" is an alias for this mode.
1567 It will start looking for an open display number at :20 Override
1569 via X11VNC_CREATE_STARTING_DISPLAY_NUMBER=n By default 80 X dis‐
1570 plays are allowed (i.e. going to :99) Override via X11VNC_CRE‐
1571 ATE_MAX_DISPLAYS=n
1572 For its heuristics, the create display script sets LC_ALL=C so
1574 that command output is uniform. By default it will try to
1575 restore LC_ALL right before starting the user session. However,
1576 if you don't mind it keeping LC_ALL=C set the env. var.:
1577 X11VNC_CREATE_LC_ALL_C_OK=1
1578 By default FINDCREATEDISPLAY will try Xvfb and then Xdummy:
1580 The Xdummy wrapper is part of the x11vnc source code
1582 (x11vnc/misc/Xdummy) It should be available in PATH and have
1583 run "Xdummy -install" once to create the shared library. Xdummy
1584 only works on Linux. As of 12/2009 it no longer needs to be run
1585 as root, and the default is to not run as root. In some circum‐
1586 stances permissions may require running it as root, in these
1587 cases specify FD_XDUMMY_RUN_AS_ROOT=1, this is the same as sup‐
1588 plying -root to the Xdummy cmdline.
1589 Xvfb is available on most platforms and does not require root.
1591 An advantage of Xdummy over Xvfb is that Xdummy supports RANDR
1593 dynamic screen resizing.
1594 When x11vnc exits (i.e. user disconnects) the X server session
1596 stays running in the background. The FINDDISPLAY will find it
1597 directly next time. The user must exit the X session in the
1598 usual way for it to terminate (or kill the X server process if
1599 all else fails).
1600 To troubleshoot the FINDCREATEDISPLAY mechanism, set the follow‐
1602 ing env. var. to an output log file, e.g -env CREATE_DIS‐
1603 PLAY_OUTPUT=/tmp/mydebug.txt
1604 So this is a somewhat odd mode for x11vnc in that it will start
1606 up and poll virtual X servers! This can be used from, say,
1607 inetd(8) to provide a means of definitely getting a desktop
1608 (either real or virtual) on the machine. E.g. a desktop ser‐
1609 vice:
1610 5900 stream tcp nowait root /usr/sbin/tcpd /.../x11vnc -inetd -q
1612 -http -ssl SAVE -unixpw -users unixpw=\ -passwd secret -prog
1613 /.../x11vnc \ -display WAIT:cmd=FINDCREATEDISPLAY
1614 Where /.../x11vnc is the full path to x11vnc.
1616 See the -svc/-service option alias above.
1618 If for some reason you do not want x11vnc to ever try to find an
1620 existing display set the env. var X11VNC_FINDDIS‐
1621 PLAY_ALWAYS_FAILS=1 (also -env ...) This is the same as setting
1622 X11VNC_SKIP_DISPLAY=all or supplying "nd=all" after "username:"
1623 Use WAIT:cmd=FINDCREATEDISPLAY-print to print out the script
1625 that is used for this.
1626 You can specify the preferred X server order via e.g.,
1628 WAIT:cmd=FINDCREATEDISPLAY-Xdummy,Xvfb,X and/or leave out ones
1629 you do not want. The the case "X" means try to start up a real,
1630 hardware X server using xinit(1) or startx(1). If there is
1631 already an X server running the X case may only work on Linux
1632 (see startx(1) ).
1633 "Xvnc" will start up a VNC X server (real- or tight-vnc, e.g.
1635 use if Xvfb is not available). "Xsrv" will start up the server
1636 program in the variable "FD_XSRV" if it is non-empty. You can
1637 make this be a wrapper script if you like (it must handle :N,
1638 -geometry, and -depth and other X server options).
1639 You can set the environment variable FD_GEOM (or X11VNC_CRE‐
1641 ATE_GEOM) to WxH or WxHxD to set the width and height and
1642 optionally the color depth of the created display. You can also
1643 set FD_SESS to be the session (short name of the windowmanager:
1644 kde, gnome, twm, failsafe, etc.). FD_OPTS contains extra options
1645 to pass to the X server. You can also set FD_PROG to be the full
1646 path to the session/windowmanager program.
1647 More FD tricks: FD_CUPS=port or FD_CUPS=host:port will set the
1649 cups printing environment. Similarly for FD_ESD=port or
1650 FD_ESD=host:port for esddsp sound redirection. Set FD_EXTRA to
1651 a command to be run a few seconds after the X server starts up.
1652 Set FD_TAG to be a unique name for the session, it is set as an
1653 X property, that makes FINDDISPLAY only find sessions with that
1654 tag value.
1655 Set FD_XDMCP_IF to the network interface that the display man‐
1657 ager is running on; default is 'localhost' but you may need to
1658 set it to '::1' on some IPv6 only systems or misconfigured dis‐
1659 play managers.
1660 If you want the FINDCREATEDISPLAY session to contact an XDMCP
1662 login manager (xdm/gdm/kdm) on the same machine, then use
1663 "Xvfb.xdmcp" instead of "Xvfb", etc. The user will have to sup‐
1664 ply his username and password one more time (but he gets to
1665 select his desktop type so that can be useful). For this to
1666 work, you will need to enable localhost XDMCP (udp port 177) for
1667 the display manager. This seems to be:
1668 for gdm in gdm.conf: Enable=true in section [xdmcp] for kdm in
1670 kdmrc: Enable=true in section [Xdmcp] for xdm in xdm-con‐
1671 fig: DisplayManager.requestPort: 177
1672 See the shorthand options above "-svc", "-xdmsvc" and
1674 "-sshxdmsvc" that specify the above options for some useful
1675 cases.
1676 If you set the env. var WAITBG=1 x11vnc will go into the back‐
1678 ground once listening in wait mode.
1679 Another special mode is FINDCREATEDISPLAY-Xvnc.redirect, (or
1681 FINDDISPLAY-Xvnc.redirect). In this case it will start up Xvnc
1682 as above if needed, but instead of polling it in its normal way,
1683 it simply does a socket redirection of the connected VNC viewer
1684 to the Xvnc.
1685 So in Xvnc.redirect x11vnc does no VNC but merely transfers the
1687 data back and forth. This should be faster then x11vnc's
1688 polling method, but not as fast as connecting directly to the
1689 Xvnc with the VNC Viewer. The idea here is to take advantage of
1690 x11vnc's display finding/creating scheme, SSL, and perhaps a few
1691 others. Most of x11vnc's options do not apply in this mode.
1692 Xvnc.redirect should also work for the vnc.so X server module
1694 for the h/w display however it will work only for finding the
1695 display and the user must already be logged into the X console.
1696 -vencrypt mode
1698 The VeNCrypt extension to the VNC protocol allows encrypted
1700 SSL/TLS connections. If the -ssl mode is enabled, then VeNCrypt
1701 is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel,
1702 only the protocol handshake is a little different.)
1703 To control when and how VeNCrypt is used, specify the mode
1705 string. If mode is "never", then VeNCrypt is not used. If mode
1706 is "support" (the default) then VeNCrypt is supported. If mode
1707 is "only", then the similar and older ANONTLS protocol is not
1708 simultaneously supported. x11vnc's normal SSL mode (vncs://)
1709 will be supported under -ssl unless you set mode to "force".
1710 If mode is prefixed with "nodh:", then Diffie Hellman anonymous
1712 key exchange is disabled. If mode is prefixed with "nox509:",
1713 then X509 key exchange is disabled.
1714 To disable all Anonymous Diffie-Hellman access (susceptible to
1716 Man-In-The-Middle attack) you will need to supply "-vencrypt
1717 nodh:support -anontls never" or "-vencrypt nodh:only"
1718 If mode is prefixed with "newdh:", then new Diffie Hellman
1720 parameters are generated for each connection (this can be time
1721 consuming: 1-60 secs; see -dhparams below for a faster way)
1722 rather than using the fixed values in the program. Using fixed,
1723 publicly known values is not known to be a security problem.
1724 This setting applies to ANONTLS as well.
1725 Long example: -vencrypt newdh:nox509:support
1727 Also, if mode is prefixed with "plain:", then if -unixpw mode is
1729 active the VeNCrypt "*Plain" username+passwd method is enabled
1730 for Unix logins. Otherwise in -unixpw mode the normal login
1731 panel is provided.
1732 You *MUST* supply the -ssl option for VeNCrypt to be active.
1734 The -vencrypt option only fine-tunes its operation.
1735 -anontls mode
1737 The ANONTLS extension to the VNC protocol allows encrypted
1739 SSL/TLS connections. If the -ssl mode is enabled, then ANONTLS
1740 is enabled as well BY DEFAULT (they both use a SSL/TLS tunnel,
1741 only the protocol handshake is a little different.)
1742 ANONTLS is an older SSL/TLS mode introduced by vino.
1744 It is referred to as 'TLS' for its registered VNC security-type
1746 name, but we use the more descriptive ´ANONTLS' here because it
1747 provides only Anonymous Diffie-Hellman encrypted connections,
1748 and hence no possibility for certificate authentication.
1749 To control when and how ANONTLS is used, specify the mode
1751 string. If mode is "never", then ANONTLS is not used. If mode
1752 is "support" (the default) then ANONTLS is supported. If mode
1753 is "only", then the similar VeNCrypt protocol is not simultane‐
1754 ously supported. x11vnc's normal SSL mode (vncs://) will be
1755 supported under -ssl unless you set mode to "force".
1756 If mode is prefixed with "newdh:", then new Diffie Hellman
1758 parameters are generated for each connection (this can be time
1759 consuming: 1-60 secs; see -dhparams below for a faster way)
1760 rather than using the fixed values in the program. Using fixed,
1761 publicly known values is not known to be a security problem.
1762 This setting applies to VeNCrypt as well. See the description
1763 of "plain:" under -vencrypt.
1764 Long example: -anontls newdh:plain:support
1766 You *MUST* supply the -ssl option for ANONTLS to be active. The
1768 -anontls option only fine-tunes its operation.
1769 -sslonly
1771 Same as: "-vencrypt never -anontls never" i.e. it disables the
1773 VeNCrypt and ANONTLS encryption methods and only allows standard
1774 SSL tunneling. You must also supply the -ssl ... option (see
1775 below.)
1776 -dhparams file
1778 For some operations a set of Diffie Hellman parameters (prime
1780 and generator) is needed. If so, use the parameters in file. In
1781 particular, the VeNCrypt and ANONTLS anonymous DH mode need
1782 them. By default a fixed set is used. If you do not want to do
1783 that you can specify "newdh:" to the -vencrypt and -anontls
1784 options to generate a new set each session. If that is too slow
1785 for you, use -dhparams file to a set you created manually via
1786 "openssl dhparam -out file 1024"
1787 -nossl
1789 Disable the -ssl option (see below). Since -ssl is off by
1791 default -nossl would only be used on the commandline to unset
1792 any *earlier* -ssl option (or -svc...)
1793 -ssl [pem]
1795 Use the openssl library (www.openssl.org) to provide a built-in
1797 encrypted SSL/TLS tunnel between VNC viewers and x11vnc. This
1798 requires libssl support to be compiled into x11vnc at build
1799 time. If x11vnc is not built with libssl support it will exit
1800 immediately when -ssl is prescribed. See the -stunnel option
1801 below for an alternative.
1802 The VNC Viewer-side needs to support SSL/TLS as well. See this
1804 URL and also the discussion below for ideas on how to enable SSL
1805 support for the viewer: http://www.karl‐
1806 runge.com/x11vnc/faq.html#faq-ssl-tun nel-viewers . x11vnc pro‐
1807 vides an SSL enabled Java viewer applet in the classes/ssl
1808 directory (-http or -httpdir options.) The SSVNC viewer package
1809 supports SSL tunnels too.
1810 If the VNC Viewer supports VeNCrypt or ANONTLS (vino's encryp‐
1812 tion mode) they are also supported by the -ssl mode (see the
1813 -vencrypt and -anontls options for more info; use -sslonly to
1814 disable both of them.)
1815 Use "-ssl /path/to/mycert.pem" to specify an SSL certificate
1817 file in PEM format to use to identify and provide a key for this
1818 server. See openssl(1) for more info about PEMs and the
1819 -sslGenCert and "-ssl SAVE" options below for how to create
1820 them.
1821 The connecting VNC viewer SSL tunnel can (at its option) authen‐
1823 ticate this server if it has the public key part of the certifi‐
1824 cate (or a common certificate authority, CA, is a more sophisti‐
1825 cated way to verify this server's cert, see -sslGenCA below).
1826 This authentication is done to prevent Man-In-The-Middle
1827 attacks. Otherwise, if the VNC viewer simply accepts this
1828 server's key WITHOUT verification, the traffic is protected from
1829 passive sniffing on the network, but *NOT* from Man-In-The-Mid‐
1830 dle attacks. There are hacker tools like dsniff/webmitm and cain
1831 that implement SSL Man-In-The-Middle attacks.
1832 If [pem] is empty or the string "SAVE" then the openssl(1) com‐
1834 mand must be available to generate the certificate the first
1835 time. A self-signed certificate is generated (see -sslGenCA and
1836 -sslGenCert for use of a Certificate Authority.) It will be
1837 saved to the file ~/.vnc/certs/server.pem. On subsequent calls
1838 if that file already exists it will be used directly.
1839 Use "SAVE_NOPROMPT" to avoid being prompted to protect the gen‐
1841 erated key with a passphrase. However in -inetd and -bg modes
1842 there will be no prompting for a passphrase in either case.
1843 If [pem] is "SAVE_PROMPT" the server.pem certificate will be
1845 created based on your answers to its prompts for all info such
1846 as OrganizationalName, CommonName, etc.
1847 Use "SAVE-<string>" and "SAVE_PROMPT-<string>" to refer to the
1849 file ~/.vnc/certs/server-<string>.pem instead (it will be gener‐
1850 ated if it does not already exist). E.g. "SAVE-charlie" will
1851 store to the file ~/.vnc/certs/server-charlie.pem
1852 Examples: x11vnc -ssl SAVE -display :0 ... x11vnc -ssl SAVE-
1854 someother -display :0 ...
1855 If [pem] is "TMP" and the openssl(1) utility command exists in
1857 PATH, then a temporary, self-signed certificate will be gener‐
1858 ated for this session. If openssl(1) cannot be used to generate
1859 a temporary certificate x11vnc exits immediately. The temporary
1860 cert will be discarded when x11vnc exits.
1861 If successful in using openssl(1) to generate a temporary cer‐
1863 tificate in "SAVE" or "TMP" creation modes, the public part of
1864 it will be displayed to stderr (e.g. one could copy it to the
1865 client-side to provide authentication of the server to VNC view‐
1866 ers.)
1867 NOTE: In "TMP" mode, unless you safely copy the public part of
1869 the temporary Cert to the viewer for authenticate *every time*
1870 (unlikely...), then only passive sniffing attacks are prevented
1871 and you are still open to Man-In-The-Middle attacks. This is
1872 why the default "SAVE" mode is preferred (and more sophisticated
1873 CA mode too). Only with saved keys AND the VNC viewer authenti‐
1874 cating them (via the public certificate), are Man-In-The-Middle
1875 attacks prevented.
1876 If [pem] is "ANON" then the Diffie-Hellman anonymous key
1878 exchange method is used. In this mode there are *no* SSL cer‐
1879 tificates and so it is not possible to authenticate either the
1880 VNC server or VNC client. Thus only passive network sniffing
1881 attacks are avoided: the "ANON" method is susceptible to Man-In-
1882 The-Middle attacks. "ANON" is not recommended; instead use a
1883 SSL PEM you created or the default "SAVE" method.
1884 See -ssldir below to use a directory besides the default
1886 ~/.vnc/certs
1887 If your x11vnc binary was not compiled with OpenSSL library sup‐
1889 port, use of the -ssl option will induce an immediate failure
1890 and exit. For such binaries, consider using the -stunnel option
1891 for SSL encrypted connections.
1892 Misc Info: In temporary cert creation mode "TMP", set the env.
1894 var. X11VNC_SHOW_TMP_PEM=1 to have x11vnc print out the entire
1895 certificate, including the PRIVATE KEY part, to stderr. There
1896 are better ways to get/save this info. See "SAVE" above and
1897 "-sslGenCert" below.
1898 -ssltimeout n
1900 Set SSL read timeout to n seconds. In some situations (i.e. an
1902 iconified viewer in Windows) the viewer stops talking and the
1903 connection is dropped after the default timeout (25s for about
1904 the first minute, 43200s later). Set to zero to poll forever.
1905 Set to a negative value to use the builtin setting.
1906 Note that this value does NOT apply to the *initial* ssl init
1908 connection. The default timeout for that is 20sec. Use -env
1909 SSL_INIT_TIMEOUT=n to modify it.
1910 -sslnofail
1912 Exit at the first SSL connection failure. Useful when scripting
1914 SSL connections (e.g. x11vnc is started via ssh) and you do not
1915 want x11vnc waiting around for more connections, tying up ports,
1916 etc.
1917 -ssldir dir
1919 Use dir as an alternate ssl certificate and key management
1921 toplevel directory. The default is ~/.vnc/certs
1922 This directory is used to store server and other certificates
1924 and keys and also other materials. E.g. in the simplest case,
1925 "-ssl SAVE" will store the x11vnc server cert in dir/server.pem
1926 Use of alternate directories via -ssldir allows you to manage
1928 multiple VNC Certificate Authority (CA) keys. Another use is if
1929 ~/.vnc/cert is on an NFS share you might want your certificates
1930 and keys to be on a local filesystem to prevent network snooping
1931 (for example -ssldir /var/lib/x11vnc-certs).
1932 -ssldir affects nearly all of the other -ssl* options, e.g. -ssl
1934 SAVE, -sslGenCert, etc..
1935 -sslverify path
1937 For either of the -ssl or -stunnel modes, use path to provide
1939 certificates to authenticate incoming VNC *Client* connections
1940 (normally only the server is authenticated in SSL.) This can be
1941 used as a method to replace standard password authentication of
1942 clients.
1943 If path is a directory it contains the client (or CA) certifi‐
1945 cates in separate files. If path is a file, it contains one or
1946 more certificates. See special tokens below. These correspond
1947 to the "CApath = dir" and "CAfile = file" stunnel options. See
1948 the stunnel(8) manpage for details.
1949 Examples: x11vnc -ssl -sslverify ~/my.crt x11vnc -ssl -sslverify
1951 ~/my_pem_dir/
1952 Note that if path is a directory, it must contain the certs in
1954 separate files named like <HASH>.0, where the value of <HASH> is
1955 found by running the command "openssl x509 -hash -noout -in
1956 file.crt". Evidently one uses <HASH>.1 if there is a colli‐
1957 sion...
1958 The the key-management utility "-sslCertInfo HASHON" and
1960 "-sslCertInfo HASHOFF" will create/delete these hashes for you
1961 automatically (via symlink) in the HASH subdirs it manages.
1962 Then you can point -sslverify to the HASH subdir.
1963 Special tokens: in -ssl mode, if path is not a file or a direc‐
1965 tory, it is taken as a comma separated list of tokens that are
1966 interpreted as follows:
1967 If a token is "CA" that means load the CA/cacert.pem file from
1969 the ssl directory. If a token is "clients" then all the files
1970 clients/*.crt in the ssl directory are loaded. Otherwise the
1971 file clients/token.crt is attempted to be loaded. As a kludge,
1972 use a token like ../server-foo to load a server cert if you find
1973 that necessary.
1974 Use -ssldir to use a directory different from the ~/.vnc/certs
1976 default.
1977 Note that if the "CA" cert is loaded you do not need to load any
1979 of the certs that have been signed by it. You will need to load
1980 any additional self-signed certs however.
1981 Examples: x11vnc -ssl -sslverify CA x11vnc -ssl -sslverify
1983 self:fred,self:jim x11vnc -ssl -sslverify CA,clients
1984 Usually "-sslverify CA" is the most effective. See the
1986 -sslGenCA and -sslGenCert options below for how to set up and
1987 manage the CA framework.
1988 NOTE: the following utilities, -sslGenCA, -sslGenCert,
1990 -sslEncKey, -sslCertInfo, and -sslCRL are provided for complete‐
1991 ness, but for casual usage they are overkill.
1992 They provide VNC Certificate Authority (CA) key creation and
1994 server / client key generation and signing. So they provide a
1995 basic Public Key management framework for VNC-ing with x11vnc.
1996 (note that they require openssl(1) be installed on the system)
1997 However, the simplest usage mode, "-ssl TMP" (where x11vnc auto‐
1999 matically generates its own, self-signed, temporary key and the
2000 VNC viewers always accept it, e.g. accepting via a dialog box)
2001 is probably safe enough for most scenarios. CA management is
2002 not needed.
2003 To protect against Man-In-The-Middle attacks the "TMP" mode can
2005 be improved by using "-ssl SAVE" (same as "-ssl", i.e. the
2006 default) to have x11vnc create a longer term self-signed cer‐
2007 tificate, and then (safely) copy the corresponding public key
2008 cert to the desired client machines (care must be taken the pri‐
2009 vate key part is not stolen; you will be prompted for a
2010 passphrase).
2011 So keep in mind no CA key creation or management (-sslGenCA and
2013 -sslGenCert) is needed for either of the above two common usage
2014 modes.
2015 One might want to use -sslGenCA and -sslGenCert if you had a
2017 large number of VNC client and server workstations. That way
2018 the administrator could generate a single CA key with -sslGenCA
2019 and distribute its certificate part to all of the workstations.
2020 Next, he could create signed VNC server keys (-sslGenCert server
2022 ...) for each workstation or user that then x11vnc would use to
2023 authenticate itself to any VNC client that has the CA cert.
2024 Optionally, the admin could also make it so the VNC clients
2026 themselves are authenticated to x11vnc (-sslGenCert client ...)
2027 For this -sslverify would be pointed to the CA cert (and/or
2028 self-signed certs).
2029 x11vnc will be able to use all of these cert and key files. On
2031 the VNC client side, they will need to be "imported" somehow.
2032 Web browsers have "Manage Certificates" actions as does the Java
2033 applet plugin Control Panel. stunnel can also use these files
2034 (see the ss_vncviewer example script in the FAQ and SSVNC.)
2035 -sslCRL path
2037 Set the Certificate Revocation Lists (CRL) to path. This set‐
2039 ting applies for both -ssl and -stunnel modes.
2040 If path is a file, the file contains one or more CRLs in PEM
2042 format. If path is a directory, it contains hash named files of
2043 CRLs in the usual OpenSSL manner. See the OpenSSL and stun‐
2044 nel(8) documentation for more info.
2045 This option only applies if -sslverify has been supplied: it
2047 checks for revocation along the certificate chain used to verify
2048 the VNC client. The -sslCRL setting will be ignored when
2049 -sslverify is not specified.
2050 Note that if a CRL's expiration date has passed, all SSL connec‐
2052 tions will fail regardless of if they are related to the subject
2053 of the CRL or not.
2054 Only rarely will one's x11vnc -ssl infrastructure be so large
2056 that this option would be useful (since normally maintaining the
2057 contents of the -sslverify file or directory should be enough.)
2058 However, when using x11vnc with a Certificate Authority (see
2059 -sslGenCA) to authenticate Clients via SSL/TLS, the -sslCRL
2060 option can be useful to revoke users' certs whose private SSL
2061 keys were lost or stolen (e.g. laptop.) This way a new CA
2062 cert+key does not need to be created and new signed client keys
2063 generated and distributed to all users.
2064 To create a CRL file with revoked certificates the commands
2066 'openssl ca -revoke ...' and 'openssl ca -gencrl ...' are use‐
2067 ful. (Run them in ~/.vnc/certs)
2068 -sslGenCA [dir]
2070 Generate your own Certificate Authority private key, certifi‐
2072 cate, and other files in directory [dir]. x11vnc then exits.
2073 If [dir] is not supplied, a -ssldir setting is used, or other‐
2075 wise ~/.vnc/certs is used.
2076 This command also creates directories where server and client
2078 certs and keys will be stored. The openssl(1) program must be
2079 installed on the system and available in PATH.
2080 After the CA files and directories are created the x11vnc com‐
2082 mand exits; the VNC server is not run.
2083 You will be prompted for information to put into the CA certifi‐
2085 cate. The info does not have to be accurate just as long as
2086 clients accept the cert for VNC connections. You will also need
2087 to supply a passphrase of at least 4 characters for the CA pri‐
2088 vate key.
2089 Once you have generated the CA you can distribute its certifi‐
2091 cate part, [dir]/CA/cacert.pem, to other workstations where VNC
2092 viewers will be run. One will need to "import" this certificate
2093 in the applications, e.g. Web browser, Java applet plugin, stun‐
2094 nel, etc. Next, you can create and sign keys using the CA with
2095 the -sslGenCert option below.
2096 Examples: x11vnc -sslGenCA x11vnc -sslGenCA ~/myCAdir x11vnc
2098 -ssldir ~/myCAdir -sslGenCA
2099 (the last two lines are equivalent)
2101 -sslGenCert type name
2103 Generate a VNC server or client certificate and private key pair
2105 signed by the CA created previously with -sslGenCA. The
2106 openssl(1) program must be installed on the system and available
2107 in PATH.
2108 After the Certificate is generated x11vnc exits; the VNC server
2110 is not run.
2111 The type of key to be generated is the string type. It is
2113 either "server" (i.e. for use by x11vnc) or "client" (for a VNC
2114 viewer). Note that typically only "server" is used: the VNC
2115 clients authenticate themselves by a non-public-key method (e.g.
2116 VNC or unix password). type is required.
2117 An arbitrary default name you want to associate with the key is
2119 supplied by the name string. You can change it at the various
2120 prompts when creating the key. name is optional.
2121 If name is left blank for clients keys then "nobody" is used.
2123 If left blank for server keys, then the primary server key:
2124 "server.pem" is created (this is the saved one referenced by
2125 "-ssl SAVE" when the server is started)
2126 If name begins with the string "self:" then a self-signed cer‐
2128 tificate is created instead of one signed by your CA key.
2129 If name begins with the string "req:" then only a key (.key) and
2131 a certificate signing *request* (.req) are generated. You can
2132 then send the .req file to an external CA (even a professional
2133 one, e.g. Thawte) and then combine the .key and the received
2134 cert into the .pem file with the same basename.
2135 The distinction between "server" and "client" is simply the
2137 choice of output filenames and sub-directory. This makes it so
2138 the -ssl SAVE-name option can easily pick up the x11vnc PEM file
2139 this option generates. And similarly makes it easy for the
2140 -sslverify option to pick up your client certs.
2141 There is nothing special about the filename or directory loca‐
2143 tion of either the "server" and "client" certs. You can rename
2144 the files or move them to wherever you like.
2145 Precede this option with -ssldir [dir] to use a directory other
2147 than the default ~/.vnc/certs You will need to run -sslGenCA on
2148 that directory first before doing any -sslGenCert key creation.
2149 Note you cannot recreate a cert with exactly the same distigu‐
2151 ished name (DN) as an existing one. To do so, you will need to
2152 edit the [dir]/CA/index.txt file to delete the line.
2153 Similar to -sslGenCA, you will be prompted to fill in some
2155 information that will be recorded in the certificate when it is
2156 created.
2157 Tip: if you know the fully-qualified hostname other people will
2159 be connecting to, you can use that as the CommonName "CN" to
2160 avoid some applications (e.g. web browsers and java plugin) com‐
2161 plaining that it does not match the hostname.
2162 You will also need to supply the CA private key passphrase to
2164 unlock the private key created from -sslGenCA. This private key
2165 is used to sign the server or client certificate.
2166 The "server" certs can be used by x11vnc directly by pointing to
2168 them via the -ssl [pem] option. The default file will be
2169 ~/.vnc/certs/server.pem. This one would be used by simply typ‐
2170 ing -ssl SAVE. The pem file contains both the certificate and
2171 the private key. server.crt file contains the cert only.
2172 The "client" cert + private key file will need to be copied and
2174 imported into the VNC viewer side applications (Web browser,
2175 Java plugin, stunnel, etc.) Once that is done you can delete
2176 the "client" private key file on this machine since it is only
2177 needed on the VNC viewer side. The, e.g.
2178 ~/.vnc/certs/clients/<name>.pem contains both the cert and pri‐
2179 vate key. The <name>.crt contains the certificate only.
2180 NOTE: It is very important to know one should generate new keys
2182 with a passphrase. Otherwise if an untrusted user steals the
2183 key file he could use it to masquerade as the x11vnc server (or
2184 VNC viewer client). You will be prompted whether to encrypt the
2185 key with a passphrase or not. It is recommended that you do.
2186 One inconvenience to a passphrase is that it must be typed in
2187 EVERY time x11vnc or the client app is started up.
2188 Examples:
2190 x11vnc -sslGenCert server x11vnc -ssl SAVE -display :0 ...
2192 and then on viewer using ss_vncviewer stunnel wrapper (see the
2194 FAQ): ss_vncviewer -verify ./cacert.crt hostname:0
2195 (this assumes the cacert.crt cert from -sslGenCA was safely
2197 copied to the VNC viewer machine where ss_vncviewer is run)
2198 Example using a name:
2200 x11vnc -sslGenCert server charlie x11vnc -ssl SAVE-charlie -dis‐
2202 play :0 ...
2203 Example for a client certificate (rarely used):
2205 x11vnc -sslGenCert client roger scp
2207 ~/.vnc/certs/clients/roger.pem somehost:. rm
2208 ~/.vnc/certs/clients/roger.pem
2209 x11vnc is then started with the option -sslverify
2211 ~/.vnc/certs/clients/roger.crt (or simply -sslverify roger), and
2212 on the viewer user on somehost could do for example:
2213 ss_vncviewer -mycert ./roger.pem hostname:0
2215 If you set the env. var REQ_ARGS='...' it will be passed to
2217 openssl req(1). A common use would be REQ_ARGS='-days 1095' to
2218 bump up the expiration date (3 years in this case).
2219 -sslEncKey pem
2221 Utility to encrypt an existing PEM file with a passphrase you
2223 supply when prompted. For that key to be used (e.g. by x11vnc)
2224 the passphrase must be supplied each time.
2225 The "SAVE" notation described under -ssl applies as well. (pre‐
2227 cede this option with -ssldir [dir] to refer a directory besides
2228 the default ~/.vnc/certs)
2229 The openssl(1) program must be installed on the system and
2231 available in PATH. After the Key file is encrypted the x11vnc
2232 command exits; the VNC server is not run.
2233 Examples: x11vnc -sslEncKey /path/to/foo.pem x11vnc -sslEncKey
2235 SAVE x11vnc -sslEncKey SAVE-charlie
2236 -sslCertInfo pem
2238 Prints out information about an existing PEM file. In addition
2240 the public certificate is also printed. The openssl(1) program
2241 must be in PATH. Basically the command "openssl x509 -text" is
2242 run on the pem.
2243 After the info is printed the x11vnc command exits; the VNC
2245 server is not run.
2246 The "SAVE" notation described under -ssl applies as well.
2248 Using "LIST" will give a list of all certs being managed (in
2250 the ~/.vnc/certs dir, use -ssldir to refer to another dir).
2251 "ALL" will print out the info for every managed key (this can be
2252 very long). Giving a client or server cert shortname will also
2253 try a lookup (e.g. -sslCertInfo charlie). Use "LISTL" or "LL"
2254 for a long (ls -l style) listing.
2255 Using "HASHON" will create subdirs [dir]/HASH and [dir]/HASH
2257 with OpenSSL hash filenames (e.g. 0d5fbbf1.0) symlinks pointing
2258 up to the corresponding *.crt file. ([dir] is ~/.vnc/certs or
2259 one given by -ssldir.) This is a useful way for other OpenSSL
2260 applications (e.g. stunnel) to access all of the certs without
2261 having to concatenate them. x11vnc will not use them unless you
2262 specifically reference them. "HASHOFF" removes these HASH sub‐
2263 dirs.
2264 The LIST, LISTL, LL, ALL, HASHON, HASHOFF words can also be low‐
2266 ercase, e.g. "list".
2267 -sslDelCert pem
2269 Prompts you to delete all .crt .pem .key .req files associated
2271 with [pem]. x11vnc then exits. "SAVE" and lookups as in
2272 -sslCertInfo apply as well.
2273 -sslScripts
2275 Prints out both the 'genCA' and 'genCert' x11vnc openssl wrapper
2277 scripts for you to examine, modify, etc. The scripts are
2278 printed to stdout and then the x11vnc program exits.
2279 -stunnel [pem]
2281 Use the stunnel(8) (stunnel.mirt.net) to provide an encrypted
2283 SSL tunnel between viewers and x11vnc.
2284 This external tunnel method was implemented prior to the inte‐
2286 grated -ssl encryption described above. It still works well and
2287 avoids the requirement of linking with the OpenSSL libraries.
2288 This mode requires stunnel to be installed on the system and
2289 available via PATH (n.b. stunnel is often installed in sbin
2290 directories). Version 4.x of stunnel is assumed (but see -stun‐
2291 nel3 below.)
2292 [pem] is optional, use "-stunnel /path/to/stunnel.pem" to spec‐
2294 ify a PEM certificate file to pass to stunnel. See the -ssl
2295 option for more info on certificate files.
2296 Whether or not your stunnel has its own certificate depends on
2298 your stunnel configuration; stunnel often generates one at
2299 install time. See your stunnel documentation for details. In
2300 any event, if you want to use this certificate you must supply
2301 the full path to it as [pem]. Note: the file may only be read‐
2302 able by root.
2303 [pem] may also be the special strings "TMP", "SAVE", and
2305 "SAVE..." as described in the -ssl option. If [pem] is not sup‐
2306 plied, "SAVE" is assumed.
2307 Note that the VeNCrypt, ANONTLS, and "ANON" modes are not sup‐
2309 ported in -stunnel mode.
2310 stunnel is started up as a child process of x11vnc and any SSL
2312 connections stunnel receives are decrypted and sent to x11vnc
2313 over a local socket. The strings "The SSL VNC desktop is ..."
2314 and "SSLPORT=..." are printed out at startup to indicate this.
2315 The -localhost option is enforced by default to avoid people
2317 routing around the SSL channel. Use -env STUNNEL_DISABLE_LOCAL‐
2318 HOST=1 to disable this security requirement.
2319 Set -env STUNNEL_DEBUG=1 for more debugging printout.
2321 Set -env STUNNEL_PROG=xxx to the full path of stunnel program
2323 you want to be used (e.g. /usr/bin/stunnel4).
2324 Set -env STUNNEL_LISTEN=xxx to the address of the network inter‐
2326 face to listen on (the default is to listen on all interfaces),
2327 e.g. STUNNEL_LISTEN=192.168.1.100.
2328 A simple way to add IPv6 support is STUNNEL_LISTEN=::
2330 Your VNC viewer will also need to be able to connect via SSL.
2332 Unfortunately not too many do this. See the information about
2333 SSL viewers under the -ssl option. The x11vnc project's SSVNC
2334 is an option.
2335 Also, in the x11vnc distribution, patched TightVNC and UltraVNC
2337 Java applet jar files are provided in the classes/ssl directory
2338 that do SSL connections. Enable serving them with the -http,
2339 -http_ssl, or -httpdir (see the option descriptions for more
2340 info.)
2341 Note that for the Java viewer applet usage the "?PORT=xxxx" in
2343 the various URLs printed at startup will need to be supplied to
2344 the web browser to connect properly.
2345 Currently the automatic "single port" HTTPS mode of -ssl is not
2347 fully supported in -stunnel mode. However, it can be emulated
2348 via:
2349 % x11vnc -stunnel -http_ssl -http_oneport ...
2351 In general, it is also not too difficult to set up an stunnel or
2353 other SSL tunnel on the viewer side. A simple example on Unix
2354 using stunnel 3.x is:
2355 % stunnel -c -d localhost:5901 -r remotehost:5900 % vncviewer
2357 localhost:1
2358 For Windows, stunnel has been ported to it and there are proba‐
2360 bly other such tools available. See the FAQ and SSVNC for more
2361 examples.
2362 -stunnel3 [pem]
2364 Use version 3.x stunnel command line syntax instead of version
2366 4.x. The -http/-httpdir Java applet serving is currently not
2367 available in this mode.
2368 -enc cipher:keyfile
2370 Use symmetric encryption with cipher "cipher" and secret key
2372 data in "keyfile". If keyfile is pw=<string> then "string" is
2373 used as the key data.
2374 NOTE: It is recommended that you use SSL via the -ssl option
2376 instead of this option because SSL is well understood and takes
2377 great care to establish unique session keys and is more compati‐
2378 ble with other software. Use this option if you do not want to
2379 deal with SSL certificates for authentication and do not want to
2380 use SSH but want some encryption for your VNC session. Or if
2381 you must interface with a symmetric key tunnel that you do not
2382 have control over.
2383 Note that this mode will NOT work with the UltraVNC DSM plugins
2385 because they alter the RFB protocol in addition to tunnelling
2386 with the symmetric cipher (an unfortunate choice of implementa‐
2387 tion...)
2388 cipher can be one of: arc4, aesv2, aes-cfb, blowfish, aes256,
2390 or 3des. See the OpenSSL documentation for more info. The key‐
2391 size is 128 bits (except for aes256). Here is one way to make a
2392 keyfile with that many bits:
2393 dd if=/dev/random of=./my.key bs=16 count=1
2395 you will need to securely share this key with the other side of
2397 the VNC connection (See SSVNC for examples).
2398 Example: -enc blowfish:./my.key Example: -enc blow‐
2400 fish:pw=swordfish
2401 By default 16 bytes of random salt followed by 16 bytes of ran‐
2403 dom initialization vector are sent at the very beginning of the
2404 stream. The other side must read these and initialize their
2405 cipher with them. These values make the session key unique
2406 (without them the security is minimal). Similarly, the other
2407 side must send us its random salt and IV with those same
2408 lengths.
2409 The salt and key data are combined to create a session key using
2411 an md5 hash as described in EVP_BytesToKey(3).
2412 The exact call is: EVP_BytesToKey(Cipher, EVP_md5(), salt, key‐
2414 data, len, 1, keystr, NULL); where salt is the random data as
2415 described above, and keydata is the shared secret key data.
2416 keystr is the resulting session key. The cipher is then seeded
2417 with keystr and uses the random initialization vector as its
2418 first block.
2419 To modify the amount of random salt and initialization vector
2421 use cipher@n,m where n is the salt length and m the initializa‐
2422 tion vector length. E.g.
2423 -enc aes-cfb@8,16:./my.key
2425 It is not a good idea to set either one to zero, although you
2427 may be forced to if the other side of the tunnel is not under
2428 your control.
2429 To skip the salt and EVP_BytesToKey MD5 entirely (no hashing is
2431 done: the keydata is directly inserted into the cipher) specify
2432 "-1" for the salt, e.g.
2433 -enc blowfish@-1,16:./my.key
2435 The message digest can also be changed to something besides the
2437 default MD5. Use cipher@md+n,m where "md" can be one of sha,
2438 sha1, md5, or ripe. For example:
2439 -enc arc4@sha+8,16:./my.key
2441 The SSVNC vnc viewer project supplies a symmetric encryption
2443 tool named "ultravnc_dsm_helper" that can be used on the viewer
2444 side. For example:
2445 ssvncviewer exec='ultravnc_dsm_helper arc4 my.key 0 h:p'
2447 where h:p is the hostname and port of the x11vnc server. ultra‐
2449 vnc_dsm_helper may also be used standalone to provide a symmet‐
2450 ric encryption tunnel for any viewer or server (VNC or other‐
2451 wise.) The cipher (1st arg) is basically the same syntax as we
2452 use above.
2453 Also see the 'Non-Ultra DSM' SSVNC option for the ´UltraVNC DSM
2455 Encryption Plugin' advanced option.
2456 For both ways of using the viewer, you can specify the salt,ivec
2458 sizes (in GUI or, e.g. arc4@8,16).
2459 -https [port]
2461 Use a special, separate HTTPS port (-ssl and -stunnel modes
2463 only) for HTTPS Java viewer applet downloading. I.e. not 5900
2464 and not 5800 (the defaults.)
2465 BACKGROUND: In -ssl mode, it turns out you can use the single
2467 VNC port (e.g. 5900) for both VNC and HTTPS connections. (HTTPS
2468 is used to retrieve a SSL-aware VncViewer.jar applet that is
2469 provided with x11vnc). Since both use SSL the implementation
2470 was extended to detect if HTTP traffic (i.e. GET) is taking
2471 place and handle it accordingly. The URL would be, e.g.:
2472 https://mymachine.org:5900/
2474 This is convenient for firewalls, etc, because only one port
2476 needs to be allowed in. However, this heuristic adds a few sec‐
2477 onds delay to each connection and can be unreliable (especially
2478 if the user takes much time to ponder the Certificate dialogs in
2479 his browser, Java VM, or VNC Viewer applet. That's right 3 sep‐
2480 arate "Are you sure you want to connect?" dialogs!)
2481 END OF BACKGROUND.
2483 USAGE: So use the -https option to provide a separate, more
2485 reliable HTTPS port that x11vnc will listen on. If [port] is
2486 not provided (or is 0), one is autoselected. The URL to use is
2487 printed out at startup.
2488 The SSL Java applet directory is specified via the -httpdir
2490 option. If not supplied, -https will try to guess the directory
2491 as though the -http option was supplied.
2492 -httpsredir [port]
2494 In -ssl mode with the Java applet retrieved via HTTPS, when the
2496 HTML file containing applet parameters ('index.vnc' or
2497 'proxy.vnc') is sent do NOT set the applet PORT parameter to the
2498 actual VNC port but set it to "port" instead. If "port" is not
2499 supplied, then the port number is guessed from the Host: HTTP
2500 header.
2501 This is useful when an incoming TCP connection redirection is
2503 performed by a router/gateway/firewall from one port to an
2504 internal machine where x11vnc is listening on a different port.
2505 The Java applet needs to connect to the firewall/router port,
2506 not the VNC port on the internal workstation. For example, one
2507 could redir from mygateway.com:443 to workstation:5900.
2508 This spares the user from having to type in https://mygate‐
2510 way.com/?PORT=443 into their web browser. Note that port 443 is
2511 the default https port; other ports must be explicitly indi‐
2512 cated, for example: https://mygateway.com:8000/?PORT=8000. To
2513 avoid having to include the PORT= in the browser URL, simply
2514 supply "-httpsredir" to x11vnc.
2515 This option does not work in -stunnel mode.
2517 More tricks: set the env var X11VNC_EXTRA_HTTPS_PARAMS to be
2519 extra URL parameters to use. This way you do not need to spec‐
2520 ify extra PARAMS in the index.vnc file. E.g. x11vnc -env
2521 X11VNC_EXTRA_HTTPS_PARAMS='?GET=1' ...
2522 If you do not want to expose the non-SSL HTTP port to the net‐
2524 work (i.e. you just want the single VNC/HTTPS port, e.g. 5900,
2525 open for connections) then specify the option -env
2526 X11VNC_HTTP_LISTEN_LOCALHOST=1 This way the connection to the
2527 LibVNCServer httpd server will only be available on localhost
2528 (note that in -ssl mode, HTTPS requests are redirected from SSL
2529 to the non-SSL LibVNCServer HTTP server.)
2530 -http_oneport
2532 For UN-encrypted connections mode (i.e. no -ssl, -stunnel, or
2534 -enc options), allow the Java VNC Viewer applet to be downloaded
2535 thru the VNC port via HTTP.
2536 That is to say, you can use a single port for Java applet viewer
2538 connections by using a URL in your web browser like this, for
2539 example:
2540 http://hostname:5900
2542 The regular, two-port mode, URL http://hostname:5800 will con‐
2544 tinue to work as well.
2545 As mentioned above, this mode will NOT work with the -ssl,
2547 -stunnel, or -enc encryption options. Note that is it equiva‐
2548 lent to '-enc none' (i.e. it uses the same detection mechanism
2549 as for HTTPS, but with no encryption.)
2550 HTTPS single-port is on by default in -ssl encrypted mode (and
2552 -enc too), so you only need -http_oneport when doing non-SSL
2553 encrypted connections.
2554 This mode could also be useful for SSH tunnels since it means
2556 only one port needs to be redirected.
2557 The -httpsredir option may also be useful for this mode when
2559 using an SSH tunnel as well as for router port redirections.
2560 Note that the -env X11VNC_HTTP_LISTEN_LOCALHOST=1 option
2562 described above under -httpsredir applies for the LibVNCServer
2563 httpd server in all cases (ssl or not.)
2564 -ssh user@host:disp
2566 Create a remote listening port on machine "host" via a SSH tun‐
2568 nel using the -R rport:localhost:lport method. lport will be the
2569 local x11vnc listening port, so a connection to rport
2570 (5900+disp) on "host" will reach x11vnc. E.g. fred@snoopy.com:0
2571 This could be useful if a firewall/router prevents incoming con‐
2573 nections to the x11vnc machine, but the ssh machine "host" can
2574 be reached by the VNC viewer. "user@" is not needed unless the
2575 remote unix username differs from the current one.
2576 By default the remote sshd is usually configured to listen only
2578 on localhost for rport, so the viewer may need to ssh -L redir
2579 to "host" as well (See SSVNC to automate this). The sshd set‐
2580 ting GatewayPorts enables listening on all interfaces for rport;
2581 viewers can reach it more easily.
2582 "disp" is the VNC display for the remote SSH side, e.g. 0 corre‐
2584 sponds to port 5900, etc. If disp is greater than 200 the value
2585 is used as the port. Use a negative value to force a low port,
2586 e.g. host:-80 will use port 80.
2587 If ssh-agent is not active, then the ssh password needs to be
2589 entered in the terminal where x11vnc is running.
2590 By default the remote ssh will issue a 'sleep 300' to wait for
2592 the incoming connection for 5 mins. To modify this use
2593 user@host:disp+secs.
2594 If the remote SSH server is on a non-standard port (i.e. not 22)
2596 use user@host:port:disp+secs.
2597 Note that the ssh process MAY NOT be killed when x11vnc exits.
2599 It tries by looking at ps(1) output.
2600 -usepw
2602 If no other password method was supplied on the command line,
2604 first look for ~/.vnc/passwd and if found use it with -rfbauth;
2605 next, look for ~/.vnc/passwdfile and use it with -passwdfile;
2606 otherwise, prompt the user for a password to create
2607 ~/.vnc/passwd and use it with the -rfbauth option. If none of
2608 these succeed x11vnc exits immediately.
2609 -storepasswd pass file
2611 Store password pass as the VNC password in the file file. Once
2613 the password is stored the program exits. Use the password via
2614 "-rfbauth file"
2615 If called with no arguments, "x11vnc -storepasswd", the user is
2617 prompted for a password and it is stored in the file
2618 ~/.vnc/passwd. Called with one argument, that will be the file
2619 to store the prompted password in.
2620 -nopw
2622 Disable the big warning message when you use x11vnc without some
2624 sort of password.
2625 -accept string
2627 Run a command (possibly to prompt the user at the X11 display)
2629 to decide whether an incoming client should be allowed to con‐
2630 nect or not. string is an external command run via system(3) or
2631 some special cases described below. Be sure to quote string if
2632 it contains spaces, shell characters, etc. If the external com‐
2633 mand returns 0 the client is accepted, otherwise the client is
2634 rejected. See below for an extension to accept a client view-
2635 only.
2636 If x11vnc is running as root (say from inetd(8) or from display
2638 managers xdm(1) , gdm(1) , etc), think about the security impli‐
2639 cations carefully before supplying this option (likewise for the
2640 -gone option).
2641 Environment: The RFB_CLIENT_IP environment variable will be set
2643 to the incoming client IP number and the port in RFB_CLIENT_PORT
2644 (or -1 if unavailable). Similarly, RFB_SERVER_IP and
2645 RFB_SERVER_PORT (the x11vnc side of the connection), are set to
2646 allow identification of the tcp virtual circuit. The x11vnc
2647 process id will be in RFB_X11VNC_PID, a client id number in
2648 RFB_CLIENT_ID, and the number of other connected clients in
2649 RFB_CLIENT_COUNT. RFB_MODE will be "accept". RFB_STATE will be
2650 PROTOCOL_VERSION, SECURITY_TYPE, AUTHENTICATION, INITIALISATION,
2651 NORMAL, or UNKNOWN indicating up to which state the client has
2652 achieved. RFB_LOGIN_VIEWONLY will be 0, 1, or -1 (unknown).
2653 RFB_USERNAME, RFB_LOGIN_TIME, and RFB_CURRENT_TIME may also be
2654 set.
2655 If string is "popup" then a builtin popup window is used. The
2657 popup will time out after 120 seconds, use "popup:N" to modify
2658 the timeout to N seconds (use 0 for no timeout).
2659 In the case of "popup" and when the -unixpw option is specified,
2661 then a *second* window will be popped up after the user success‐
2662 fully logs in via his UNIX password. This time the user will be
2663 identified as UNIX:username@hostname, the "UNIX:" prefix indi‐
2664 cates which user the viewer logged as via -unixpw. The first
2665 popup is only for whether to allow him to even *try* to login
2666 via unix password.
2667 If string is "xmessage" then an xmessage(1) invocation is used
2669 for the command. xmessage must be installed on the machine for
2670 this to work.
2671 Both "popup" and "xmessage" will present an option for accepting
2673 the client "View-Only" (the client can only watch). This option
2674 will not be presented if -viewonly has been specified, in which
2675 case the entire display is view only.
2676 If the user supplied command is prefixed with something like
2678 "yes:0,no:*,view:3 mycommand ..." then this associates the
2679 numerical command return code with the actions: accept, reject,
2680 and accept-view-only, respectively. Use "*" instead of a number
2681 to indicate the default action (in case the command returns an
2682 unexpected value). E.g. "no:*" is a good choice.
2683 Note that x11vnc blocks while the external command or popup is
2685 running (other clients may see no updates during this period).
2686 So a person sitting a the physical display is needed to respond
2687 to an popup prompt. (use a 2nd x11vnc if you lock yourself out).
2688 More -accept tricks: use "popupmouse" to only allow mouse clicks
2690 in the builtin popup to be recognized. Similarly use "popupkey"
2691 to only recognize keystroke responses. These are to help avoid
2692 the user accidentally accepting a client by typing or clicking.
2693 All 3 of the popup keywords can be followed by +N+M to supply a
2694 position for the popup window. The default is to center the
2695 popup window.
2696 -afteraccept string
2698 As -accept, except to run a user supplied command after a client
2700 has been accepted and authenticated. RFB_MODE will be set to
2701 "afteraccept" and the other RFB_* variables are as in -accept.
2702 Unlike -accept, the command return code is not interpreted by
2703 x11vnc. Example: -afteraccept 'killall xlock &'
2704 -gone string
2706 As -accept, except to run a user supplied command when a client
2708 goes away (disconnects). RFB_MODE will be set to "gone" and the
2709 other RFB_* variables are as in -accept. The "popup" actions
2710 apply as well. Unlike -accept, the command return code is not
2711 interpreted by x11vnc. Example: -gone 'xlock &'
2712 -users list
2714 If x11vnc is started as root (say from inetd(8) or from display
2716 managers xdm(1) , gdm(1) , etc), then as soon as possible after
2717 connections to the X display are established try to switch to
2718 one of the users in the comma separated list. If x11vnc is not
2719 running as root this option is ignored.
2720 Why use this option? In general it is not needed since x11vnc
2722 is already connected to the X display and can perform its pri‐
2723 mary functions. The option was added to make some of the
2724 *external* utility commands x11vnc occasionally runs work prop‐
2725 erly. In particular under GNOME and KDE to implement the
2726 "-solid color" feature external commands (gconftool-2 and dcop)
2727 unfortunately must be run as the user owning the desktop ses‐
2728 sion. Since this option switches userid it also affects the
2729 userid used to run the processes for the -accept and -gone
2730 options. It also affects the ability to read files for options
2731 such as -connect, -allow, and -remap and also the ultra and
2732 tight filetransfer feature if enabled. Note that the -connect
2733 file is also sometimes written to.
2734 So be careful with this option since in some situations its use
2736 can decrease security.
2737 In general the switch to a user will only take place if the dis‐
2739 play can still be successfully opened as that user (this is pri‐
2740 marily to try to guess the actual owner of the session). Exam‐
2741 ple: "-users fred,wilma,betty". Note that a malicious local
2742 user "barney" by quickly using "xhost +" when logging in may
2743 possibly get the x11vnc process to switch to user "fred". What
2744 happens next?
2745 Under display managers it may be a long time before the switch
2747 succeeds (i.e. a user logs in). To instead make it switch imme‐
2748 diately regardless if the display can be reopened prefix the
2749 username with the "+" character. E.g. "-users +bob" or "-users
2750 +nobody".
2751 The latter (i.e. switching immediately to user "nobody") is the
2753 only obvious use of the -users option that increases security.
2754 Use the following notation to associate a group with a user:
2756 user1.group1,user2.group2,... Note that initgroups(2) will
2757 still be called first to try to switch to ALL of a user's groups
2758 (primary and additional groups). Only if that fails or it is
2759 not available then the single group specified as above (or the
2760 user's primary group if not specified) is switched to with set‐
2761 gid(2). Use -env X11VNC_SINGLE_GROUP=1 to prevent trying init‐
2762 groups(2) and only switch to the single group. This sort of
2763 setting is only really needed to make the ultra or tight file‐
2764 transfer permissions work properly. This format applies to any
2765 comma separated list of users, even the special "=" modes
2766 described below.
2767 In -unixpw mode, if "-users unixpw=" is supplied then after a
2769 user authenticates himself via the -unixpw mechanism, x11vnc
2770 will try to switch to that user as though "-users +username" had
2771 been supplied. If you want to limit which users this will be
2772 done for, provide them as a comma separated list after "unixpw="
2773 Groups can also be specified as described above.
2774 Similarly, in -ssl mode, if "-users sslpeer=" is supplied then
2776 after an SSL client authenticates with his cert (the -sslverify
2777 option is required for this) x11vnc will extract a UNIX username
2778 from the "emailAddress" field (username@hostname.com) of the
2779 "Subject" of the x509 SSL cert and then try to switch to that
2780 user as though "-users +username" had been supplied. If you
2781 want to limit which users this will be done for, provide them as
2782 a comma separated list after "sslpeer=". Set the env. var
2783 X11VNC_SSLPEER_CN to use the Common Name (normally a hostname)
2784 instead of the Email field.
2785 NOTE: for sslpeer= mode the x11vnc administrator must take care
2787 that any client certs he adds to -sslverify have the intended
2788 UNIX username in the "emailAddress" field of the cert. Other‐
2789 wise a user may be able to log in as another. This command can
2790 be of use in checking: "openssl x509 -text -in file.crt", see
2791 the "Subject:" line. Also, along with the normal RFB_* env.
2792 vars. (see -accept) passed to external cmd= commands,
2793 RFB_SSL_CLIENT_CERT will be set to the client's x509 certificate
2794 string.
2795 The sslpeer= mode can aid finding X sessions via the FINDDISPLAY
2797 and FINDCREATEDISPLAY mechanisms.
2798 To immediately switch to a user *before* connections to the X
2800 display are made or any files opened use the "=" character:
2801 "-users =bob". That user needs to be able to open the X display
2802 and any files of course.
2803 The special user "guess=" means to examine the utmpx database
2805 (see who(1) ) looking for a user attached to the display number
2806 (from DISPLAY or -display option) and try him/her. To limit the
2807 list of guesses, use: "-users guess=bob,betty".
2808 Even more sinister is the special user "lurk=" that means to try
2810 to guess the DISPLAY from the utmpx login database as well. So
2811 it "lurks" waiting for anyone to log into an X session and then
2812 connects to it. Specify a list of users after the = to limit
2813 which users will be tried. To enable a different searching
2814 mode, if the first user in the list is something like ":0" or
2815 ":0-2" that indicates a range of DISPLAY numbers that will be
2816 tried (regardless of whether they are in the utmpx database) for
2817 all users that are logged in. Also see the "-display WAIT:..."
2818 functionality. Examples: "-users lurk=" and also "-users
2819 lurk=:0-1,bob,mary"
2820 Be especially careful using the "guess=" and "lurk=" modes.
2822 They are not recommended for use on machines with untrustworthy
2823 local users.
2824 -noshm
2826 Do not use the MIT-SHM extension for the polling. Remote dis‐
2828 plays can be polled this way: be careful this can use large
2829 amounts of network bandwidth. This is also of use if the local
2830 machine has a limited number of shm segments and -onetile is not
2831 sufficient.
2832 -flipbyteorder
2834 Sometimes needed if remotely polled host has different endian‐
2836 ness. Ignored unless -noshm is set.
2837 -onetile
2839 Do not use the new copy_tiles() framebuffer mechanism, just use
2841 1 shm tile for polling. Limits shm segments used to 3.
2842 To disable any automatic shm reduction set the env. var.
2844 X11VNC_NO_LIMIT_SHM.
2845 -solid [color]
2847 To improve performance, when VNC clients are connected try to
2849 change the desktop background to a solid color. The [color] is
2850 optional: the default color is "cyan4". For a different one
2851 specify the X color (rgb.txt name, e.g. "darkblue" or numerical
2852 "#RRGGBB").
2853 Currently this option only works on GNOME, KDE, CDE, XFCE, and
2855 classic X (i.e. with the background image on the root window).
2856 The "gconftool-2", "dcop" and "xfconf-query" external commands
2857 are run for GNOME, KDE, and XFCE respectively. This also works
2858 on native MacOSX. (There is no color selection for MacOSX or
2859 XFCE.) Other desktops won't work, (send us the corresponding
2860 commands if you find them). If x11vnc is running as root (
2861 inetd(8) or gdm(1) ), the -users option may be needed for GNOME,
2862 KDE, XFCE. If x11vnc guesses your desktop incorrectly, you can
2863 force it by prefixing color with "gnome:", "kde:", "cde:",
2864 "xfce:", or "root:".
2865 Update: -solid no longer works on KDE4.
2867 This mode works in a limited way on the Mac OS X Console with
2869 one color ('kelp') using the screensaver writing to the back‐
2870 ground. Look in "~/Library/Screen Savers" for VncSolidColor.png
2871 to change the color.
2872 -blackout string
2874 Black out rectangles on the screen. string is a comma separated
2876 list of WxH+X+Y type geometries for each rectangle. If one of
2877 the items on the list is the string "noptr" the mouse pointer
2878 will not be allowed to go into a blacked out region.
2879 -xinerama, -noxinerama
2881 If your screen is composed of multiple monitors glued together
2883 via XINERAMA, and that screen is not a rectangle this option
2884 will try to guess the areas to black out (if your system has
2885 libXinerama). default: -xinerama
2886 In general, we have noticed on XINERAMA displays you may need to
2888 use the "-xwarppointer" option if the mouse pointer misbehaves
2889 and it is enabled by default. Use "-noxwarppointer" if you do
2890 not want this.
2891 -xtrap
2893 Use the DEC-XTRAP extension for keystroke and mouse input inser‐
2895 tion. For use on legacy systems, e.g. X11R5, running an incom‐
2896 plete or missing XTEST extension. By default DEC-XTRAP will be
2897 used if XTEST server grab control is missing, use -xtrap to do
2898 the keystroke and mouse insertion via DEC-XTRAP as well.
2899 -xrandr [mode]
2901 If the display supports the XRANDR (X Resize, Rotate and Reflec‐
2903 tion) extension, and you expect XRANDR events to occur to the
2904 display while x11vnc is running, this options indicates x11vnc
2905 should try to respond to them (as opposed to simply crashing by
2906 assuming the old screen size). See the xrandr(1) manpage and
2907 run ´xrandr -q' for more info. [mode] is optional and described
2908 below.
2909 Since watching for XRANDR events and trapping errors increases
2911 polling overhead, only use this option if XRANDR changes are
2912 expected. For example on a rotatable screen PDA or laptop, or
2913 using a XRANDR-aware Desktop where you resize often. It is best
2914 to be viewing with a vncviewer that supports the NewFBSize
2915 encoding, since it knows how to react to screen size changes.
2916 Otherwise, LibVNCServer tries to do so something reasonable for
2917 viewers that cannot do this (portions of the screen may be
2918 clipped, unused, etc).
2919 Note: the default now is to check for XRANDR events, but do not
2921 trap every X call that may fail due to resize. If a resize
2922 event is received, the full -xrandr mode is enabled. To disable
2923 even checking for events supply: -noxrandr.
2924 "mode" defaults to "resize", which means create a new, resized,
2926 framebuffer and hope all viewers can cope with the change.
2927 "newfbsize" means first disconnect all viewers that do not sup‐
2928 port the NewFBSize VNC encoding, and then resize the frame‐
2929 buffer. "exit" means disconnect all viewer clients, and then
2930 terminate x11vnc.
2931 -rotate string
2933 Rotate and/or flip the framebuffer view exported by VNC. This
2935 transformation is independent of XRANDR and is done in software
2936 in main memory and so may be slower. This mode could be useful
2937 on a handheld with portrait or landscape modes that do not cor‐
2938 respond to the scanline order of the actual framebuffer. string
2939 can be:
2940 x flip along x-axis y flip along y-axis xy flip
2942 along x- and y-axes +90 rotate 90 degrees clockwise -90
2943 rotate 90 degrees counter-clockwise +90x rotate 90 degrees
2944 CW, then flip along x +90y rotate 90 degrees CW, then flip
2945 along y
2946 these give all possible rotations and reflections.
2948 Aliases: same as xy: yx, +180, -180, 180 same as -90: +270, 270
2950 same as +90: 90, (ditto for 90x, 90y)
2951 Like -scale, this transformation is applied at the very end of
2953 any chain of framebuffer transformations and so any options with
2954 geometries, e.g. -blackout, -clip, etc. are relative to the
2955 original X (or -rawfb) framebuffer, not the final one sent to
2956 VNC viewers.
2957 If you do not want the cursor shape to be rotated prefix string
2959 with "nc:", e.g. "nc:+90", "nc:xy", etc.
2960 -padgeom WxH
2962 Whenever a new vncviewer connects, the framebuffer is replaced
2964 with a fake, solid black one of geometry WxH. Shortly after‐
2965 wards the framebuffer is replaced with the real one. This is
2966 intended for use with vncviewers that do not support NewFBSize
2967 and one wants to make sure the initial viewer geometry will be
2968 big enough to handle all subsequent resizes (e.g. under -xrandr,
2969 -remote id:windowid, rescaling, etc.)
2970 In -unixpw mode this sets the size of the login screen. Use
2972 "once:WxH" it ignore padgeom after the login screen is set up.
2973 -o logfile
2975 Write stderr messages to file logfile instead of to the termi‐
2977 nal. Same as "-logfile file". To append to the file use "-oa
2978 file" or "-logappend file". If logfile contains the string
2979 "%VNCDISPLAY" it is expanded to the vnc display (the name may
2980 need to be guessed at.) "%HOME" works too.
2981 -flag file
2983 Write the "PORT=NNNN" (e.g. PORT=5900) string to file in addi‐
2985 tion to stdout. This option could be useful by wrapper script
2986 to detect when x11vnc is ready.
2987 -rmflag file
2989 Remove file at exit to signal when x11vnc is done. The file is
2991 created at startup if it does not already exist or if file is
2992 prefixed with "create:". If the file is created, the x11vnc PID
2993 is placed in the file. Otherwise the files contents is not
2994 changed. Use prefix "nocreate:" to prevent creation.
2995 -rc filename
2997 Use filename instead of $HOME/.x11vncrc for rc file.
2999 -norc
3001 Do not process any .x11vncrc file for options.
3003 -env VAR=VALUE
3005 Set the environment variable 'VAR' to value 'VALUE' at x11vnc
3007 startup. This is a convenience utility to avoid shell script
3008 wrappers, etc. to set the env. var. You may specify as many of
3009 these as needed on the command line.
3010 -prog /path/to/x11vnc
3012 Set the full path to the x11vnc program for cases when it cannot
3014 be determined from argv[0] (e.g. tcpd/inetd)
3015 -h, -help
3017 Print this help text. -?, -opts Only list the
3019 x11vnc options.
3020 -V, -version
3022 Print program version and last modification date.
3024 -license
3026 Print out license information. Same as -copying and -warranty.
3028 -dbg
3030 Instead of exiting after cleaning up, run a simple "debug crash
3032 shell" when fatal errors are trapped.
3033 -q, -quiet
3035 Be quiet by printing less informational output to stderr. (use
3037 -noquiet to undo an earlier -quiet.)
3038 The -quiet option does not eliminate all informational output,
3040 it only reduces it. It is ignored in most auxiliary usage
3041 modes, e.g. -storepasswd. To eliminate all output use:
3042 2>/dev/null 1>&2, etc.
3043 -v, -verbose
3045 Print out more information to stderr.
3047 -bg
3049 Go into the background after screen setup. Messages to stderr
3051 are lost unless -o logfile is used. Something like this could
3052 be useful in a script:
3053 port=`ssh -t $host "x11vnc -display :0 -bg" | grep PORT`
3055 port=`echo "$port" | sed -e 's/PORT=//'`
3057 port=`expr $port - 5900`
3059 vncviewer $host:$port
3061 -modtweak, -nomodtweak
3063 Option -modtweak automatically tries to adjust the AltGr and
3065 Shift modifiers for differing language keyboards between client
3066 and host. Otherwise, only a single key press/release of a Key‐
3067 code is simulated (i.e. ignoring the state of the modifiers:
3068 this usually works for identical keyboards). Also useful in
3069 resolving cases where a Keysym is bound to multiple keys (e.g.
3070 "<" + ">" and "," + "<" keys). Default: -modtweak
3071 If you are having trouble with with keys and -xkb or -noxkb, and
3073 similar things don't help, try -nomodtweak.
3074 On some HP-UX systems it is been noted that they have an odd
3076 keymapping where a single keycode will have a keysym, e.g. "#",
3077 up to three times. You can check via "xmodmap -pk" or the -dk
3078 option. The failure is when you try to type "#" it yields "3".
3079 If you see this problem try setting the environment variable
3080 MODTWEAK_LOWEST=1 to see if it helps.
3081 -xkb, -noxkb
3083 When in modtweak mode, use the XKEYBOARD extension (if the X
3085 display supports it) to do the modifier tweaking. This is pow‐
3086 erful and should be tried if there are still keymapping problems
3087 when using -modtweak by itself. The default is to check whether
3088 some common keysyms, e.g. !, @, [, are only accessible via -xkb
3089 mode and if so then automatically enable the mode. To disable
3090 this automatic detection use -noxkb.
3091 When -xkb mode is active you can set these env. vars. They
3093 apply only when there is ambiguity as to which key to choose
3094 (i.e the mapping is not one-to-one). NOKEYHINTS=1: for up ascii
3095 keystrokes do not use score hints saved when the key was pressed
3096 down. NOANYDOWN=1: for up keystrokes do not resort to searching
3097 through keys that are currently pressed down. KEYSDOWN=N:
3098 remember the last N keys press down for tie-breaking when an up
3099 keystroke comes in.
3100 -capslock
3102 When in -modtweak (the default) or -xkb mode, if a keysym in the
3104 range A-Z comes in check the X server to see if the Caps_Lock is
3105 set. If it is do not artificially press Shift to generate the
3106 keysym. This will enable the CapsLock key to behave correctly
3107 in some circumstances: namely *both* the VNC viewer machine and
3108 the x11vnc X server are in the CapsLock on state. If one side
3109 has CapsLock on and the other off and the keyboard is not behav‐
3110 ing as you think it should you should correct the CapsLock
3111 states (hint: pressing CapsLock inside and outside of the viewer
3112 can help toggle them both to the correct state). However, for
3113 best results do not use this option, but rather *only* enable
3114 CapsLock on the VNC viewer side (i.e. by pressing CapsLock out‐
3115 side of the viewer window, also -skip_lockkeys below). Also try
3116 -nomodtweak for a possible workaround.
3117 -skip_lockkeys, -noskip_lockkeys
3119 Have x11vnc ignore all Caps_Lock, Shift_Lock, Num_Lock,
3121 Scroll_Lock keysyms received from viewers. The idea is you
3122 press Caps_Lock on the VNC Viewer side but that does not change
3123 the lock state in the x11vnc-side X server. Nevertheless your
3124 capitalized letters come in over the wire and are applied cor‐
3125 rectly to the x11vnc-side X server. Note this mode probably
3126 won't do what you want in -nomodtweak mode. Also, a kludge for
3127 KP_n digits is always done in this mode: they are mapped to reg‐
3128 ular digit keysyms. See also -capslock above. The default is
3129 -noskip_lockkeys.
3130 -skip_keycodes string
3132 Ignore the comma separated list of decimal keycodes. Perhaps
3134 these are keycodes not on your keyboard but your X server thinks
3135 exist. Currently only applies to -xkb mode. Use this option to
3136 help x11vnc in the reverse problem it tries to solve: Keysym ->
3137 Keycode(s) when ambiguities exist (more than one Keycode per
3138 Keysym). Run 'xmodmap -pk' to see your keymapping. Example:
3139 "-skip_keycodes 94,114"
3140 -sloppy_keys
3142 Experimental option that tries to correct some "sloppy" key
3144 behavior. E.g. if at the viewer you press Shift+Key but then
3145 release the Shift before Key that could give rise to extra
3146 unwanted characters (usually only between keyboards of different
3147 languages). Only use this option if you observe problems with
3148 some keystrokes.
3149 -skip_dups, -noskip_dups
3151 Some VNC viewers send impossible repeated key events, e.g. key-
3153 down, key-down, key-up, key-up all for the same key, or 20 downs
3154 in a row for the same modifier key! Setting -skip_dups means to
3155 skip these duplicates and just process the first event. Note:
3156 some VNC viewers assume they can send down's without the corre‐
3157 sponding up's and so you should not set this option for these
3158 viewers (symptom: some keys do not autorepeat) Default:
3159 -noskip_dups
3160 -add_keysyms, -noadd_keysyms
3162 If a Keysym is received from a VNC viewer and that Keysym does
3164 not exist in the X server, then add the Keysym to the X server's
3165 keyboard mapping on an unused key. Added Keysyms will be
3166 removed periodically and also when x11vnc exits. Default:
3167 -add_keysyms
3168 -clear_mods
3170 At startup and exit clear the modifier keys by sending KeyRe‐
3172 lease for each one. The Lock modifiers are skipped. Used to
3173 clear the state if the display was accidentally left with any
3174 pressed down.
3175 -clear_keys
3177 As -clear_mods, except try to release ANY pressed key. Note
3179 that this option and -clear_mods can interfere with a person
3180 typing at the physical keyboard.
3181 -clear_all
3183 As -clear_keys, except try to release any CapsLock, NumLock,
3185 etc. locks as well.
3186 -remap string
3188 Read Keysym remappings from file named string. Format is one
3190 pair of Keysyms per line (can be name or hex value) separated by
3191 a space. If no file named string exists, it is instead inter‐
3192 preted as this form: key1-key2,key3-key4,... See
3193 <X11/keysymdef.h> header file for a list of Keysym names, or use
3194 xev(1).
3195 To map a key to a button click, use the fake Keysyms "Button1",
3197 ..., etc. E.g: "-remap Super_R-Button2" (useful for pasting on a
3198 laptop)
3199 I use these if the machine I am viewing from does not have a
3201 scrollwheel or I don't like using the one it has:
3202 -remap Super_R-Button4,Menu-Button5 -remap KP_Add-But‐
3204 ton4,KP_Enter-Button5
3205 the former would be used on a PC, the latter on a MacBook. This
3207 way those little used keys can be used to generate bigger hops
3208 than the Up and Down arrows provide. One can scroll through
3209 text or web pages more quickly this way (especially if x11vnc
3210 scroll detection is active.)
3211 Use Button44, Button12, etc. for multiple clicks.
3213 To disable a keysym (i.e. make it so it will not be injected),
3215 remap it to "NoSymbol" or "None".
3216 Dead keys: "dead" (or silent, mute) keys are keys that do not
3218 produce a character but must be followed by a 2nd keystroke.
3219 This is often used for accenting characters, e.g. to put "`" on
3220 top of "a" by pressing the dead key and then "a". Note that
3221 this interpretation is not part of core X11, it is up to the
3222 toolkit or application to decide how to react to the sequence.
3223 The X11 names for these keysyms are "dead_grave", "dead_acute",
3224 etc. However some VNC viewers send the keysyms "grave", "acute"
3225 instead thereby disabling the accenting. To work around this
3226 -remap can be used. For example "-remap grave-dead_grave,acute-
3227 dead_acute"
3228 As a convenience, "-remap DEAD" applies these remaps:
3230 g grave-dead_grave
3232 a acute-dead_acute
3233 c asciicircum-dead_circumflex
3234 t asciitilde-dead_tilde
3235 m macron-dead_macron
3236 b breve-dead_breve
3237 D abovedot-dead_abovedot
3238 d diaeresis-dead_diaeresis
3239 o degree-dead_abovering
3240 A doubleacute-dead_doubleacute
3241 r caron-dead_caron
3242 e cedilla-dead_cedilla
3243 If you just want a subset use the first letter label, e.g.
3245 "-remap DEAD=ga" to get the first two. Additional remaps may
3246 also be supplied via commas, e.g. "-remap DEAD=ga,Super_R-But‐
3247 ton2". Finally, "DEAD=missing" means to apply all of the above
3248 as long as the left hand member is not already in the X11
3249 keymap.
3250 -norepeat, -repeat
3252 Option -norepeat disables X server key auto repeat when VNC
3254 clients are connected and VNC keyboard input is not idle for
3255 more than 5 minutes. This works around a repeating keystrokes
3256 bug (triggered by long processing delays between key down and
3257 key up client events: either from large screen changes or high
3258 latency). Default: -norepeat
3259 You can set the env. var. X11VNC_IDLE_TIMEOUT to the number of
3261 idle seconds you want (5min = 300secs).
3262 Note: your VNC viewer side will likely do autorepeating, so this
3264 is no loss unless someone is simultaneously at the real X dis‐
3265 play.
3266 Use "-norepeat N" to set how many times norepeat will be reset
3268 if something else (e.g. X session manager) undoes it. The
3269 default is 2. Use a negative value for unlimited resets.
3270 -nofb
3272 Ignore video framebuffer: only process keyboard and pointer.
3274 Intended for use with Win2VNC and x2vnc dual-monitor setups.
3275 -nobell
3277 Do not watch for XBell events. (no beeps will be heard) Note:
3279 XBell monitoring requires the XKEYBOARD extension.
3280 -nosel
3282 Do not manage exchange of X selection/cutbuffer between VNC
3284 viewers and the X server at all.
3285 -noprimary
3287 Do not poll the PRIMARY selection for changes to send back to
3289 clients. (PRIMARY is still set on received changes, however).
3290 -nosetprimary
3292 Do not set the PRIMARY selection for changes received from VNC
3294 clients.
3295 -noclipboard
3297 Do not poll the CLIPBOARD selection for changes to send back to
3299 clients. (CLIPBOARD is still set on received changes, however).
3300 -nosetclipboard
3302 Do not set the CLIPBOARD selection for changes received from VNC
3304 clients.
3305 -seldir string
3307 If direction string is "send", only send the selection to view‐
3309 ers, and if it is "recv" only receive it from viewers. To work
3310 around apps setting the selection too frequently and messing up
3311 the other end. You can actually supply a comma separated list
3312 of directions, including "debug" to turn on debugging output.
3313 -cursor [mode], -nocursor
3315 Sets how the pointer cursor shape (little icon at the mouse
3317 pointer) should be handled. The "mode" string is optional and
3318 is described below. The default is to show some sort of cursor
3319 shape(s). How this is done depends on the VNC viewer and the X
3320 server. Use -nocursor to disable cursor shapes completely.
3321 Some VNC viewers support the TightVNC CursorPosUpdates and Cur‐
3323 sorShapeUpdates extensions (cuts down on network traffic by not
3324 having to send the cursor image every time the pointer is
3325 moved), in which case these extensions are used (see -nocursor‐
3326 shape and -nocursorpos below to disable). For other viewers the
3327 cursor shape is written directly to the framebuffer every time
3328 the pointer is moved or changed and gets sent along with the
3329 other framebuffer updates. In this case, there will be some lag
3330 between the vnc viewer pointer and the remote cursor position.
3331 If the X display supports retrieving the cursor shape informa‐
3333 tion from the X server, then the default is to use that mode.
3334 On Solaris this can be done with the SUN_OVL extension using
3335 -overlay (see also the -overlay_nocursor option). A similar
3336 overlay scheme is used on IRIX. Xorg (e.g. Linux) and recent
3337 Solaris Xsun servers support the XFIXES extension to retrieve
3338 the exact cursor shape from the X server. If XFIXES is present
3339 it is preferred over Overlay and is used by default (see -nox‐
3340 fixes below). This can be disabled with -nocursor, and also
3341 some values of the "mode" option below.
3342 Note that under XFIXES cursors with transparency (alpha channel)
3344 will usually not be exactly represented and one may find Overlay
3345 preferable. See also the -alphacut and -alphafrac options below
3346 as fudge factors to try to improve the situation for cursors
3347 with transparency for a given theme.
3348 The "mode" string can be used to fine-tune the displaying of
3350 cursor shapes. It can be used the following ways:
3351 "-cursor arrow" - just show the standard arrow nothing more or
3353 nothing less.
3354 "-cursor none" - same as "-nocursor"
3356 "-cursor X" - when the cursor appears to be on the root window,
3358 draw the familiar X shape. Some desktops such as GNOME cover up
3359 the root window completely, and so this will not work, try "X1",
3360 etc, to try to shift the tree depth. On high latency links or
3361 slow machines there will be a time lag between expected and the
3362 actual cursor shape.
3363 "-cursor some" - like "X" but use additional heuristics to try
3365 to guess if the window should have a windowmanager-like resizer
3366 cursor or a text input I-beam cursor. This is a complete hack,
3367 but may be useful in some situations because it provides a lit‐
3368 tle more feedback about the cursor shape.
3369 "-cursor most" - try to show as many cursors as possible. Often
3371 this will only be the same as "some" unless the display has
3372 overlay visuals or XFIXES extensions available. On Solaris and
3373 IRIX if XFIXES is not available, -overlay mode will be
3374 attempted.
3375 -cursor_drag
3377 Show cursor shape changes even when the mouse is being dragged
3379 with a mouse button down. This is useful if you want to be able
3380 to see Drag-and-Drop cursor icons, etc.
3381 -arrow n
3383 Choose an alternate "arrow" cursor from a set of some common
3385 ones. n can be 1 to 6. Default is: 1 Ignored when in XFIXES
3386 cursor-grabbing mode.
3387 -noxfixes
3389 Do not use the XFIXES extension to draw the exact cursor shape
3391 even if it is available.
3392 Note: To work around a crash in Xorg 1.5 and later some people
3394 needed to use -noxfixes. The Xorg crash occurred right after a
3395 Display Manager (e.g. GDM) login. Starting with x11vnc 0.9.9 it
3396 tries to automatically avoid using XFIXES until it is sure a
3397 window manager is running. See the -reopen option for more info
3398 and how to use X11VNC_AVOID_WINDOWS=never to disable it.
3399 -alphacut n
3401 When using the XFIXES extension for the cursor shape, cursors
3403 with transparency will not usually be displayed exactly (but
3404 opaque ones will). This option sets n as a cutoff for cursors
3405 that have transparency ("alpha channel" with values ranging from
3406 0 to 255) Any cursor pixel with alpha value less than n becomes
3407 completely transparent. Otherwise the pixel is completely
3408 opaque. Default 240
3409 -alphafrac fraction
3411 With the threshold in -alphacut some cursors will become almost
3413 completely transparent because their alpha values are not high
3414 enough. For those cursors adjust the alpha threshold until
3415 fraction of the non-zero alpha channel pixels become opaque.
3416 Default 0.33
3417 -alpharemove
3419 By default, XFIXES cursors pixels with transparency have the
3421 alpha factor multiplied into the RGB color values (i.e. that
3422 corresponding to blending the cursor with a black background).
3423 Specify this option to remove the alpha factor. (useful for
3424 light colored semi-transparent cursors).
3425 -noalphablend
3427 In XFIXES mode do not send cursor alpha channel data to LibVNC‐
3429 Server. The default is to send it. The alphablend effect will
3430 only be visible in -nocursorshape mode or for clients with cur‐
3431 sorshapeupdates turned off. (However there is a hack for 32bpp
3432 with depth 24, it uses the extra 8 bits to store cursor trans‐
3433 parency for use with a hacked vncviewer that applies the trans‐
3434 parency locally. See the FAQ for more info).
3435 -nocursorshape
3437 Do not use the TightVNC CursorShapeUpdates extension even if
3439 clients support it. See -cursor above.
3440 -cursorpos, -nocursorpos
3442 Option -cursorpos enables sending the X cursor position back to
3444 all vnc clients that support the TightVNC CursorPosUpdates
3445 extension. Other clients will be able to see the pointer
3446 motions. Default: -cursorpos
3447 -xwarppointer, -noxwarppointer
3449 Move the pointer with XWarpPointer(3X) instead of the XTEST
3451 extension. Use this as a workaround if the pointer motion
3452 behaves incorrectly, e.g. on touchscreens or other non-standard
3453 setups.
3454 It is also sometimes needed on XINERAMA displays and is enabled
3456 by default if XINERAMA is found to be active. To prevent this,
3457 use -noxwarppointer.
3458 -always_inject
3460 Even if there is no displacement (dx = dy = 0) for a VNC mouse
3462 event force the pointer to the indicated x,y position anyway.
3463 Recent (2009) gui toolkits (gnome) have problems with x11vnc's
3464 original mouse input injection method. So x11vnc's mouse input
3465 injection method has been modified. To regain the OLD behavior
3466 use this option: -always_inject. Then x11vnc will always force
3467 positioning the mouse to the x,y position even if that position
3468 has not changed since the previous VNC input event.
3469 The first place this problem was noticed was in gnome terminal:
3471 if you pressed and released mouse button 3, a menu was posted
3472 and then its first element 'New Terminal Window' was activated.
3473 This was because x11vnc injected the mouse position twice: once
3474 on ButtonPress and again on ButtonRelease. The toolkit inter‐
3475 preted the 2nd one as mouse motion even though the mouse hadn't
3476 moved. So now by default x11vnc tries to avoid injecting the
3477 2nd one.
3478 Note that with the new default x11vnc will be oblivious to
3480 applications moving the pointer (warping) or the user at the
3481 physical display moving it. So it might, e.g., inject ButtonRe‐
3482 lease at the wrong position. If this (or similar scenarios)
3483 causes problems in your environment, specify -always_inject for
3484 the old method.
3485 -buttonmap string
3487 String to remap mouse buttons. Format: IJK-LMN, this maps but‐
3489 tons I -> L, etc., e.g. -buttonmap 13-31
3490 Button presses can also be mapped to keystrokes: replace a but‐
3492 ton digit on the right of the dash with :<sym>: or
3493 :<sym1>+<sym2>: etc. for multiple keys. For example, if the
3494 viewing machine has a mouse-wheel (buttons 4 5) but the x11vnc
3495 side does not, these will do scrolls:
3496 -buttonmap 12345-123:Prior::Next:
3498 -buttonmap 12345-123:Up+Up+Up::Down+Down+Down:
3500 See <X11/keysymdef.h> header file for a list of Keysyms, or use
3502 the xev(1) program. Note: mapping of button clicks to Keysyms
3503 may not work if -modtweak or -xkb is needed for the Keysym.
3504 If you include a modifier like "Shift_L" the modifier's up/down
3506 state is toggled, e.g. to send "The" use :Shift_L+t+Shift_L+h+e:
3507 (the 1st one is shift down and the 2nd one is shift up). (note:
3508 the initial state of the modifier is ignored and not reset) To
3509 include button events use "Button1", ... etc.
3510 -buttonmap currently does not work on MacOSX console or in
3512 -rawfb mode.
3513 Workaround: use -buttonmap IJ...-LM...=n to limit the number of
3515 mouse buttons to n, e.g. 123-123=3. This will prevent x11vnc
3516 from crashing if the X server reports there are 5 buttons (4/5
3517 scroll wheel), but there are only really 3.
3518 -nodragging
3520 Do not update the display during mouse dragging events (mouse
3522 button held down). Greatly improves response on slow setups,
3523 but you lose all visual feedback for drags, text selection, and
3524 some menu traversals. It overrides any -pointer_mode setting.
3525 -ncache n
3527 Client-side caching scheme. Framebuffer memory n (an integer)
3529 times that of the full display is allocated below the actual
3530 framebuffer to cache screen contents for rapid retrieval. So a
3531 W x H frambuffer is expanded to a W x (n+1)*H one. Use 0 to
3532 disable.
3533 The n is actually optional, the default is 10.
3535 For this and the other -ncache* options below you can abbreviate
3537 "-ncache" with "-nc". Also, "-nonc" is the same as "-ncache 0"
3538 This is an experimental option, currently implemented in an awk‐
3540 ward way in that in the VNC Viewer you can see the pixel cache
3541 contents if you scroll down, etc. So you will have to set
3542 things up so you can't see that region. If this method is suc‐
3543 cessful, the changes required for clients to do this less awk‐
3544 wardly will be investigated.
3545 The SSVNC viewer does a good job at automatically hiding the
3547 pixel cache region. Or use SSVNC's -ycrop option to explicitly
3548 hide the region.
3549 Note that this mode consumes a huge amount of memory, both on
3551 the x11vnc server side and on the VNC Viewer side. If n=2 then
3552 the amount of RAM used is roughly tripled for both x11vnc and
3553 the VNC Viewer. As a rule of thumb, note that 1280x1024 at
3554 depth 24 is about 5MB of pixel data.
3555 For reasonable response when cycling through 4 to 6 large (e.g.
3557 web browser) windows a value n of 6 to 12 is recommended.
3558 (that's right: ~10X more memory...)
3559 Because of the way window backingstore and saveunders are imple‐
3561 mented, n must be even. It will be incremented by 1 if it is
3562 not.
3563 This mode also works for native MacOS X, but may not be as
3565 effective as the X version. This is due to a number of things,
3566 one is the drop-shadow compositing that leaves extra areas that
3567 need to be repaired (see -ncache_pad). Another is the window
3568 iconification animations need to be avoided (see -macicontime).
3569 It appears the that the 'Scale' animation mode gives better
3570 results than the 'Genie' one. Also, window event detection not
3571 as accurate as the X version.
3572 -ncache_cr
3574 In -ncache mode, try to do copyrect opaque window moves/drags
3576 instead of wireframes (this can induce painting errors). The
3577 wireframe will still be used when moving a window whose save-
3578 unders has not yet been set or has been invalidated.
3579 Some VNC Viewers provide better response than others with this
3581 option. On Unix, realvnc viewer gives smoother drags than
3582 tightvnc viewer. Response may also be choppy if the server side
3583 machine is too slow.
3584 Sometimes on very slow modem connections, this actually gives an
3586 improvement because no pixel data at all (not even the box ani‐
3587 mation) is sent during the drag.
3588 -ncache_no_moveraise
3590 In -ncache mode, do not assume that moving a window will cause
3592 the window manager to raise it to the top of the stack. The
3593 default is to assume it does, and so at the beginning of any
3594 wireframe, etc, window moves the window will be pushed to top in
3595 the VNC viewer.
3596 -ncache_no_dtchange
3598 In -ncache mode, do not try to guess when the desktop (viewport)
3600 changes to another one (i.e. another workarea). The default is
3601 to try to guess and when detected try to make the transistion
3602 more smoothly.
3603 -ncache_no_rootpixmap
3605 In -ncache mode, do not try to snapshot the desktop background
3607 to use in guessing or reconstructing window save-unders.
3608 -ncache_keep_anims
3610 In -ncache mode, do not try to disable window manager animations
3612 and other effects (that usually degrade ncache performance or
3613 cause painting errors). The default is to try to disable them
3614 on KDE (but not GNOME) when VNC clients are connected.
3615 For other window managers or desktops that provide animations,
3617 effects, compositing, translucency, etc. that interfere with the
3618 -ncache method you will have to disable them manually.
3619 -ncache_old_wm
3621 In -ncache mode, enable some heuristics for old style window
3623 managers such as fvwm and twm.
3624 -ncache_pad n
3626 In -ncache mode, pad each window with n pixels for the caching
3628 rectangles. This can be used to try to improve the situation
3629 with dropshadows or other compositing (e.g. MacOS X window man‐
3630 ager), although it could make things worse. The default is 0 on
3631 Unix and 24 on MacOS X.
3632 -debug_ncache
3634 Turn on debugging and profiling output under -ncache.
3636 -wireframe [str], -nowireframe
3638 Try to detect window moves or resizes when a mouse button is
3640 held down and show a wireframe instead of the full opaque win‐
3641 dow. This is based completely on heuristics and may not always
3642 work: it depends on your window manager and even how you move
3643 things around. See -pointer_mode below for discussion of the
3644 "bogging down" problem this tries to avoid. Default: -wireframe
3645 Shorter aliases: -wf [str] and -nowf
3647 The value "str" is optional and, of course, is packed with many
3649 tunable parameters for this scheme:
3650 Format: shade,linewidth,percent,T+B+L+R,mod,t1+t2+t3+t4 Default:
3652 0xff,2,0,32+8+8+8,all,0.15+0.30+5.0+0.125
3653 If you leave nothing between commas: ",," the default value is
3655 used. If you don't specify enough commas, the trailing parame‐
3656 ters are set to their defaults.
3657 "shade" indicate the "color" for the wireframe, usually a
3659 greyscale: 0-255, however for 16 and 32bpp you can specify an
3660 rgb.txt X color (e.g. "dodgerblue") or a value > 255 is treated
3661 as RGB (e.g. red is 0xff0000). "linewidth" sets the width of
3662 the wireframe in pixels. "percent" indicates to not apply the
3663 wireframe scheme to windows with area less than this percent of
3664 the full screen.
3665 "T+B+L+R" indicates four integers for how close in pixels the
3667 pointer has to be from the Top, Bottom, Left, or Right edges of
3668 the window to consider wireframing. This is a speedup to
3669 quickly exclude a window from being wireframed: set them all to
3670 zero to not try the speedup (scrolling and selecting text will
3671 likely be slower).
3672 "mod" specifies if a button down event in the interior of the
3674 window with a modifier key (Alt, Shift, etc.) down should indi‐
3675 cate a wireframe opportunity. It can be "0" or "none" to skip
3676 it, "1" or "all" to apply it to any modifier, or "Shift", "Alt",
3677 "Control", "Meta", "Super", or "Hyper" to only apply for that
3678 type of modifier key.
3679 "t1+t2+t3+t4" specify four floating point times in seconds: t1
3681 is how long to wait for the pointer to move, t2 is how long to
3682 wait for the window to start moving or being resized (for some
3683 window managers this can be rather long), t3 is how long to keep
3684 a wireframe moving before repainting the window. t4 is the mini‐
3685 mum time between sending wireframe "animations". If a slow link
3686 is detected, these values may be automatically changed to some‐
3687 thing better for a slow link.
3688 -nowireframelocal
3690 By default, mouse motion and button presses of a user sitting at
3692 the LOCAL display are monitored for wireframing opportunities
3693 (so that the changes will be sent efficiently to the VNC
3694 clients). Use this option to disable this behavior.
3695 -wirecopyrect mode, -nowirecopyrect
3697 Since the -wireframe mechanism evidently tracks moving windows
3699 accurately, a speedup can be obtained by telling the VNC viewers
3700 to locally copy the translated window region. This is the VNC
3701 CopyRect encoding: the framebuffer update doesn't need to send
3702 the actual new image data.
3703 Shorter aliases: -wcr [mode] and -nowcr
3705 "mode" can be "never" (same as -nowirecopyrect) to never try the
3707 copyrect, "top" means only do it if the window was not covered
3708 by any other windows, and "always" means to translate the
3709 orginally unobscured region (this may look odd as the remaining
3710 pieces come in, but helps on a slow link). Default: "always"
3711 Note: there can be painting errors or slow response when using
3713 -scale so you may want to disable CopyRect in this case "-wire‐
3714 copyrect never" on the command line or by remote-control. Or
3715 you can also use the "-scale xxx:nocr" scale option.
3716 -debug_wireframe
3718 Turn on debugging info printout for the wireframe heuristics.
3720 "-dwf" is an alias. Specify multiple times for more output.
3721 -scrollcopyrect mode, -noscrollcopyrect
3723 Like -wirecopyrect, but use heuristics to try to guess if a win‐
3725 dow has scrolled its contents (either vertically or horizon‐
3726 tally). This requires the RECORD X extension to "snoop" on X
3727 applications (currently for certain XCopyArea and XConfigureWin‐
3728 dow X protocol requests). Examples: Hitting <Return> in a ter‐
3729 minal window when the cursor was at the bottom, the text scrolls
3730 up one line. Hitting <Down> arrow in a web browser window, the
3731 web page scrolls up a small amount. Or scrolling with a scroll‐
3732 bar or mouse wheel.
3733 Shorter aliases: -scr [mode] and -noscr
3735 This scheme will not always detect scrolls, but when it does
3737 there is a nice speedup from using the VNC CopyRect encoding
3738 (see -wirecopyrect). The speedup is both in reduced network
3739 traffic and reduced X framebuffer polling/copying. On the other
3740 hand, it may induce undesired transients (e.g. a terminal cursor
3741 being scrolled up when it should not be) or other painting
3742 errors (window tearing, bunching-up, etc). These are automati‐
3743 cally repaired in a short period of time. If this is unaccept‐
3744 able disable the feature with -noscrollcopyrect.
3745 Screen clearing kludges: for testing at least, there are some
3747 "magic key sequences" (must be done in less than 1 second) to
3748 aid repairing painting errors that may be seen when using this
3749 mode:
3750 3 Alt_L's in a row: resend whole screen, 4 Alt_L's in a row:
3752 reread and resend whole screen, 3 Super_L's in a row: mark whole
3753 screen for polling, 4 Super_L's in a row: reset RECORD context,
3754 5 Super_L's in a row: try to push a black screen
3755 note: Alt_L is the Left "Alt" key (a single key) Super_L is the
3757 Left "Super" key (Windows flag). Both of these are modifier
3758 keys, and so should not generate characters when pressed by
3759 themselves. Also, your VNC viewer may have its own refresh hot-
3760 key or button.
3761 "mode" can be "never" (same as -noscrollcopyrect) to never try
3763 the copyrect, "keys" means to try it in response to keystrokes
3764 only, "mouse" means to try it in response to mouse events only,
3765 "always" means to do both. Default: "always"
3766 Note: there can be painting errors or slow response when using
3768 -scale so you may want to disable CopyRect in this case
3769 "-scrollcopyrect never" on the command line or by remote-con‐
3770 trol. Or you can also use the "-scale xxx:nocr" scale option.
3771 -scr_area n
3773 Set the minimum area in pixels for a rectangle to be considered
3775 for the -scrollcopyrect detection scheme. This is to avoid
3776 wasting the effort on small rectangles that would be quickly
3777 updated the normal way. E.g. suppose an app updated the posi‐
3778 tion of its skinny scrollbar first and then shifted the large
3779 panel it controlled. We want to be sure to skip the small
3780 scrollbar and get the large panel. Default: 60000
3781 -scr_skip list
3783 Skip scroll detection for applications matching the comma sepa‐
3785 rated list of strings in list. Some applications implement
3786 their scrolling in strange ways where the XCopyArea, etc, also
3787 applies to invisible portions of the window: if we CopyRect
3788 those areas it looks awful during the scroll and there may be
3789 painting errors left after the scroll. Soffice.bin is the worst
3790 known offender.
3791 Use "##" to denote the start of the application class (e.g.
3793 "##XTerm") and "++" to denote the start of the application
3794 instance name (e.g. "++xterm"). The string your list is matched
3795 against is of the form "^^WM_NAME##Class++Instance<same-for-any-
3796 subwindows>" The "xlsclients -la" command will provide this
3797 info.
3798 If a pattern is prefixed with "KEY:" it only applies to Key‐
3800 stroke generated scrolls (e.g. Up arrow). If it is prefixed
3801 with "MOUSE:" it only applies to Mouse induced scrolls (e.g.
3802 dragging on a scrollbar). Default: ##Soffice.bin,##StarOf‐
3803 fice,##OpenOffice
3804 -scr_inc list
3806 Opposite of -scr_skip: this list is consulted first and if there
3808 is a match the window will be monitored via RECORD for scrolls
3809 irrespective of -scr_skip. Use -scr_skip '*' to skip anything
3810 that does not match your -scr_inc. Use -scr_inc '*' to include
3811 everything.
3812 -scr_keys list
3814 For keystroke scroll detection, only apply the RECORD heuristics
3816 to the comma separated list of keysyms in list. You may find
3817 the RECORD overhead for every one of your keystrokes disrupts
3818 typing too much, but you don't want to turn it off completely
3819 with "-scr mouse" and -scr_parms does not work or is too confus‐
3820 ing.
3821 The listed keysyms can be numeric or the keysym names in the
3823 <X11/keysymdef.h> header file or from the xev(1) program. Exam‐
3824 ple: "-scr_keys Up,Down,Return". One probably wants to have
3825 application specific lists (e.g. for terminals, etc) but that is
3826 too icky to think about for now...
3827 If list begins with the "-" character the list is taken as an
3829 exclude list: all keysyms except those list will be considered.
3830 The special string "builtin" expands to an internal list of
3831 keysyms that are likely to cause scrolls. BTW, by default modi‐
3832 fier keys, Shift_L, Control_R, etc, are skipped since they
3833 almost never induce scrolling by themselves.
3834 -scr_term list
3836 Yet another cosmetic kludge. Apply shell/terminal heuristics to
3838 applications matching comma separated list (same as for
3839 -scr_skip/-scr_inc). For example an annoying transient under
3840 scroll detection is if you hit Enter in a terminal shell with
3841 full text window, the solid text cursor block will be scrolled
3842 up. So for a short time there are two (or more) block cursors
3843 on the screen. There are similar scenarios, (e.g. an output
3844 line is duplicated).
3845 These transients are induced by the approximation of scroll
3847 detection (e.g. it detects the scroll, but not the fact that the
3848 block cursor was cleared just before the scroll). In nearly all
3849 cases these transient errors are repaired when the true X frame‐
3850 buffer is consulted by the normal polling. But they are dis‐
3851 tracting, so what this option provides is extra "padding" near
3852 the bottom of the terminal window: a few extra lines near the
3853 bottom will not be scrolled, but rather updated from the actual
3854 X framebuffer. This usually reduces the annoying artifacts.
3855 Use "none" to disable. Default: "term"
3856 -scr_keyrepeat lo-hi
3858 If a key is held down (or otherwise repeats rapidly) and this
3860 induces a rapid sequence of scrolls (e.g. holding down an Arrow
3861 key) the "scrollcopyrect" detection and overhead may not be able
3862 to keep up. A time per single scroll estimate is performed and
3863 if that estimate predicts a sustainable scrollrate of keys per
3864 second between "lo" and "hi" then repeated keys will be DIS‐
3865 CARDED to maintain the scrollrate. For example your key autore‐
3866 peat may be 25 keys/sec, but for a large window or slow link
3867 only 8 scrolls per second can be sustained, then roughly 2 out
3868 of every 3 repeated keys will be discarded during this period.
3869 Default: "4-20"
3870 -scr_parms string
3872 Set various parameters for the scrollcopyrect mode. The format
3874 is similar to that for -wireframe and packed with lots of param‐
3875 eters:
3876 Format: T+B+L+R,t1+t2+t3,s1+s2+s3+s4+s5 Default:
3878 0+64+32+32,0.02+0.10+0.9,0.03+0.06+0.5+0.1+5.0
3879 If you leave nothing between commas: ",," the default value is
3881 used. If you don't specify enough commas, the trailing parame‐
3882 ters are set to their defaults.
3883 "T+B+L+R" indicates four integers for how close in pixels the
3885 pointer has to be from the Top, Bottom, Left, or Right edges of
3886 the window to consider scrollcopyrect. If -wireframe overlaps
3887 it takes precedence. This is a speedup to quickly exclude a
3888 window from being watched for scrollcopyrect: set them all to
3889 zero to not try the speedup (things like selecting text will
3890 likely be slower).
3891 "t1+t2+t3" specify three floating point times in seconds that
3893 apply to scrollcopyrect detection with *Keystroke* input: t1 is
3894 how long to wait after a key is pressed for the first scroll, t2
3895 is how long to keep looking after a Keystroke scroll for more
3896 scrolls. t3 is how frequently to try to update surrounding
3897 scrollbars outside of the scrolling area (0.0 to disable)
3898 "s1+s2+s3+s4+s5" specify five floating point times in seconds
3900 that apply to scrollcopyrect detection with *Mouse* input: s1 is
3901 how long to wait after a mouse button is pressed for the first
3902 scroll, s2 is how long to keep waiting for additional scrolls
3903 after the first Mouse scroll was detected. s3 is how frequently
3904 to try to update surrounding scrollbars outside of the scrolling
3905 area (0.0 to disable). s4 is how long to buffer pointer motion
3906 (to try to get fewer, bigger mouse scrolls). s5 is the maximum
3907 time to spend just updating the scroll window without updating
3908 the rest of the screen.
3909 -fixscreen string
3911 Periodically "repair" the screen based on settings in string.
3913 Hopefully you won't need this option, it is intended for cases
3914 when the -scrollcopyrect or -wirecopyrect features leave too
3915 many painting errors, but it can be used for any scenario. This
3916 option periodically performs costly operations and so interac‐
3917 tive response may be reduced when it is on. You can use 3
3918 Alt_L's (the Left "Alt" key) taps in a row (as described under
3919 -scrollcopyrect) instead to manually request a screen repaint
3920 when it is needed.
3921 string is a comma separated list of one or more of the follow‐
3923 ing: "V=t", "C=t", "X=t", and "8=t". In these "t" stands for a
3924 time in seconds (it is a floating point even though one should
3925 usually use values > 2 to avoid wasting resources). V sets how
3926 frequently the entire screen should be sent to viewers (it is
3927 like the 3 Alt_L's). C sets how long to wait after a CopyRect
3928 to repaint the full screen. X sets how frequently to reread the
3929 full X11 framebuffer from the X server and push it out to con‐
3930 nected viewers. Use of X should be rare, please report a bug if
3931 you find you need it. 8= applies only for -8to24 mode: it sets
3932 how often the non-default visual regions of the screen (e.g.
3933 8bpp windows) are refreshed. Examples: -fixscreen V=10
3934 -fixscreen C=10
3935 -debug_scroll
3937 Turn on debugging info printout for the scroll heuristics.
3939 "-ds" is an alias. Specify it multiple times for more output.
3940 -noxrecord
3942 Disable any use of the RECORD extension. This is currently used
3944 by the -scrollcopyrect scheme and to monitor X server grabs.
3945 -grab_buster, -nograb_buster
3947 Some of the use of the RECORD extension can leave a tiny window
3949 for XGrabServer deadlock. This is only if the whole-server
3950 grabbing application expects mouse or keyboard input before
3951 releasing the grab. It is usually a window manager that does
3952 this. x11vnc takes care to avoid the problem, but if caught
3953 x11vnc will freeze. Without -grab_buster, the only solution is
3954 to go the physical display and give it some input to satisfy the
3955 grabbing app. Or manually kill and restart the window manager
3956 if that is feasible. With -grab_buster, x11vnc will fork a
3957 helper thread and if x11vnc appears to be stuck in a grab after
3958 a period of time (20-30 sec) then it will inject some user
3959 input: button clicks, Escape, mouse motion, etc to try to break
3960 the grab. If you experience a lot of grab deadlock, please
3961 report a bug.
3962 -debug_grabs
3964 Turn on debugging info printout with respect to XGrabServer()
3966 deadlock for -scrollcopyrect__mode_.
3967 -debug_sel
3969 Turn on debugging info printout with respect to PRIMARY, CLIP‐
3971 BOARD, and CUTBUFFER0 selections.
3972 -pointer_mode n
3974 Various pointer motion update schemes. "-pm" is an alias. The
3976 problem is pointer motion can cause rapid changes on the screen:
3977 consider the rapid changes when you drag a large window around
3978 opaquely. Neither x11vnc's screen polling and vnc compression
3979 routines nor the bandwidth to the vncviewers can keep up these
3980 rapid screen changes: everything will bog down when dragging or
3981 scrolling. So a scheme has to be used to "eat" much of that
3982 pointer input before re-polling the screen and sending out
3983 framebuffer updates. The mode number n can be 0 to 4 and selects
3984 one of the schemes desribed below.
3985 Note that the -wireframe and -scrollcopyrect__mode_s complement
3987 -pointer_mode by detecting (and improving) certain periods of
3988 "rapid screen change".
3989 n=0: does the same as -nodragging. (all screen polling is sus‐
3991 pended if a mouse button is pressed.)
3992 n=1: was the original scheme used to about Jan 2004: it basi‐
3994 cally just skips -input_skip keyboard or pointer events before
3995 repolling the screen.
3996 n=2 is an improved scheme: by watching the current rate of input
3998 events it tries to detect if it should try to "eat" additional
3999 pointer events before continuing.
4000 n=3 is basically a dynamic -nodragging mode: it detects when the
4002 mouse motion has paused and then refreshes the display.
4003 n=4 attempts to measures network rates and latency, the video
4005 card read rate, and how many tiles have been changed on the
4006 screen. From this, it aggressively tries to push screen
4007 "frames" when it decides it has enough resources to do so. NOT
4008 FINISHED.
4009 The default n is 2. Note that modes 2, 3, 4 will skip
4011 -input_skip keyboard events (but it will not count pointer
4012 events). Also note that these modes are not available in
4013 -threads mode which has its own pointer event handling mecha‐
4014 nism.
4015 To try out the different pointer modes to see which one gives
4017 the best response for your usage, it is convenient to use the
4018 remote control function, for example "x11vnc -R pm:4" or the
4019 tcl/tk gui (Tuning -> pointer_mode -> n).
4020 -input_skip n
4022 For the pointer handling when non-threaded: try to read n user
4024 input events before scanning display. n < 0 means to act as
4025 though there is always user input. Default: 10
4026 -allinput
4028 Have x11vnc read and process all available client input before
4030 proceeding.
4031 -input_eagerly
4033 Similar to -allinput but use the handleEventsEagerly mechanism
4035 built into LibVNCServer.
4036 -multiptr
4038 Enable support for per-client input devices. Each client will
4040 get its own cursor and keyboard focus.
4041 -speeds rd,bw,lat
4043 x11vnc tries to estimate some speed parameters that are used to
4045 optimize scheduling (e.g. -pointer_mode 4, -wireframe, -scroll‐
4046 copyrect) and other things. Use the -speeds option to set these
4047 manually. The triple rd,bw,lat corresponds to video h/w read
4048 rate in MB/sec, network bandwidth to clients in KB/sec, and net‐
4049 work latency to clients in milliseconds, respectively. If a
4050 value is left blank, e.g. "-speeds ,100,15", then the internal
4051 scheme is used to estimate the empty value(s).
4052 Typical PC video cards have read rates of 5-10 MB/sec. If the
4054 framebuffer is in main memory instead of video h/w (e.g. SunRay,
4055 shadowfb, dummy driver, Xvfb), the read rate may be much faster.
4056 "x11perf -getimage500" can be used to get a lower bound (remem‐
4057 ber to factor in the bytes per pixel). It is up to you to esti‐
4058 mate the network bandwith and latency to clients. For the
4059 latency the ping(1) command can be used.
4060 For convenience there are some aliases provided, e.g. "-speeds
4062 modem". The aliases are: "modem" for 6,4,200; "dsl" for
4063 6,100,50; and "lan" for 6,5000,1
4064 -wmdt string
4066 For some features, e.g. -wireframe and -scrollcopyrect, x11vnc
4068 has to work around issues for certain window managers or desk‐
4069 tops (currently kde and xfce). By default it tries to guess
4070 which one, but it can guess incorrectly. Use this option to
4071 indicate which wm/dt. string can be "gnome", "kde", "cde",
4072 "xfce", or "root" (classic X wm). Anything else is interpreted
4073 as "root".
4074 -debug_pointer
4076 Print debugging output for every pointer event.
4078 -debug_keyboard
4080 Print debugging output for every keyboard event.
4082 Same as -dp and -dk, respectively. Use multiple times for more output.
4084 -defer time
4086 Time in ms to delay sending updates to connected clients (defer‐
4088 UpdateTime) Default: 20
4089 -wait time
4091 Time in ms to pause between screen polls. Used to cut down on
4093 load. Default: 20
4094 -extra_fbur n
4096 Perform extra FrameBufferUpdateRequests checks to try to be in
4098 better sync with the client's requests. What this does is per‐
4099 form extra polls of the client socket at critical times (before
4100 '-defer' and '-wait' calls.) The default is n=1. Set to a
4101 larger number to insert more checks or set to n=0 to disable. A
4102 downside of these extra calls is that more mouse input may be
4103 processed than desired.
4104 -wait_ui factor
4106 Factor by which to cut the -wait time if there has been recent
4108 user input (pointer or keyboard). Improves response, but
4109 increases the load whenever you are moving the mouse or typing.
4110 Default: 2.00
4111 -setdefer n
4113 When the -wait_ui mechanism cuts down the wait time ms, set the
4115 defer time to the same ms value. n=1 to enable, 0 to disable,
4116 and -1 to set defer to 0 (no delay). Similarly, 2 and -2 indi‐
4117 cate 'urgent_update' mode should be used to push the updates
4118 even sooner. Default: 1
4119 -nowait_bog
4121 Do not detect if the screen polling is "bogging down" and sleep
4123 more. Some activities with no user input can slow things down a
4124 lot: consider a large terminal window with a long build running
4125 in it continuously streaming text output. By default x11vnc
4126 will try to detect this (3 screen polls in a row each longer
4127 than 0.25 sec with no user input), and sleep up to 1.5 secs to
4128 let things "catch up". Use this option to disable that detec‐
4129 tion.
4130 -slow_fb time
4132 Floating point time in seconds to delay all screen polling. For
4134 special purpose usage where a low frame rate is acceptable and
4135 desirable, but you want the user input processed at the normal
4136 rate so you cannot use -wait.
4137 -xrefresh time
4139 Floating point time in seconds to indicate how often to do the
4141 equivalent of xrefresh(1) to force all windows (in the viewable
4142 area if -id, -sid, or -clip is used) to repaint themselves. Use
4143 this only if applications misbehave by not repainting themselves
4144 properly. See also -noxdamage.
4145 -nap, -nonap
4147 Monitor activity and if it is low take longer naps between
4149 screen polls to really cut down load when idle. Default: take
4150 naps
4151 -sb time
4153 Time in seconds after NO activity (e.g. screen blank) to really
4155 throttle down the screen polls (i.e. sleep for about 1.5 secs).
4156 Use 0 to disable. Default: 60 Set the env. var. X11VNC_SB_FAC‐
4157 TOR to scale it.
4158 -readtimeout n
4160 Set LibVNCServer rfbMaxClientWait to n seconds. On slow links
4162 that take a long time to paint the first screen LibVNCServer may
4163 hit the timeout and drop the connection. Default: 20 seconds.
4164 -ping n
4166 Send a 1x1 framebuffer update to all clients every n seconds
4168 (e.g. to try to keep a network connection alive)
4169 -nofbpm, -fbpm
4171 If the system supports the FBPM (Frame Buffer Power Management)
4173 extension (i.e. some Sun systems), then prevent the video h/w
4174 from going into a reduced power state when VNC clients are con‐
4175 nected.
4176 FBPM capable video h/w save energy when the workstation is idle
4178 by going into low power states (similar to DPMS for monitors).
4179 This interferes with x11vnc's polling of the framebuffer data.
4180 "-nofbpm" means prevent FBPM low power states whenever VNC
4182 clients are connected, while "-fbpm" means to not monitor the
4183 FBPM state at all. See the xset(1) manpage for details. -nof‐
4184 bpm is basically the same as running "xset fbpm force on" peri‐
4185 odically. Default: -fbpm
4186 -nodpms, -dpms
4188 If the system supports the DPMS (Display Power Management Sig‐
4190 naling) extension, then prevent the monitor from going into a
4191 reduced power state when VNC clients are connected.
4192 DPMS reduced power monitor states are a good thing and you nor‐
4194 mally want the power down to take place (usually x11vnc has no
4195 problem exporting the display in this state). You probably only
4196 want to use "-nodpms" to work around problems with Screen Savers
4197 kicking on in DPMS low power states. There is known problem
4198 with kdesktop_lock on KDE where the screen saver keeps kicking
4199 in every time user input stops for a second or two. Specifying
4200 "-nodpms" works around it.
4201 "-nodpms" means prevent DPMS low power states whenever VNC
4203 clients are connected, while "-dpms" means to not monitor the
4204 DPMS state at all. See the xset(1) manpage for details.
4205 -nodpms is basically the same as running "xset dpms force on"
4206 periodically. Default: -dpms
4207 -forcedpms
4209 If the system supports the DPMS (Display Power Management Sig‐
4211 naling) extension, then try to keep the monitor in a powered off
4212 state. This is to prevent nosey people at the physical display
4213 from viewing what is on the screen. Be sure to lock the screen
4214 before disconnecting.
4215 This method is far from bullet proof, e.g. suppose someone
4217 attaches a non-DPMS monitor, or loads the machine so that there
4218 is a gap of time before x11vnc restores the powered off state?
4219 On many machines if he floods it with keyboard and mouse input
4220 he can see flashes of what is on the screen before the DPMS off
4221 state is reestablished. For this to work securely there would
4222 need to be support in the X server to do this exactly rather
4223 than approximately with DPMS.
4224 -clientdpms
4226 As -forcedpms but only when VNC clients are connected.
4228 -noserverdpms
4230 The UltraVNC ServerInput extension is supported. This allows
4232 the VNC viewer to click a button that will cause the server
4233 (x11vnc) to try to disable keyboard and mouse input at the phys‐
4234 ical display and put the monitor in dpms powered off state. Use
4235 this option to skip powering off the monitor.
4236 -noultraext
4238 Disable the following UltraVNC extensions: SingleWindow and
4240 ServerInput. The others managed by LibVNCServer (textchat, 1/n
4241 scaling, rfbEncodingUltra) are not.
4242 -chatwindow
4244 Place a local UltraVNC chat window on the X11 display that
4246 x11vnc is polling. That way the person on the VNC viewer-side
4247 can chat with the person at the physical X11 console. (e.g.
4248 helpdesk w/o telephone)
4249 For this to work the SSVNC package (version 1.0.21 or later)
4251 MUST BE installed on the system where x11vnc runs and the
4252 'ssvnc' command must be available in $PATH. The ssvncviewer is
4253 used as a chat window helper. See http://www.karl‐
4254 runge.com/x11vnc/ssvnc.html
4255 This option implies '-rfbversion 3.6' so as to trick UltraVNC
4257 viewers, otherwise they assume chat is not available. To spec‐
4258 ify a different rfbversion, place it after the -chatwindow
4259 option on the cmdline.
4260 See also the remote control 'chaton' and 'chatoff' actions.
4262 These can also be set from the tkx11vnc GUI.
4263 -noxdamage
4265 Do not use the X DAMAGE extension to detect framebuffer changes
4267 even if it is available. Use -xdamage if your default is to
4268 have it off.
4269 x11vnc's use of the DAMAGE extension: 1) significantly reduces
4271 the load when the screen is not changing much, and 2) detects
4272 changed areas (small ones by default) more quickly.
4273 Currently the DAMAGE extension is overly conservative and often
4275 reports large areas (e.g. a whole terminal or browser window) as
4276 damaged even though the actual changed region is much smaller
4277 (sometimes just a few pixels). So heuristics were introduced to
4278 skip large areas and use the damage rectangles only as "hints"
4279 for the traditional scanline polling. The following tuning
4280 parameters are introduced to adjust this behavior:
4281 -xd_area A
4283 Set the largest DAMAGE rectangle area A (in pixels: width *
4285 height) to trust as truly damaged: the rectangle will be copied
4286 from the framebuffer (slow) no matter what. Set to zero to
4287 trust *all* rectangles. Default: 20000
4288 -xd_mem f
4290 Set how long DAMAGE rectangles should be "remembered", f is a
4292 floating point number and is in units of the scanline repeat
4293 cycle time (32 iterations). The default (1.0) should give no
4294 painting problems. Increase it if there are problems or decrease
4295 it to live on the edge (perhaps useful on a slow machine).
4296 -sigpipe string
4298 Broken pipe (SIGPIPE) handling. string can be "ignore" or
4300 "exit". For "ignore" LibVNCServer will handle the abrupt loss
4301 of a client and continue, for "exit" x11vnc will cleanup and
4302 exit at the 1st broken connection.
4303 This option is not really needed since LibVNCServer is doing the
4305 correct thing now for quite some time. However, for convenience
4306 you can use it to ignore other signals, e.g. "-sigpipe
4307 ignore:HUP,INT,TERM" in case that would be useful for some sort
4308 of application. You can also put "exit:.." in the list to have
4309 x11vnc cleanup on the listed signals. "-sig" is an alias for
4310 this option if you don't like the 'pipe'. Example: -sig
4311 ignore:INT,TERM,exit:USR1
4312 -threads, -nothreads
4314 Whether or not to use the threaded LibVNCServer algorithm
4316 [rfbRunEventLoop] if libpthread is available. In this mode new
4317 threads (one for input and one for output) are created to handle
4318 each new client. Default: -nothreads.
4319 Thread stability is much improved in version 0.9.8.
4321 Multiple clients in threaded mode should be stable for the ZRLE
4323 encoding on all platforms. The Tight and Zlib encodings are
4324 currently only stable on Linux for multiple clients. Compile
4325 with -DTLS=__thread if your OS and compiler and linker support
4326 it.
4327 For resizes (randr, etc.) set this env. var. to the number of
4329 milliseconds to sleep: X11VNC_THREADS_NEW_FB_SLEEP at various
4330 places in the do_new_fb() action. This is to let various activ‐
4331 ities settle. Default is about 500ms.
4332 Multiple clients in threaded mode could yield better performance
4334 for 'class-room' broadcasting usage; also in -appshare broadcast
4335 mode. See also the -reflect option.
4336 -fs f
4338 If the fraction of changed tiles in a poll is greater than f,
4340 the whole screen is updated. Default: 0.75
4341 -gaps n
4343 Heuristic to fill in gaps in rows or cols of n or less tiles.
4345 Used to improve text paging. Default: 4
4346 -grow n
4348 Heuristic to grow islands of changed tiles n or wider by check‐
4350 ing the tile near the boundary. Default: 3
4351 -fuzz n
4353 Tolerance in pixels to mark a tiles edges as changed. Default:
4355 2
4356 -debug_tiles
4358 Print debugging output for tiles, fb updates, etc.
4360 -snapfb
4362 Instead of polling the X display framebuffer (fb) for changes,
4364 periodically copy all of X display fb into main memory and exam‐
4365 ine that copy for changes. (This setting also applies for non-X
4366 -rawfb modes). Under some circumstances this will improve
4367 interactive response, or at least make things look smoother, but
4368 in others (most!) it will make the response worse. If the video
4369 h/w fb is such that reading small tiles is very slow this mode
4370 could help. To keep the "framerate" up the screen size x bpp
4371 cannot be too large. Note that this mode is very wasteful of
4372 memory I/O resources (it makes full screen copies even if noth‐
4373 ing changes). It may be of use in video capture-like applica‐
4374 tions, webcams, or where window tearing is a problem.
4375 -rawfb string
4377 Instead of polling X, poll the memory object specified in
4379 string.
4380 For file polling, to memory map mmap(2) a file use:
4382 "map:/path/to/a/file@WxHxB", with framebuffer Width, Height, and
4383 Bits per pixel. "mmap:..." is the same.
4384 If there is trouble with mmap, use "file:/..." for slower
4386 lseek(2) based reading.
4387 Use "snap:..." to imply -snapfb mode and the "file:" access
4389 (this is for unseekable devices that only provide the fb all at
4390 once, e.g. a video camera provides the whole frame).
4391 For shared memory segments string is of the form: "shm:N@WxHxB"
4393 which specifies a shmid N and with WxHxB as above. See shmat(1)
4394 and ipcs(1)
4395 If you do not supply a type "map" is assumed if the file exists
4397 (see the next paragraphs for some exceptions to this.)
4398 If string is "setup:cmd", then the command "cmd" is run and the
4400 first line from it is read and used as string. This allows ini‐
4401 tializing the device, determining WxHxB, etc. These are often
4402 done as root so take care.
4403 If the string begins with "video", see the VIDEO4LINUX discus‐
4405 sion below where the device may be queried for (and possibly
4406 set) the framebuffer parameters.
4407 If the string begins with "console", "/dev/fb", "fb", or "vt",
4409 see the LINUX CONSOLE discussion below where the framebuffer
4410 device is opened and keystrokes (and possibly mouse events) are
4411 inserted into the console.
4412 If the string begins with "vnc", see the VNC HOST discussion
4414 below where the framebuffer is taken as that of another remote
4415 VNC server.
4416 Optional suffixes are ":R/G/B" and "+O" to specify red, green,
4418 and blue masks (in hex) and an offset into the memory object.
4419 If the masks are not provided x11vnc guesses them based on the
4420 bpp (if the colors look wrong, you need to provide the masks.)
4421 Another optional suffix is the Bytes Per Line which in some
4423 cases is not WxB/8. Specify it as WxHxB-BPL e.g.
4424 800x600x16-2048. This could be a normal width 1024 at 16bpp fb,
4425 but only width 800 shows up.
4426 So the full format is: mode:file@WxHxB:R/G/B+O-BPL
4428 Examples:
4430 -rawfb shm:210337933@800x600x32:ff/ff00/ff0000
4432 -rawfb map:/dev/fb0@1024x768x32
4434 -rawfb map:/tmp/Xvfb_screen0@640x480x8+3232
4436 -rawfb file:/tmp/my.pnm@250x200x24+37
4438 -rawfb file:/dev/urandom@128x128x8 -rawfb
4440 snap:/dev/video0@320x240x24 -24to32 -rawfb video0 -rawfb video
4441 -pipeinput VID -rawfb console -rawfb vt2 -rawfb vnc:somehost:0
4442 (see ipcs(1) and fbset(1) for the first two examples)
4444 In general all user input is discarded by default (see the
4446 -pipeinput option for how to use a helper program to insert).
4447 Most of the X11 (screen, keyboard, mouse) options do not make
4448 sense and many will cause this mode to crash, so please think
4449 twice before setting or changing them in a running x11vnc.
4450 If you DO NOT want x11vnc to close the X DISPLAY in rawfb mode,
4452 prepend a "+" e.g. +file:/dev/fb0... Keeping the display open
4453 enables the default remote-control channel, which could be use‐
4454 ful. Alternatively, if you specify -noviewonly, then the mouse
4455 and keyboard input are STILL sent to the X display, this usage
4456 should be very rare, i.e. doing something strange with /dev/fb0.
4457 If the device is not "seekable" (e.g. webcam) try reading it all
4459 at once in full snaps via the "snap:" mode (note: this is a
4460 resource hog). If you are using file: or map: AND the device
4461 needs to be reopened for *every* snapfb snapshot, set the envi‐
4462 ronment variable: SNAPFB_RAWFB_RESET=1 as well.
4463 If you want x11vnc to dynamically transform a 24bpp rawfb to
4465 32bpp (note that this will be slower) also supply the -24to32
4466 option. This would be useful for, say, a video camera that
4467 delivers the pixel data as 24bpp packed RGB. This is the
4468 default under "video" mode if the bpp is 24.
4469 Normally the bits per pixel, B, is 8, 16, or 32 (or rarely 24),
4471 however there is also some support for B < 8 (e.g. old graphics
4472 displays 4 bpp or 1 bpp). In this case you certainly must sup‐
4473 ply the masks as well: WxHxB:R/G/B. The pixels will be padded
4474 out to 8 bpp using depth 8 truecolor. The scheme currently does
4475 not work with snap fb (ask if interested.) B=1 monochrome exam‐
4476 ple: file:/dev/urandom@128x128x1:1/1/1 Some other like this are
4477 128x128x2:3/3/3 128x128x4:7/7/7
4478 For B < 8 framebuffers you can also set the env. var RAWFB_CGA=1
4480 to try a CGA mapping for B=4 (e.g. linux vga16fb driver.) Note
4481 with low bpp and/or resolution VGA and VGA16 modes on the Linux
4482 console one's attempt to export them via x11vnc can often be
4483 thwarted due to special color palettes, pixel packings, and even
4484 video painting buffering. OTOH, often experimenting with the
4485 RGB masks can yield something recognizable.
4486 VIDEO4LINUX: on Linux some attempt is made to handle video
4488 devices (webcams or TV tuners) automatically. The idea is the
4489 WxHxB will be extracted from the device itself. So if you do
4490 not supply "@WxHxB... parameters x11vnc will try to determine
4491 them. It first tries the v4l API if that support has been com‐
4492 piled in. Otherwise it will run the v4l- info(1) external pro‐
4493 gram if it is available.
4494 The simplest examples are "-rawfb video" and "-rawfb video1"
4496 which imply the device file /dev/video and /dev/video1, respec‐
4497 tively. You can also supply the /dev if you like, e.g. "-rawfb
4498 /dev/video0"
4499 Since the video capture device framebuffer usually changes con‐
4501 tinuously (e.g. brightness fluctuations), you may want to use
4502 the -wait, -slow_fb, or -defer options to lower the "framerate"
4503 to cut down on network VNC traffic.
4504 A more sophisticated video device scheme allows initializing the
4506 device's settings using:
4507 -rawfb video:<settings>
4509 The prefix could also be, as above, e.g. "video1:" to specify
4511 the device file. The v4l API must be available for this to
4512 work. Otherwise, you will need to try to initialize the device
4513 with an external program, e.g. xawtv, spcaview, and hope they
4514 persist when x11vnc re-opens the device.
4515 <settings> is a comma separated list of key=value pairs. The
4517 device's brightness, color, contrast, and hue can be set to per‐
4518 centages, e.g. br=80,co=50,cn=44,hu=60.
4519 The device filename can be set too if needed (if it does not
4521 start with "video"), e.g. fn=/dev/qcam.
4522 The width, height and bpp of the framebuffer can be set via,
4524 e.g., w=160,h=120,bpp=16.
4525 Related to the bpp above, the pixel format can be set via the
4527 fmt=XXX, where XXX can be one of: GREY, HI240, RGB555, RGB565,
4528 RGB24, and RGB32 (with bpp 8, 8, 16, 16, 24, and 32 respec‐
4529 tively). See http://www.linuxtv.org for more info (V4L api).
4530 For TV/rf tuner cards one can set the tuning mode via tun=XXX
4532 where XXX can be one of PAL, NTSC, SECAM, or AUTO.
4533 One can switch the input channel by the inp=XXX setting, where
4535 XXX is the name of the input channel (Television, Composite1, S-
4536 Video, etc). Use the name that is in the information about the
4537 device that is printed at startup.
4538 For input channels with tuners (e.g. Television) one can change
4540 which station is selected by the sta=XXX setting. XXX is the
4541 station number. Currently only the ntsc-cable-us (US cable)
4542 channels are built into x11vnc. See the -freqtab option below
4543 to supply one from xawtv. If XXX is greater than 500, then it is
4544 interpreted as a raw frequency in KHz.
4545 Example:
4547 -rawfb video:br=80,w=320,h=240,fmt=RGB32,tun=NTSC,sta=47
4549 one might need to add inp=Television too for the input channel
4551 to be TV if the card doesn't come up by default in that one.
4552 Note that not all video capture devices will support all of the
4554 above settings.
4555 See the -pipeinput VID option below for a way to control the
4557 settings through the VNC Viewer via keystrokes. As a shortcut,
4558 if the string begins "Video.." instead of "video.." then
4559 -pipeinput VID is implied.
4560 As above, if you specify a "@WxHxB..." after the <settings>
4562 string they are used verbatim: the device is not queried for the
4563 current values. Otherwise the device will be queried.
4564 LINUX CONSOLE: The following describes some ways to view and
4566 possibly interact with the Linux text/graphics console (i.e. not
4567 X11 XFree86/Xorg)
4568 Note: If the LibVNCServer LinuxVNC program is on your system you
4570 may want to use that instead of the following method because it
4571 will be faster and more accurate for the Linux text console and
4572 includes mouse support. There is, however, the basic LinuxVNC
4573 functionality in x11vnc if you replace "console" with "vt" in
4574 the examples below.
4575 If the rawfb string begins with "console" the framebuffer device
4577 /dev/fb0 is opened and /dev/tty0 is opened too. The latter is
4578 used to inject keystrokes (not all are supported, but the basic
4579 ones are). You will need to be root to inject keystrokes, but
4580 not necessarily to open /dev/fb0. /dev/tty0 refers to the
4581 active VT, to indicate one explicitly, use, e.g., "console2" for
4582 /dev/tty2, etc. by indicating the specific VT number.
4583 For the Linux framebuffer device, /dev/fb0, (fb1, etc) to be
4585 enabled the appropriate kernel drivers must be loaded. E.g.
4586 vesafb or vga16fb and also by setting the boot parameter
4587 vga=0x301 (or 0x314, 0x317, etc.) (The vga=... method is the
4588 preferred way; set your machines up that way.) Otherwise there
4589 will be a ´No such device' error. You can also load a Linux
4590 framebuffer driver specific to your make of video card for more
4591 functionality. Once the machine is booted one can often 'mod‐
4592 probe' the fb driver as root to obtain a framebuffer device.
4593 If you cannot get /dev/fb0 working on Linux, try using the Lin‐
4595 uxVNC emulation mode by "-rawfb vtN" where N = 1, ... 6 is the
4596 Linux Virtual Terminal (aka virtual console) you wish to view,
4597 e.g. "-rawfb vt2". Unlike /dev/fb mode, it need not be the
4598 active Virtual Terminal. Note that this mode can only show text
4599 and not graphics. x11vnc polls the text in /dev/vcsaN
4600 Set the env. var. RAWFB_VCSA_BW=1 to disable colors in the "vtN"
4602 mode (i.e. black and white only.) If you do not prefer the
4603 default 16bpp set RAWFB_VCSA_BPP to 8 or 32. If you need to
4604 tweak the rawfb parameters by using the 'console_guess' string
4605 printed at startup, be sure to indicate the snap: method.
4606 uinput: If the Linux version appears to be 2.6 or later and the
4608 "uinput" module appears to be present (modprobe uinput), then
4609 the uinput method will be used instead of /dev/ttyN. uinput
4610 allows insertion of BOTH keystrokes and mouse input and so it
4611 preferred when accessing graphical (e.g. QT-embedded) linux con‐
4612 sole apps. It also provides more accurate keystroke insertion.
4613 See -pipeinput UINPUT below for more information on this mode;
4614 you will have to use -pipeinput if you want to tweak any UINPUT
4615 parameters. You may also want to also use the -nodragging and
4616 -cursor none options. Use "console0", etc or -pipeinput CON‐
4617 SOLE to force the /dev/ttyN method.
4618 Note you can change the Linux VT remotely using the chvt(1) com‐
4620 mand to make the one you want be the active one (e.g. 'chvt 3').
4621 Sometimes switching out and back corrects the framebuffer's
4622 graphics state. For the "-rawfb vtN" mode there is no need to
4623 switch the VT's.
4624 To skip input injecting entirely use "consolex" or "vtx".
4626 The string "/dev/fb0" (1, etc.) can be used instead of "con‐
4628 sole". This can be used to specify a different framebuffer
4629 device, e.g. /dev/fb1. As a shortcut the "/dev/" can be
4630 dropped. If the name is something nonstandard, use "con‐
4631 sole:/dev/foofb"
4632 If you do not want x11vnc to guess the framebuffer's WxHxB and
4634 masks automatically (sometimes the kernel gives incorrect infor‐
4635 mation), specify them with a @WxHxB (and optional :R/G/B masks)
4636 at the end of the string.
4637 Examples: -rawfb console -rawfb /dev/fb0 (same) -rawfb
4639 console3 (force /dev/tty3) -rawfb consolex
4640 (no keystrokes or mouse) -rawfb console:/dev/nonstd -rawfb con‐
4641 sole -pipeinput UINPUT:accel=4.0 -rawfb vt3
4642 (/dev/tty3 w/o /dev/fb0)
4643 VNC HOST: if the -rawfb string is of the form "vnc:host:N" then
4645 the VNC display "N" on the remote VNC server "host" is connected
4646 to (i.e. x11vnc acts as a VNC client itself) and that frame‐
4647 buffer is exported.
4648 This mode is really only of use if you are trying to improve
4650 performance in the case of many (e.g. > 10) simultaneous VNC
4651 viewers, and you try a divide and conquer scheme to reduce band‐
4652 width and improve responsiveness. (However, another user found
4653 this mode useful to export a demo display through a slow link:
4654 then multiple demo viewers connected to the reflecting x11vnc on
4655 the fast side of the link, and so avoided all of the demo view‐
4656 ers going through the slow link.)
4657 For example, if there will be 64 simultaneous VNC viewers this
4659 can lead to a lot of redundant VNC traffic to and from the
4660 server host:N, extra CPU usage, and all viewers response can be
4661 reduced by having to wait for writes to the slowest client to
4662 finish. However, if you set up 8 reflectors/repeaters started
4663 with option -rawfb vnc:host:N, then there are only 8 connections
4664 to host:N. Each repeater then handles 8 vnc viewer connections
4665 thereby spreading the load around. In classroom broadcast
4666 usage, try to put the repeaters on different switches. This
4667 mode is the same as -reflect host:N. Replace "host:N" by "lis‐
4668 ten" or "listen:port" for a reverse connection.
4669 Overall performance will not be as good as a single direct con‐
4671 nection because, among other things, there is an additional
4672 level of framebuffer polling and pointer motion can still induce
4673 many changes per second that must be propagated. Tip: if the
4674 remote VNC is x11vnc doing wireframing, or an X display that
4675 does wireframing that gives much better response than opaque
4676 window dragging. Consider the -nodragging option if the problem
4677 is severe.
4678 The env. var. X11VNC_REFLECT_PASSWORD can be set to the password
4680 needed to log into the vnc host server, or to
4681 "file:path_to_file" to indicate a file containing the password
4682 as its first line.
4683 To set the pixel format that x11vnc requests as a VNC CLIENT set
4685 the env. vars: X11VNC_REFLECT_bitsPerSample X11VNC_REFLECT_sam‐
4686 plesPerPixel, and X11VNC_REFLECT_bytesPerPixel; the defaults are
4687 8, 3, 4. 2, 3, 1 would give a low color mode. See the function
4688 rfbGetClient() in libvncclient for more info.
4689 The VNC HOST mode implies -shared. Use -noshared as a subse‐
4691 quent cmdline option to disable sharing.
4692 -freqtab file
4694 For use with "-rawfb video" for TV tuner devices to specify sta‐
4696 tion frequencies. Instead of using the built in ntsc-cable-us
4697 mapping of station number to frequency, use the data in file.
4698 For stations that are not numeric, e.g. SE20, they are placed
4699 above the highest numbered station in the order they are found.
4700 Example: "-freqtab /usr/X11R6/share/xawtv/europe-west.list" You
4701 can make your own freqtab by copying the xawtv format.
4702 -pipeinput cmd
4704 This option lets you supply an external command in cmd that
4706 x11vnc will pipe all of the user input events to in a simple
4707 format. In -pipeinput mode by default x11vnc will not process
4708 any of the user input events. If you prefix cmd with "tee:" it
4709 will both send them to the pipe command and process them. For a
4710 description of the format run "-pipeinput tee:/bin/cat".
4711 Another prefix is "reopen" which means to reopen pipe if it
4712 exits. Separate multiple prefixes with commas.
4713 In combination with -rawfb one might be able to do amusing
4715 things (e.g. control non-X devices). To facilitate this, if
4716 -rawfb is in effect then the value is stored in X11VNC_RAWFB_STR
4717 for the pipe command to use if it wants. Do 'env | grep X11VNC'
4718 for more.
4719 Built-in pipeinput modes (no external program required):
4721 If cmd is "VID" and you are using the -rawfb for a video capture
4723 device, then an internal list of keyboard mappings is used to
4724 set parameters of the video. The mappings are:
4725 "B" and "b" adjust the brightness up and down. "H" and "h"
4727 adjust the hue. "C" and "c" adjust the colour. "N" and "n"
4728 adjust the contrast. "S" and "s" adjust the size of the capture
4729 screen. "I" and "i" cycle through input channels. Up and Down
4730 arrows adjust the station (if a tuner) F1, F2, ..., F6 will
4731 switch the video capture pixel format to HI240, RGB565, RGB24,
4732 RGB32, RGB555, and GREY respectively. See -rawfb video for
4733 details.
4734 If cmd is "CONSOLE" or "CONSOLEn" where n is a Linux console
4736 number, then the linux console keystroke insertion to /dev/ttyN
4737 (see -rawfb console) is performed.
4738 If cmd begins with "UINPUT" then the Linux uinput module is used
4740 to insert both keystroke and mouse events to the Linux console
4741 (see -rawfb above). This usually is the /dev/input/uinput
4742 device file (you may need to create it with "mknod
4743 /dev/input/uinput c 10 223" and insert the module with "modprobe
4744 uinput".
4745 The UINPUT mode currently only does US keyboards (a scan code
4747 option may be added), and not all keysyms are supported. But it
4748 is probably more accurate than the "CONSOLE" method.
4749 You may want to use the options -cursor none and -nodragging in
4751 this mode.
4752 Additional tuning options may be supplied via: UIN‐
4754 PUT:opt1,opt2,... (a comma separated list). If an option begins
4755 with "/" it is taken as the uinput device file.
4756 Which uinput is injected can be controlled by an option string
4758 made of the characters "K", "M", and "B" (see the -input
4759 option), e.g. "KM" allows keystroke and motion but not button
4760 clicks.
4761 A UINPUT option of the form: accel=f, or accel=fx+fy sets the
4763 mouse motion "acceleration". This is used to correct raw mouse
4764 relative motion into how much the application cursor moves
4765 (x11vnc has no control over, or knowledge of how the windowing
4766 application interprets the raw mouse motions). Typically the
4767 acceleration for an X display is 2 (see xset "m" option). "f"
4768 is a floating point number, e.g. 3.0. Use "fx+fy" if you need
4769 to supply different corrections for x and y.
4770 Note: the default acceleration is 2.0 since it seems both X and
4772 qt-embedded often (but not always) use this value.
4773 Even with a correct accel setting the mouse position will get
4775 out of sync (probably due to a mouse "threshold" setting where
4776 the acceleration doe not apply, set xset(1) ). The option
4777 reset=N sets the number of ms (default 150) after which the cur‐
4778 sor is attempted to be reset (by forcing the mouse to (0, 0) via
4779 small increments and then back out to (x, y) in 1 jump), This
4780 correction seems to be needed but can cause jerkiness or unex‐
4781 pected behavior with menus, etc. Use reset=0 to disable.
4782 If you set the env. var X11VNC_UINPUT_THRESHOLDS then the
4784 thresh=n mode will be enabled. It is currently not working
4785 well. If |dx| <= thresh and |dy| < thresh no acceleration is
4786 applied. Use "thresh=+n" |dx| + |dy| < thresh to be used
4787 instead (X11?)
4788 Example: -pipeinput UINPUT:accel=4.0 -cursor none
4790 If the uinput device has an absolute pointer (as opposed to a
4792 normal mouse that is a relative pointer) you can specify the
4793 option "abs". Note that a touchpad on a laptop is an absolute
4794 device to some degree. This (usually) avoids all the problems
4795 with mouse acceleration. If x11vnc has trouble deducing the
4796 size of the device, use "abs=WxH". Furthermore, if the device
4797 is a touchscreen (assumed to have an absolute pointer) use
4798 "touch" or "touch=WxH". For touchscreens, when a mouse button
4799 is pressed, a pressure increase is injected, and when the button
4800 is released a pressure of zero is injected.
4801 If touch has been set, use "touch_always=1" to indicate whenever
4803 the mouse moves with no button pressed, a touch event of zero
4804 pressure should be sent anyway. Also use "btn_touch=1" to indi‐
4805 cate a BTN_TOUCH keystroke press or release should be sent
4806 instead of a pressure change. Set "dragskip=n" to skip n
4807 dragged mouse touches (with pressure applied) before injecting
4808 one. To indicate the pressure that should be sent when there is
4809 a button click for a touchscreen device, specify pressure=n,
4810 e.g. n=5. The default is n=1.
4811 If a touch screen is being used ("touch" above) and it is having
4813 its input processed by tslib, you can specify the tslib calibra‐
4814 tion file via tslib_cal=<file>. For example,
4815 tslib_cal=/etc/pointercal. To get accurate or even usable posi‐
4816 tioning this is required when tslib is in use.
4817 The Linux uinput mechanism can be bypassed and one can write
4819 input events DIRECTLY to the devices instead. To do this, spec‐
4820 ify one or more of the following for the input classes:
4821 direct_rel=<device> direct_abs=<device> direct_btn=<device> or
4822 direct_key=<device>. The <device> file is usually something
4823 like /dev/input/event1 but you can specify any device file or
4824 pipe. You must specify each one of the above classes even if
4825 they correspond to the same device file (rel/abs and btn are
4826 often the same.) Look at the file /proc/bus/input/devices to
4827 get an idea what is available and the device filenames. Note:
4828 The /dev/input/mouse* devices do not seem to work, use the cor‐
4829 responding /dev/input/event* file instead. Any input class not
4830 directly specified as above will be handled via the uinput mech‐
4831 anism. To disable creating a uinput device (and thereby dis‐
4832 carding unhandled input), specify "nouinput".
4833 Examples:
4835 -pipeinput UINPUT:direct_abs=/dev/input/event1
4837 this was used on a qtmoko Neo freerunner (armel):
4839 -pipeinput UINPUT:touch,tslib_cal=/etc/pointercal,
4841 direct_abs=/dev/input/event1,nouinput,dragskip=4
4842 (where the long line has been split into two.)
4844 You can set the env. var X11VNC_UINPUT_DEBUG=1 or higher to get
4846 debugging output for UINPUT mode.
4847 -macnodim
4849 For the native MacOSX server, disable dimming.
4851 -macnosleep
4853 For the native MacOSX server, disable display sleep.
4855 -macnosaver
4857 For the native MacOSX server, disable screensaver.
4859 -macnowait
4861 For the native MacOSX server, do not wait for the user to switch
4863 back to his display.
4864 -macwheel n
4866 For the native MacOSX server, set the mouse wheel speed to n
4868 (default 5).
4869 -macnoswap
4871 For the native MacOSX server, do not swap mouse buttons 2 and 3.
4873 -macnoresize
4875 For the native MacOSX server, do not resize or reset the frame‐
4877 buffer even if it is detected that the screen resolution or
4878 depth has changed.
4879 -maciconanim n
4881 For the native MacOSX server, set n to the number of millisec‐
4883 onds that the window iconify/deiconify animation takes. In
4884 -ncache mode this value will be used to skip the animation if
4885 possible. (default 400)
4886 -macmenu
4888 For the native MacOSX server, in -ncache client-side caching
4890 mode, try to cache pull down menus (not perfect because they
4891 have animated fades, etc.)
4892 -macuskbd
4894 For the native MacOSX server, use the original keystroke inser‐
4896 tion code based on a US keyboard.
4897 -macnoopengl
4899 For the native MacOSX server, do not use OpenGL for screen cap‐
4901 ture, but rather use the original, deprecated raw memory access
4902 method: addr = CGDisplayBaseAddress().
4903 -macnorawfb
4905 For the native MacOSX server, disable the raw memory address
4907 screen capture method.
4908 MACOSX NOTE: There are some deprecated MacOSX interfaces to
4910 inject keyboard and mouse events and the raw memory access
4911 method is deprecated as well (however, OpenGL will be preferred
4912 if available because it is faster.) One can force not using any
4913 deprecated interfaces at compile time by setting
4914 -DX11VNC_MACOSX_NO_DEPRECATED=1 in CPPFLAGS. Or to turn them
4915 off one by one: -DX11VNC_MACOSX_NO_DEPRECATED_LOCALEVENTS=1,
4916 -DX11VNC_MACOSX_NO_DEPRECATED_POSTEVENTS=1 or
4917 -DX11VNC_MACOSX_NO_DEPRECATED_FRAMEBUFFER=1 At run time, for
4918 testing and workarounds, one can disable them by using: -env
4919 X11VNC_MACOSX_NO_DEPRECATED=1 -env X11VNC_MACOSX_NO_DEPRE‐
4920 CATED_LOCALEVENTS=1 -env X11VNC_MACOSX_NO_DEPRE‐
4921 CATED_POSTEVENTS=1 or -env X11VNC_MACOSX_NO_DEPRECATED_FRAME‐
4922 BUFFER=1 Note: When doing either of these for the mouse input
4923 not everything works currently, e.g. double clicks and wirefram‐
4924 ing. Also, screen resolution and pixel depth changes will not
4925 be automatically detected unless the deprecated framebuffer
4926 interfaces are allowed.
4927 Conversely, if you are compiling on an older machine that does
4929 not have some of the newer interfaces, you may need to specify
4930 -DX11VNC_MACOSX_NO_CGEVENTCREATESCROLLWHEELEVENT
4931 -DX11VNC_MACOSX_NO_CGEVENTCREATEMOUSEEVENT or
4932 -DX11VNC_MACOSX_NO_CGEVENTCREATEKEYBOARDEVENT. Use
4933 -DX11VNC_MACOSX_USE_GETMAINDEVICE to regain the very old Quick‐
4934 Draw GetMainDevice() interface (rare...)
4935 -gui [gui-opts]
4937 Start up a simple tcl/tk gui based on the remote control options
4939 -remote/-query described below. Requires the "wish" program to
4940 be installed on the machine. "gui-opts" is not required: the
4941 default is to start up both the full gui and x11vnc with the gui
4942 showing up on the X display in the environment variable DISPLAY.
4943 "gui-opts" can be a comma separated list of items. Currently
4945 there are these types of items: 1) a gui mode, a 2) gui "sim‐
4946 plicity", 3) the X display the gui should display on, 4) a
4947 "tray" or "icon" mode, and 5) a gui geometry.
4948 1) The gui mode can be "start", "conn", or "wait" "start" is the
4950 default mode above and is not required. "conn" means do not
4951 automatically start up x11vnc, but instead just try to connect
4952 to an existing x11vnc process. "wait" means just start the gui
4953 and nothing else (you will later instruct the gui to start
4954 x11vnc or connect to an existing one.)
4955 2) The gui simplicity is off by default (a power-user gui with
4957 all options is presented) To start with something less daunting
4958 supply the string "simple" ("ez" is an alias for this). Once
4959 the gui is started you can toggle between the two with "Misc ->
4960 simple_gui".
4961 3) Note the possible confusion regarding the potentially two
4963 different X displays: x11vnc polls one, but you may want the gui
4964 to appear on another. For example, if you ssh in and x11vnc is
4965 not running yet you may want the gui to come back to you via
4966 your ssh redirected X display (e.g. localhost:10).
4967 If you do not specify a gui X display in "gui-opts" then the
4969 DISPLAY environment variable and -display option are tried (in
4970 that order). Regarding the x11vnc X display the gui will try to
4971 communication with, it first tries -display and then DISPLAY.
4972 For example, "x11vnc -display :0 -gui otherhost:0", will remote
4973 control an x11vnc polling :0 and display the gui on otherhost:0
4974 The "tray/icon" mode below reverses this preference, preferring
4975 to display on the x11vnc display.
4976 4) When "tray" or "icon" is specified, the gui presents itself
4978 as a small icon with behavior typical of a "system tray" or
4979 "dock applet". The color of the icon indicates status (con‐
4980 nected clients) and there is also a balloon status. Clicking on
4981 the icon gives a menu from which properties, etc, can be set and
4982 the full gui is available under "Advanced". To be fully func‐
4983 tional, the gui mode should be "start" (the default).
4984 Note that tray or icon mode will imply the -forever x11vnc
4986 option (if the x11vnc server is started along with the gui)
4987 unless -connect or -connect_or_exit has been specified. So
4988 x11vnc (and the tray/icon gui) will wait for more connections
4989 after the first client disconnects. If you want only one viewer
4990 connection include the -once option.
4991 For "icon" the gui just a small standalone window. For "tray"
4993 it will attempt to embed itself in the "system tray" if possi‐
4994 ble. If "=setpass" is appended then at startup the X11 user will
4995 be prompted to set the VNC session password. If =<hexnumber> is
4996 appended that icon will attempt to embed itself in the window
4997 given by hexnumber. Use =noadvanced to disable the full gui.
4998 (To supply more than one, use "+" sign). E.g. -gui tray=setpass
4999 and -gui icon=0x3600028
5000 Other modes: "full", the default and need not be specified.
5002 "-gui none", do not show a gui, useful to override a ~/.x11vncrc
5003 setting, etc.
5004 5) When "geom=+X+Y" is specified, that geometry is passed to the
5006 gui toplevel. This is the icon in icon/tray mode, or the full
5007 gui otherwise. You can also specify width and height, i.e.
5008 WxH+X+Y, but it is not recommended. In "tray" mode the geometry
5009 is ignored unless the system tray manager does not seem to be
5010 running. One could imagine using something like "-gui
5011 tray,geom=+4000+4000" with a display manager to keep the gui
5012 invisible until someone logs in...
5013 More icon tricks, "icon=minimal" gives an icon just with the VNC
5015 display number. You can also set the font with "iconfont=...".
5016 The following could be useful: "-gui icon=minimal,icon‐
5017 font=5x8,geom=24x10+0-0"
5018 General examples of the -gui option: "x11vnc -gui", "x11vnc -gui
5020 ez" "x11vnc -gui localhost:10", "x11vnc -gui conn,host:0",
5021 "x11vnc -gui tray,ez" "x11vnc -gui tray=setpass"
5022 If you do not intend to start x11vnc from the gui (i.e. just
5024 remote control an existing one), then the gui process can run on
5025 a different machine from the x11vnc server as long as X permis‐
5026 sions, etc. permit communication between the two.
5027 FONTS: On some systems the tk fonts can be too small, jagged, or
5029 otherwise unreadable. There are 4 env vars you can set to be
5030 the tk font you prefer:
5031 X11VNC_FONT_BOLD main font for menus and buttons.
5033 X11VNC_FONT_FIXED font for fixed width text.
5034 X11VNC_FONT_BOLD_SMALL tray icon font. X11VNC_FONT_REG_SMALL
5036 tray icon menu font.
5037 The last two only apply for the tray icon mode.
5039 Here are some examples:
5041 -env X11VNC_FONT_BOLD='Helvetica -16 bold' -env
5043 X11VNC_FONT_FIXED='Courier -14' -env X11VNC_FONT_REG_SMALL='Hel‐
5044 vetica -12'
5045 You can put the lines like the above (without the quotes) in
5047 your ~/.x11vncrc file to avoid having to specify them on the
5048 x11vnc command line.
5049 -remote command
5051 Remotely control some aspects of an already running x11vnc
5053 server. "-R" and "-r" are aliases for "-remote". After the
5054 remote control command is sent to the running server the 'x11vnc
5055 -remote ...' x11vnc command exits. You can often use the
5056 -query command (see below) to see if the x11vnc server processed
5057 your -remote command.
5058 The default communication channel is that of X properties
5060 (specifically X11VNC_REMOTE), and so this command must be run
5061 with correct settings for DISPLAY and possibly XAUTHORITY to
5062 connect to the X server and set the property. Alternatively,
5063 use the -display and -auth options to set them to the correct
5064 values. The running server cannot use the -novncconnect option
5065 because that disables the communication channel. See below for
5066 alternate channels.
5067 For example: 'x11vnc -remote stop' (which is the same as ´x11vnc
5069 -R stop') will close down the x11vnc server. ´x11vnc -R shared'
5070 will enable shared connections, and ´x11vnc -R scale:3/4' will
5071 rescale the desktop.
5072 To use a different name for the X11 property (e.g. to have sepa‐
5074 rate communication channels for multiple x11vnc's on the same
5075 display) set the X11VNC_REMOTE environment variable to the
5076 string you want, for example: -env
5077 X11VNC_REMOTE=X11VNC_REMOTE_12345 Both sides of the channel must
5078 use the same unique name.
5079 To run a bunch of commands in a sequence use something like:
5081 x11vnc -R 'script:firstcmd;secondcmd;...'
5082 Use x11vnc -R script:file=/path/to/file to read commands from a
5084 file (can be multi-line and use the comment '#' character in the
5085 normal way. The ';' separator must still be used to separate
5086 each command.)
5087 To not try to contact another x11vnc process and instead just
5089 run the command (or query) directly, prefix the command with the
5090 string "DIRECT:"
5091 The following -remote/-R commands are supported:
5093 stop terminate the server, same as "quit" "exit" or
5095 "shutdown".
5096 ping see if the x11vnc server responds. return is:
5098 ans=ping:<display>
5099 ping:mystring as above, but use your own unique string.
5101 return is: ans=ping:mystring:<xdisplay>
5102 blacken try to push a black fb update to all clients
5104 (due to timings a client could miss it). Same as "zero", also
5105 "zero:x1,y1,x2,y2" for a rectangle.
5106 refresh send the entire fb to all clients.
5108 reset recreate the fb, polling memory, etc.
5110 id:windowid set -id window to "windowid". empty or "root" to
5112 go back to root window
5113 sid:windowid set -sid window to "windowid"
5115 id_cmd:cmd cmds: raise, lower, map, unmap, iconify,
5117 move:dXdY, resize:dWdH, geom:WxH+X+Y. dX dY, dW, and dH must
5118 have a leading "+" or "-" e.g.: move:-30+10 resize:+20+35 also:
5119 wm_delete, wm_name:string and icon_name:string. Also
5120 id_cmd:win=N:cmd
5121 waitmapped wait until subwin is mapped.
5123 nowaitmapped do not wait until subwin is mapped.
5125 clip:WxH+X+Y set -clip mode to "WxH+X+Y"
5127 flashcmap enable -flashcmap mode.
5129 noflashcmap disable -flashcmap mode.
5131 shiftcmap:n set -shiftcmap to n.
5133 notruecolor enable -notruecolor mode.
5135 truecolor disable -notruecolor mode.
5137 overlay enable -overlay mode (if applicable).
5139 nooverlay disable -overlay mode.
5141 overlay_cursor in -overlay mode, enable cursor drawing.
5143 overlay_nocursor disable cursor drawing. same as nooverlay_cur‐
5145 sor.
5146 8to24 enable -8to24 mode (if applicable).
5148 no8to24 disable -8to24 mode.
5150 8to24_opts:str set the -8to24 opts to "str".
5152 24to32 enable -24to32 mode (if applicable).
5154 no24to32 disable -24to32 mode.
5156 visual:vis set -visual to "vis"
5158 scale:frac set -scale to "frac"
5160 scale_cursor:f set -scale_cursor to "f"
5162 viewonly enable -viewonly mode.
5164 noviewonly disable -viewonly mode.
5166 shared enable -shared mode.
5168 noshared disable -shared mode.
5170 forever enable -forever mode.
5172 noforever disable -forever mode.
5174 timeout:n reset -timeout to n, if there are currently no
5176 clients, exit unless one connects in the next n secs.
5177 tightfilexfer enable filetransfer for NEW clients.
5179 notightfilexfer disable filetransfer for NEW clients.
5181 ultrafilexfer enable filetransfer for clients.
5183 noultrafilexfer disable filetransfer for clients.
5185 rfbversion:n.m set -rfbversion for new clients.
5187 http enable http client connections.
5189 nohttp disable http client connections.
5191 deny deny any new connections, same as "lock"
5193 nodeny allow new connections, same as "unlock"
5195 avahi enable avahi service advertising.
5197 noavahi disable avahi service advertising.
5199 mdns enable avahi service advertising.
5201 nomdns disable avahi service advertising.
5203 zeroconf enable avahi service advertising.
5205 nozeroconf disable avahi service advertising.
5207 connect:host do reverse connection to host, "host" may be a
5209 comma separated list of hosts or host:ports. See -connect.
5210 Passwords required as with fwd connections. See
5211 X11VNC_REVERSE_CONNECTION_NO_AUTH=1
5212 disconnect:host disconnect any clients from "host" same as
5214 "close:host". Use host "all" to close all current clients. If
5215 you know the client internal hex ID, e.g. 0x3 (returned by
5216 "-query clients" and RFB_CLIENT_ID) you can use that too.
5217 proxy:host:port set reverse connection proxy (empty to disable).
5219 allowonce:host For the next connection only, allow connection
5221 from "host". In -ssl mode two connections are allowed (i.e.
5222 Fetch Cert) unless X11VNC_NO_SSL_ALLOW_TWICE=1
5223 allow:hostlist set -allow list to (comma separated) "hostlist".
5225 See -allow and -localhost. Do not use with -allow /path/to/file
5226 Use "+host" to add a single host, and use "-host" to delete a
5227 single host
5228 localhost enable -localhost mode
5230 nolocalhost disable -localhost mode
5232 listen:str set -listen to str, empty to disable.
5234 noipv6 enable -noipv6 mode.
5236 ipv6 disable -noipv6 mode.
5238 noipv4 enable -noipv4 mode.
5240 ipv4 disable -noipv4 mode.
5242 6 enable -6 IPv6 listening mode.
5244 no6 disable -6 IPv6 listening mode.
5246 lookup disable -nolookup mode.
5248 nolookup enable -nolookup mode.
5250 lookup disable -nolookup mode.
5252 input:str set -input to "str", empty to disable.
5254 grabkbd enable -grabkbd mode.
5256 nograbkbd disable -grabkbd mode.
5258 grabptr enable -grabptr mode.
5260 nograbptr disable -grabptr mode.
5262 grabalways enable -grabalways mode.
5264 nograbalways disable -grabalways mode.
5266 grablocal:n set -grablocal to n.
5268 client_input:str set the K, M, B -input on a per-client basis.
5270 select which client as for disconnect, e.g. client_input:host:MB
5271 or client_input:0x2:K
5272 accept:cmd set -accept "cmd" (empty to disable).
5274 afteraccept:cmd set -afteraccept (empty to disable).
5276 gone:cmd set -gone "cmd" (empty to disable).
5278 noshm enable -noshm mode.
5280 shm disable -noshm mode (i.e. use shm).
5282 flipbyteorder enable -flipbyteorder mode, you may need to set
5284 noshm for this to do something.
5285 noflipbyteorder disable -flipbyteorder mode.
5287 onetile enable -onetile mode. (you may need to set shm
5289 for this to do something)
5290 noonetile disable -onetile mode.
5292 solid enable -solid mode
5294 nosolid disable -solid mode.
5296 solid_color:color set -solid color (and apply it).
5298 blackout:str set -blackout "str" (empty to disable). See
5300 -blackout for the form of "str" (basically: WxH+X+Y,...) Use
5301 "+WxH+X+Y" to append a single rectangle use "-WxH+X+Y" to delete
5302 one
5303 xinerama enable -xinerama mode. (if applicable)
5305 noxinerama disable -xinerama mode.
5307 xtrap enable -xtrap input mode(if applicable)
5309 noxtrap disable -xtrap input mode.
5311 xrandr enable -xrandr mode. (if applicable)
5313 noxrandr disable -xrandr mode.
5315 xrandr_mode:mode set the -xrandr mode to "mode".
5317 rotate:mode set the -rotate mode to "mode".
5319 padgeom:WxH set -padgeom to WxH (empty to disable) If WxH is
5321 "force" or "do" the padded geometry fb is immediately applied.
5322 quiet enable -quiet mode.
5324 noquiet disable -quiet mode.
5326 modtweak enable -modtweak mode.
5328 nomodtweak enable -nomodtweak mode.
5330 xkb enable -xkb modtweak mode.
5332 noxkb disable -xkb modtweak mode.
5334 capslock enable -capslock mode.
5336 nocapslock disable -capslock mode.
5338 skip_lockkeys enable -skip_lockkeys mode.
5340 noskip_lockkeys disable -skip_lockkeys mode.
5342 skip_keycodes:str enable -xkb -skip_keycodes "str".
5344 sloppy_keys enable -sloppy_keys mode.
5346 nosloppy_keys disable -sloppy_keys mode.
5348 skip_dups enable -skip_dups mode.
5350 noskip_dups disable -skip_dups mode.
5352 add_keysyms enable -add_keysyms mode.
5354 noadd_keysyms stop adding keysyms. those added will still be
5356 removed at exit.
5357 clear_mods enable -clear_mods mode and clear them.
5359 noclear_mods disable -clear_mods mode.
5361 clear_keys enable -clear_keys mode and clear them.
5363 noclear_keys disable -clear_keys mode.
5365 clear_locks do the clear_locks action.
5367 clear_all do the clear_all action.
5369 keystate have x11vnc print current keystate.
5371 remap:str set -remap "str" (empty to disable). See -remap
5373 for the form of "str" (basically: key1-key2,key3-key4,...) Use
5374 "+key1-key2" to append a single keymapping, use "-key1-key2" to
5375 delete.
5376 norepeat enable -norepeat mode.
5378 repeat disable -norepeat mode.
5380 nofb enable -nofb mode.
5382 fb disable -nofb mode.
5384 bell enable bell (if supported).
5386 nobell disable bell.
5388 sendbell ring the bell now.
5390 nosel enable -nosel mode.
5392 sel disable -nosel mode.
5394 noprimary enable -noprimary mode.
5396 primary disable -noprimary mode.
5398 nosetprimary enable -nosetprimary mode.
5400 setprimary disable -nosetprimary mode.
5402 noclipboard enable -noclipboard mode.
5404 clipboard disable -noclipboard mode.
5406 nosetclipboard enable -nosetclipboard mode.
5408 setclipboard disable -nosetclipboard mode.
5410 seldir:str set -seldir to "str"
5412 resend_cutbuffer resend the most recent CUTBUFFER0 copy
5414 resend_clipboard resend the most recent CLIPBOARD copy
5416 resend_primary resend the most recent PRIMARY copy
5418 cursor:mode enable -cursor "mode".
5420 show_cursor enable showing a cursor.
5422 noshow_cursor disable showing a cursor. (same as "nocursor")
5424 cursor_drag enable cursor changes during drag.
5426 nocursor_drag disable cursor changes during drag.
5428 arrow:n set -arrow to alternate n.
5430 xfixes enable xfixes cursor shape mode.
5432 noxfixes disable xfixes cursor shape mode.
5434 alphacut:n set -alphacut to n.
5436 alphafrac:f set -alphafrac to f.
5438 alpharemove enable -alpharemove mode.
5440 noalpharemove disable -alpharemove mode.
5442 alphablend disable -noalphablend mode.
5444 noalphablend enable -noalphablend mode.
5446 cursorshape disable -nocursorshape mode.
5448 nocursorshape enable -nocursorshape mode.
5450 cursorpos disable -nocursorpos mode.
5452 nocursorpos enable -nocursorpos mode.
5454 xwarp enable -xwarppointer mode.
5456 noxwarp disable -xwarppointer mode.
5458 always_inject enable -always_inject mode.
5460 noalways_inject disable -always_inject mode.
5462 buttonmap:str set -buttonmap "str", empty to disable
5464 dragging disable -nodragging mode.
5466 nodragging enable -nodragging mode.
5468 ncache reenable -ncache mode.
5470 noncache disable -ncache mode.
5472 ncache_size:n set -ncache size to n.
5474 ncache_cr enable -ncache_cr mode.
5476 noncache_cr disable -ncache_cr mode.
5478 ncache_no_moveraise enable no_moveraise mode.
5480 noncache_no_moveraise disable no_moveraise mode.
5482 ncache_no_dtchange enable ncache_no_dtchange mode.
5484 noncache_no_dtchange disable ncache_no_dtchange mode.
5486 ncache_old_wm enable ncache_old_wm mode.
5488 noncache_old_wm disable ncache_old_wm mode.
5490 ncache_no_rootpixmap enable ncache_no_rootpixmap.
5492 noncache_no_rootpixmap disable ncache_no_rootpixmap.
5494 ncache_reset_rootpixmap recheck the root pixmap, ncrp
5496 ncache_keep_anims enable ncache_keep_anims.
5498 noncache_keep_anims disable ncache_keep_anims.
5500 ncache_pad:n set -ncache_pad to n.
5502 wireframe enable -wireframe mode. same as "wf"
5504 nowireframe disable -wireframe mode. same as "nowf"
5506 wireframe:str enable -wireframe mode string.
5508 wireframe_mode:str enable -wireframe mode string.
5510 wireframelocal enable wireframelocal. same as "wfl"
5512 nowireframe disable wireframelocal. same as "nowfl"
5514 wirecopyrect:str set -wirecopyrect string. same as "wcr:"
5516 scrollcopyrect:str set -scrollcopyrect string. same "scr"
5518 noscrollcopyrect disable -scrollcopyrect__mode_. "noscr"
5520 scr_area:n set -scr_area to n
5522 scr_skip:list set -scr_skip to "list"
5524 scr_inc:list set -scr_inc to "list"
5526 scr_keys:list set -scr_keys to "list"
5528 scr_term:list set -scr_term to "list"
5530 scr_keyrepeat:str set -scr_keyrepeat to "str"
5532 scr_parms:str set -scr_parms parameters.
5534 fixscreen:str set -fixscreen to "str".
5536 noxrecord disable all use of RECORD extension.
5538 xrecord enable use of RECORD extension.
5540 reset_record reset RECORD extension (if avail.)
5542 pointer_mode:n set -pointer_mode to n. same as "pm"
5544 input_skip:n set -input_skip to n.
5546 allinput enable use of -allinput mode.
5548 noallinput disable use of -allinput mode.
5550 input_eagerly enable use of -input_eagerly mode.
5552 noinput_eagerly disable use of -input_eagerly mode.
5554 ssltimeout:n set -ssltimeout to n.
5556 speeds:str set -speeds to str.
5558 wmdt:str set -wmdt to str.
5560 debug_pointer enable -debug_pointer, same as "dp"
5562 nodebug_pointer disable -debug_pointer, same as "nodp"
5564 debug_keyboard enable -debug_keyboard, same as "dk"
5566 nodebug_keyboard disable -debug_keyboard, same as "nodk"
5568 keycode:n inject keystroke 'keycode' (xmodmap -pk)
5570 keycode:n,down inject 'keycode' (down=0,1)
5572 keysym:str inject keystroke 'keysym' (number/name)
5574 keysym:str,down inject 'keysym' (down=0,1)
5576 ptr:x,y,mask inject pointer event x, y, button-mask
5578 fakebuttonevent:button,down direct XTestFakeButtonEvent.
5580 sleep:t sleep floating point time t.
5582 get_xprop:p get X property named 'p'.
5584 set_xprop:p:val set X property named 'p' to 'val'. p ->
5586 id=NNN:p for hex/dec window id.
5587 wininfo:id get info about X window id. use 'root' for root
5589 window, use +id for children.
5590 grab_state get state of pointer and keyboard grab.
5592 pointer_pos print XQueryPointer x,y cursor position.
5594 pointer_x print XQueryPointer x cursor position.
5596 pointer_y print XQueryPointer y cursor position.
5598 pointer_same print XQueryPointer ptr on same screen.
5600 pointer_root print XQueryPointer curr ptr rootwin.
5602 pointer_mask print XQueryPointer button and mods mask
5604 mouse_x print x11vnc's idea of cursor position.
5606 mouse_y print x11vnc's idea of cursor position.
5608 noop do nothing.
5610 defer:n set -defer to n ms,same as deferupdate:n
5612 wait:n set -wait to n ms.
5614 extra_fbur:n set -extra_fbur to n.
5616 wait_ui:f set -wait_ui factor to f.
5618 setdefer:n set -setdefer to -2,-1,0,1, or 2.
5620 wait_bog disable -nowait_bog mode.
5622 nowait_bog enable -nowait_bog mode.
5624 slow_fb:f set -slow_fb to f seconds.
5626 xrefresh:f set -xrefresh to f seconds.
5628 readtimeout:n set read timeout to n seconds.
5630 nap enable -nap mode.
5632 nonap disable -nap mode.
5634 sb:n set -sb to n s, same as screen_blank:n
5636 fbpm disable -nofbpm mode.
5638 nofbpm enable -nofbpm mode.
5640 dpms disable -nodpms mode.
5642 nodpms enable -nodpms mode.
5644 forcedpms enable -forcedpms mode.
5646 noforcedpms disable -forcedpms mode.
5648 clientdpms enable -clientdpms mode.
5650 noclientdpms disable -clientdpms mode.
5652 noserverdpms enable -noserverdpms mode.
5654 serverdpms disable -noserverdpms mode.
5656 noultraext enable -noultraext mode.
5658 ultraext disable -noultraext mode.
5660 chatwindow enable local chatwindow mode.
5662 nochatwindow disable local chatwindow mode.
5664 chaton begin chat using local window.
5666 chatoff end chat using local window.
5668 xdamage enable xdamage polling hints.
5670 noxdamage disable xdamage polling hints.
5672 xd_area:A set -xd_area max pixel area to "A"
5674 xd_mem:f set -xd_mem remembrance to "f"
5676 fs:frac set -fs fraction to "frac", e.g. 0.5
5678 gaps:n set -gaps to n.
5680 grow:n set -grow to n.
5682 fuzz:n set -fuzz to n.
5684 snapfb enable -snapfb mode.
5686 nosnapfb disable -snapfb mode.
5688 rawfb:str set -rawfb mode to "str".
5690 uinput_accel:f set uinput_accel to f.
5692 uinput_thresh:n set uinput_thresh to n.
5694 uinput_reset:n set uinput_reset to n ms.
5696 uinput_always:n set uinput_always to 1/0.
5698 progressive:n set LibVNCServer -progressive slice height
5700 parameter to n.
5701 desktop:str set -desktop name to str for new clients.
5703 rfbport:n set -rfbport to n.
5705 macnosaver enable -macnosaver mode.
5707 macsaver disable -macnosaver mode.
5709 macnowait enable -macnowait mode.
5711 macwait disable -macnowait mode.
5713 macwheel:n set -macwheel to n.
5715 macnoswap enable -macnoswap mouse button mode.
5717 macswap disable -macnoswap mouse button mode.
5719 macnoresize enable -macnoresize mode.
5721 macresize disable -macnoresize mode.
5723 maciconanim:n set -maciconanim to n.
5725 macmenu enable -macmenu mode.
5727 macnomenu disable -macmenu mode.
5729 macuskbd enable -macuskbd mode.
5731 macnouskbd disable -macuskbd mode.
5733 httpport:n set -httpport to n.
5735 httpdir:dir set -httpdir to dir (and enable http).
5737 enablehttpproxy enable -enablehttpproxy mode.
5739 noenablehttpproxy disable -enablehttpproxy mode.
5741 alwaysshared enable -alwaysshared mode.
5743 noalwaysshared disable -alwaysshared mode. (may interfere
5745 with other options)
5746 nevershared enable -nevershared mode.
5748 nonevershared disable -nevershared mode. (may interfere with
5750 other options)
5751 dontdisconnect enable -dontdisconnect mode.
5753 nodontdisconnect disable -dontdisconnect mode. (may interfere
5755 with other options)
5756 debug_xevents enable debugging X events.
5758 nodebug_xevents disable debugging X events.
5760 debug_xdamage enable debugging X DAMAGE mechanism.
5762 nodebug_xdamage disable debugging X DAMAGE mechanism.
5764 debug_wireframe enable debugging wireframe mechanism.
5766 nodebug_wireframe disable debugging wireframe mechanism.
5768 debug_scroll enable debugging scrollcopy mechanism.
5770 nodebug_scroll disable debugging scrollcopy mechanism.
5772 debug_tiles enable -debug_tiles
5774 nodebug_tiles disable -debug_tiles
5776 debug_grabs enable -debug_grabs
5778 nodebug_grabs disable -debug_grabs
5780 debug_sel enable -debug_sel
5782 nodebug_sel disable -debug_sel
5784 debug_ncache enable -debug_ncache
5786 nodebug_ncache disable -debug_ncache
5788 dbg enable -dbg crash shell
5790 nodbg disable -dbg crash shell
5792 noremote disable the -remote command processing, it can‐
5794 not be turned back on.
5795 bcx_xattach:str This remote control command is for use with the
5797 BARCO xattach program or the x2x program. Both of these pro‐
5798 grams are for 'pointer and keyboard' sharing between separate X
5799 displays. In general the two displays are usually nearby, e.g.
5800 on the same desk, and this allows the user to share a single
5801 pointer and keyboard between them. The user moves the mouse to
5802 an edge and then the mouse pointer appears to 'jump' to the
5803 other display screen. Thus it emulates what a single X server
5804 would do for two screens (e.g. :0.0 and :0.1) The illusion of a
5805 single Xserver with multiple screens is achieved by forwarding
5806 events to the 2nd one via the XTEST extension.
5807 What the x11vnc bcx_xattach command does is to perform some
5809 pointer movements to try to INDUCE xattach/x2x to 'jump' to the
5810 other display. In what follows the ´master' display refers to
5811 the one that when it has ´focus' it is basically doing nothing
5812 besides watching for the mouse to go over an edge. The 'slave'
5813 display refers to the one to which the mouse and keyboard is
5814 redirected to once an edge in the master has been crossed. Note
5815 that the x11vnc executing the bcx_xattach command MUST be the
5816 one connected to the *master* display.
5817 Also note that when input is being redirected (via XTEST) from
5819 the master display to the slave display, the master display's
5820 pointer and keyboard are *grabbed* by xattach/x2x. x11vnc can
5821 use this info to verify that the master/slave mode change has
5822 taken place correctly. If you specify the "ifneeded" option
5823 (see below) and the initial grab state is that of the desired
5824 final state, then no pointer movements are injected and
5825 "DONE,GRAB_OK" is returned.
5826 "str" must contain one of "up", "down", "left", or "right" to
5828 indicate the direction of the 'jump'. "str" must also contain
5829 one of "master_to_slave" or "slave_to_master" to indicate the
5830 type of mode change induced by the jump. Use "M2S" and "S2M" as
5831 shorter aliases.
5832 "str" may be a "+" separated list of additional tuning options.
5834 The "shift=n" option indicates an offset shift position away
5835 from (0,0) (default 20). "final=x+y" specifies the final posi‐
5836 tion of the cursor at the end of the normal move sequence;
5837 default 30+30. "extra_move=x+y" means to do one more pointer
5838 move after "final" to x+y. "dt=n" sets the sleep time in mil‐
5839 liseconds between pointer moves (default: 40ms) "retry=n" speci‐
5840 fies the maximum number of retries if the grab state change
5841 fails. "ifneeded" means to not apply the pointer movements if
5842 the initial grab state is that of the desired final state.
5843 "nograbcheck" means to not check if the grab state changed as
5844 expected and only apply the pointer movements (default is to
5845 check the grab states.)
5846 If you do not specify "up", etc., to bcx_xattach nothing will be
5848 attempted and the command returns the string FAIL,NO_DIREC‐
5849 TION_SPECIFIED. If you do not specify "master_to_slave" or
5850 "M2S", etc., to bcx_xattach nothing will be attempted and the
5851 command returns the string FAIL,NO_MODE_CHANGE_SPECIFIED.
5852 Otherwise, the returned string will contain "DONE". It will be
5854 "DONE,GRAB_OK" if the grab state changed as expected (or if
5855 "ifneeded" was supplied and the initial grab state was already
5856 the desired one.) If the initial grab state was incorrect, but
5857 the final grab state was correct then it is
5858 "DONE,GRAB_FAIL_INIT". If the initial grab state was correct,
5859 but the final grab state was incorrect then it is
5860 "DONE,GRAB_FAIL_FINAL". If both are incorrect it will be
5861 "DONE,GRAB_FAIL". Under grab failure the string will be fol‐
5862 lowed by ":p1,k1-p2,k2" where p1,k1 indicates the initial
5863 pointer and keyboard grab states and p2,k2 the final ones. If
5864 GRAB_FAIL or GRAB_FAIL_FINAL occurs, the action will be retried
5865 up to 3 times; trying to reset the state and sleeping a bit
5866 between each try. Set retry=n to adjust the number of retries,
5867 zero to disable retries.
5868 Examples: -R bcx_xattach:down+M2S -R bcx_xattach:up+S2M -R
5870 bcx_xattach:up+S2M+nograbcheck+dt=30 -R bcx_xat‐
5871 tach:down+M2S+extra_move=100+100
5872 or use -Q instead of -R to retrieve the result text.
5874 End of the bcx_xattach:str description.
5876 The vncconnect(1) command from standard VNC distributions may
5878 also be used if string is prefixed with "cmd=" E.g. 'vncconnect
5879 cmd=stop'. Under some circumstances xprop(1) can used if it
5880 supports -set (see the FAQ).
5881 If "-connect /path/to/file" has been supplied to the running
5883 x11vnc server then that file can be used as a communication
5884 channel (this is the only way to remote control one of many
5885 x11vnc's polling the same X display) Simply run: 'x11vnc -con‐
5886 nect /path/to/file -remote ...' or you can directly write to
5887 the file via something like: "echo cmd=stop > /path/to/file",
5888 etc.
5889 -query variable
5891 Like -remote, except just query the value of variable. "-Q" is
5893 an alias for "-query". Multiple queries can be done by separat‐
5894 ing variables by commas, e.g. -query var1,var2. The results come
5895 back in the form ans=var1:value1,ans=var2:value2,... to the
5896 standard output. If a variable is read-only, it comes back with
5897 prefix "aro=" instead of "ans=".
5898 Some -remote commands are pure actions that do not make sense as
5900 variables, e.g. "stop" or "disconnect", in these cases the value
5901 returned is "N/A". To direct a query straight to the
5902 X11VNC_REMOTE property or connect file use "qry=..." instead of
5903 "cmd=..."
5904 ans= stop quit exit shutdown ping resend_cutbuffer resend_clip‐
5906 board resend_primary blacken zero refresh reset close disconnect
5907 id_cmd id sid waitmapped nowaitmapped clip flashcmap noflashcmap
5908 shiftcmap truecolor notruecolor overlay nooverlay overlay_cursor
5909 overlay_yescursor nooverlay_nocursor nooverlay_cursor noover‐
5910 lay_yescursor overlay_nocursor 8to24 no8to24 8to24_opts 24to32
5911 no24to32 visual scale scale_cursor viewonly noviewonly shared
5912 noshared forever noforever once timeout tightfilexfer notight‐
5913 filexfer ultrafilexfer noultrafilexfer rfbversion deny lock
5914 nodeny unlock avahi mdns zeroconf noavahi nomdns nozeroconf con‐
5915 nect proxy allowonce allow noipv6 ipv6 noipv4 ipv4 no6 6 local‐
5916 host nolocalhost listen lookup nolookup accept afteraccept gone
5917 shm noshm flipbyteorder noflipbyteorder onetile noonetile
5918 solid_color solid nosolid blackout xinerama noxinerama xtrap
5919 noxtrap xrandr noxrandr xrandr_mode rotate padgeom quiet q
5920 noquiet modtweak nomodtweak xkb noxkb capslock nocapslock
5921 skip_lockkeys noskip_lockkeys skip_keycodes sloppy_keys
5922 nosloppy_keys skip_dups noskip_dups add_keysyms noadd_keysyms
5923 clear_mods noclear_mods clear_keys noclear_keys clear_all
5924 clear_locks keystate remap repeat norepeat fb nofb bell nobell
5925 sendbell sel nosel primary noprimary setprimary nosetprimary
5926 clipboard noclipboard setclipboard nosetclipboard seldir cursor‐
5927 shape nocursorshape cursorpos nocursorpos cursor_drag nocur‐
5928 sor_drag cursor show_cursor noshow_cursor nocursor arrow xfixes
5929 noxfixes xdamage noxdamage xd_area xd_mem alphacut alphafrac
5930 alpharemove noalpharemove alphablend noalphablend xwarppointer
5931 xwarp noxwarppointer noxwarp always_inject noalways_inject but‐
5932 tonmap dragging nodragging ncache_cr noncache_cr
5933 ncache_no_moveraise noncache_no_moveraise ncache_no_dtchange
5934 noncache_no_dtchange ncache_no_rootpixmap noncache_no_rootpixmap
5935 ncache_reset_rootpixmap ncrp ncache_keep_anims non‐
5936 cache_keep_anims ncache_old_wm noncache_old_wm ncache_pad ncache
5937 noncache ncache_size debug_ncache nodebug_ncache wireframe_mode
5938 wireframe wf nowireframe nowf wireframelocal wfl nowireframelo‐
5939 cal nowfl wirecopyrect wcr nowirecopyrect nowcr scr_area
5940 scr_skip scr_inc scr_keys scr_term scr_keyrepeat scr_parms
5941 scrollcopyrect scr noscrollcopyrect noscr fixscreen noxrecord
5942 xrecord reset_record pointer_mode pm input_skip allinput
5943 noallinput input_eagerly noinput_eagerly input grabkbd nograbkbd
5944 grabptr nograbptr grabalways nograbalways grablocal client_input
5945 ssltimeout speeds wmdt debug_pointer dp nodebug_pointer nodp
5946 debug_keyboard dk nodebug_keyboard nodk keycode keysym ptr fake‐
5947 buttonevent sleep get_xprop set_xprop wininfo bcx_xattach defer‐
5948 update defer setdefer extra_fbur wait_ui wait_bog nowait_bog
5949 slow_fb xrefresh wait readtimeout nap nonap sb screen_blank fbpm
5950 nofbpm dpms nodpms clientdpms noclientdpms forcedpms noforcedpms
5951 noserverdpms serverdpms noultraext ultraext chatwindow
5952 nochatwindow chaton chatoff fs gaps grow fuzz snapfb nosnapfb
5953 rawfb uinput_accel uinput_thresh uinput_reset uinput_always pro‐
5954 gressive rfbport http nohttp httpport httpdir enablehttpproxy
5955 noenablehttpproxy alwaysshared noalwaysshared nevershared noal‐
5956 waysshared dontdisconnect nodontdisconnect desktop debug_xevents
5957 nodebug_xevents debug_xevents debug_xdamage nodebug_xdamage
5958 debug_xdamage debug_wireframe nodebug_wireframe debug_wireframe
5959 debug_scroll nodebug_scroll debug_scroll debug_tiles dbt node‐
5960 bug_tiles nodbt debug_tiles debug_grabs nodebug_grabs debug_sel
5961 nodebug_sel dbg nodbg macnosaver macsaver nomacnosaver macnowait
5962 macwait nomacnowait macwheel macnoswap macswap nomacnoswap mac‐
5963 noresize macresize nomacnoresize maciconanim macmenu macnomenu
5964 nomacmenu macuskbd nomacuskbd noremote
5965 aro= noop display vncdisplay icon_mode autoport loop loopbg
5967 desktopname guess_desktop guess_dbus http_url auth xauth users
5968 rootshift clipshift scale_str scaled_x scaled_y scale_numer
5969 scale_denom scale_fac_x scale_fac_y scaling_blend scal‐
5970 ing_nomult4 scaling_pad scaling_interpolate inetd privremote
5971 unsafe safer nocmds passwdfile unixpw unixpw_nis unixpw_list ssl
5972 ssl_pem sslverify stunnel stunnel_pem https httpsredir usepw
5973 using_shm logfile o flag rmflag rc norc h help V version lastmod
5974 bg sigpipe threads readrate netrate netlatency pipeinput clients
5975 client_count pid ext_xtest ext_xtrap ext_xrecord ext_xkb
5976 ext_xshm ext_xinerama ext_overlay ext_xfixes ext_xdamage
5977 ext_xrandr rootwin num_buttons button_mask mouse_x mouse_y
5978 grab_state pointer_pos pointer_x pointer_y pointer_same
5979 pointer_root pointer_mask bpp depth indexed_color dpy_x dpy_y
5980 wdpy_x wdpy_y off_x off_y cdpy_x cdpy_y coff_x coff_y rfbauth
5981 passwd viewpasswd
5982 -QD variable
5984 Just like -query variable, but returns the default value for
5986 that parameter (no running x11vnc server is consulted)
5987 -sync
5989 By default -remote commands are run asynchronously, that is, the
5991 request is posted and the program immediately exits. Use -sync
5992 to have the program wait for an acknowledgement from the x11vnc
5993 server that command was processed (somehow). On the other hand
5994 -query requests are always processed synchronously because they
5995 have to wait for the answer.
5996 Also note that if both -remote and -query requests are supplied
5998 on the command line, the -remote is processed first (syn‐
5999 chronously: no need for -sync), and then the -query request is
6000 processed in the normal way. This allows for a reliable way to
6001 see if the -remote command was processed by querying for any new
6002 settings. Note however that there is timeout of a few seconds
6003 (see the next paragraph) so if the x11vnc takes longer than that
6004 to process the requests the requester will think that a failure
6005 has taken place.
6006 The default is to wait 3.5 seconds. Or if cmd=stop only 1.0
6008 seconds. If cmd matches 'script:' then it will wait up to 10.0
6009 seconds. Set X11VNC_SYNC_TIMEOUT to the number of seconds you
6010 want it to wait.
6011 -query_retries str
6013 If a query fails to get a response from an x11vnc server, retry
6015 up to n times. str is specified as n[:t][/match] Optionally
6016 the delay between tries may be specified by "t" a floating point
6017 time (default 0.5 seconds.) Note: the response is not checked
6018 for validity or whether it corresponds to the query sent. The
6019 query "ping:mystring" may be used to help uniquely identify the
6020 query. Optionally, a matching string after a "/" will be used
6021 to check the result text. Up to n retries will take place until
6022 the matching string is found in the output text. If the match
6023 string is never found the program's exit code is 1; if the match
6024 is found it exits with 0. Note that there may be stdout printed
6025 for each retry (i.e. multiple lines printed out to stdout.)
6026 Example: -query_retries 4:1.5/grab_state
6027 -remote_prefix str
6029 Enable a remote-control communication channel for connected VNC
6031 clients. str is a non-empty string. If a VNC client sends rfb‐
6032 CutText having the prefix str then the part after it is pro‐
6033 cessed as though it were sent via 'x11vnc -remote ...'. If it
6034 begins with neither 'cmd=' nor 'qry=' then 'qry=' is assumed.
6035 Any corresponding output text for that remote control command is
6036 sent back to all client as rfbCutText. The returned output is
6037 also prefixed with str. Example: -remote_prefix DO_THIS:
6038 Note that enabling -remote_prefix allows the remote VNC viewers
6040 to run x11vnc -remote commands. Do not use this option if they
6041 are not to be trusted.
6042 -noremote, -yesremote
6044 Do not process any remote control commands or queries. Do
6046 process remote control commands or queries. Default: -yesremote
6047 A note about security wrt remote control commands. If someone
6049 can connect to the X display and change the property
6050 X11VNC_REMOTE, then they can remotely control x11vnc. Normally
6051 access to the X display is protected. Note that if they can
6052 modify X11VNC_REMOTE on the X server, they have enough permis‐
6053 sions to also run their own x11vnc and thus have complete con‐
6054 trol of the desktop. If the "-connect /path/to/file" channel
6055 is being used, obviously anyone who can write to /path/to/file
6056 can remotely control x11vnc. So be sure to protect the X dis‐
6057 play and that file's write permissions. See -privremote below.
6058 If you are paranoid and do not think -noremote is enough, to
6060 disable the X11VNC_REMOTE property channel completely use
6061 -novncconnect, or use the -safer option that shuts many things
6062 off.
6063 -unsafe
6065 A few remote commands are disabled by default (currently:
6067 id:pick, accept:<cmd>, gone:<cmd>, and rawfb:setup:<cmd>)
6068 because they are associated with running external programs. If
6069 you specify -unsafe, then these remote-control commands are
6070 allowed. Note that you can still specify these parameters on
6071 the command line, they just cannot be invoked via remote-con‐
6072 trol.
6073 -safer
6075 Equivalent to: -novncconnect -noremote and prohibiting -gui and
6077 the -connect file. Shuts off communcation channels.
6078 -privremote
6080 Perform some sanity checks and disable remote-control commands
6082 if it appears that the X DISPLAY and/or connectfile can be
6083 accessed by other users. Once remote-control is disabled it
6084 cannot be turned back on.
6085 -nocmds
6087 No external commands (e.g. system(3) , popen(3) , exec(3) )
6089 will be run at all.
6090 -allowedcmds list
6092 list contains a comma separated list of the only external com‐
6094 mands that can be run. The full list of associated options is:
6095 stunnel, ssl, unixpw, WAIT, zeroconf, id, accept, afteraccept,
6097 gone, pipeinput, v4l-info, rawfb-setup, dt, gui, ssh,
6098 storepasswd, passwdfile, custom_passwd, findauth, crash.
6099 See each option's help to learn the associated external command.
6101 Note that the -nocmds option takes precedence and disables all
6102 external commands.
6103 -deny_all
6105 For use with -remote nodeny: start out denying all incoming
6107 clients until "-remote nodeny" is used to let them in.
6108 These options are passed to LibVNCServer:
6110 -rfbport port
6112 TCP port for RFB protocol
6114 -rfbwait time
6116 max time in ms to wait for RFB client
6118 -rfbauth passwd-file
6120 use authentication on RFB protocol (use 'x11vnc -storepasswd
6122 pass file' to create a password file)
6123 -rfbversion 3.x
6125 Set the version of the RFB we choose to advertise
6127 -permitfiletransfer
6129 permit file transfer support
6131 -passwd plain-password
6133 use authentication (use plain-password as password, USE AT YOUR
6135 RISK)
6136 -deferupdate time
6138 time in ms to defer updates (default 40)
6140 -deferptrupdate time
6142 time in ms to defer pointer updates (default none)
6144 -desktop name
6146 VNC desktop name (default "LibVNCServer")
6148 -alwaysshared
6150 always treat new clients as shared
6152 -nevershared
6154 never treat new clients as shared
6156 -dontdisconnect
6158 don't disconnect existing clients when a new non-shared connec‐
6160 tion comes in (refuse new connection instead)
6161 -httpdir dir-path
6163 enable http server using dir-path home
6165 -httpport portnum
6167 use portnum for http connection
6169 -enablehttpproxy
6171 enable http proxy support
6173 -progressive height
6175 enable progressive updating for slow links
6177 -listen ipaddr
6179 listen for connections only on network interface with addr
6181 ipaddr. '-listen localhost' and hostname work too.
6182 libvncserver-tight-extension options:
6184 -disablefiletransfer
6186 disable file transfer
6188 -ftproot string
6190 set ftp root
6192
6194 $HOME/.x11vncrc, $HOME/.Xauthority
6195
6197 DISPLAY, XAUTHORITY, HOME
6198 The following are set for the auxiliary commands run by -accept, -gone
6200 and other cases:
6201 RFB_CLIENT_IP, RFB_CLIENT_PORT, RFB_SERVER_IP, RFB_SERVER_PORT,
6203 RFB_X11VNC_PID, RFB_CLIENT_ID, RFB_CLIENT_COUNT, RFB_MODE RFB_STATE
6204 RFB_LOGIN_VIEWONLY RFB_LOGIN_TIME RFB_CURRENT_TIME RFB_USERNAME
6205 RFB_SSL_CLIENT_CERT
6206
6208 vncviewer(1), vncpasswd(1), vncconnect(1), vncserver(1), Xvnc(1),
6209 xev(1), xdpyinfo(1), xwininfo(1), xprop(1), xmodmap(1), xrandr(1),
6210 Xserver(1), xauth(1), xhost(1), Xsecurity(7), xmessage(1), XGetIm‐
6211 age(3X11), ipcrm(1), inetd(1), xdm(1), gdm(1), kdm(1), ssh(1), stun‐
6212 nel(8), su(1), http://www.tightvnc.com, http://www.realvnc.com,
6213 http://www.karlrunge.com/x11vnc/, http://www.karlrunge.com/x11vnc/#faq,
6214 https://github.com/LibVNC/x11vnc
6215
6217 x11vnc was written by Karl J. Runge <runge@karlrunge.com>, it is part
6218 of the LibVNCServer project <https://github.com/LibVNC/libvncserver>.
6219 This manual page is based one the one written by Ludovic Drolez
6220 <ldrolez@debian.org>, for the Debian project (both may be used by oth‐
6221 ers).
6222x11vnc February 2018 X11VNC(1)